Scene

Reference for Scene, SceneSnapshot, SceneVersions, StructureState and EndpointState - the logical world and its per-time snapshots.

These classes live in witwin.core.scene and are exported from witwin.core. For a walkthrough, see Build a scene and Update a scene.

from witwin.core import Scene, SceneSnapshot, SceneVersions, StructureState, EndpointState

Scene #

class Scene(
    *,
    structures=(),
    endpoints=(),
    versions: SceneVersions | None = None,
    topology_version: int = 0,
    geometry_version: int = 0,
    material_version: int = 0,
    assignment_version: int = 0,
    metadata: Mapping[str, Any] | None = None,
)

The canonical logical world: structures, endpoints and four version counters. Immutable (frozen dataclass). All arguments are keyword-only.

structuresIterable[Structure]default ()

The structures. Stored as a tuple. Every item must be a Structure, otherwise TypeError.

endpointsIterable[AntennaState]default ()

Transmitters, receivers and receiver grids. Every item must be an AntennaState (a ReceiverGrid is one), otherwise TypeError.

versionsSceneVersions | Nonedefault None

Authored version counters. When given, the four *_version arguments are ignored.

topology_versionintdefault 0

Authored topology counter, used when versions is None. Must be at least 0. The same applies to geometry_version, material_version and assignment_version.

metadataMapping[str, Any] | Nonedefault None

Free-form data for tools. Stored as a read-only mapping.

Raises ValueError when IDs collide: duplicate StructureId, AssignmentId, SurfaceId, PrimitiveId or AntennaId, a negative ID, or one MaterialId used by two different material objects. See Identity and versions.

Attributes #

Attribute	Type	Meaning
`structures`	`tuple[Structure, ...]`	The structures, in the order given.
`endpoints`	`tuple[AntennaState, ...]`	The endpoints, in the order given.
`metadata`	`Mapping[str, Any]`	Read-only metadata.
`assignments`	`tuple[MaterialAssignment, ...]`	One assignment per structure (property).
`topology_version`, `geometry_version`, `material_version`, `assignment_version`	`int`	The current versions (properties, computed on each read).
`versions`	`SceneVersions`	All four versions in one object (property).

Scene.structure #

structure(structure_id: StructureId | int) -> Structure

Returns the structure with that ID. Raises KeyError if there is none.

Scene.with_structures #

with_structures(structures) -> Scene

Returns a scene with a new structure list and the same endpoints and metadata. Advances the topology and assignment counters by 1.

Scene.with_structure_geometry #

with_structure_geometry(structure_id: StructureId | int, geometry, *, topology_changed: bool | None = None) -> Scene

Returns a scene in which one structure has a new geometry. Advances the geometry counter, and the topology counter when the topology changed.

structure_idStructureId | intrequired

The structure to change. Raises KeyError if unknown.

geometryGeometrySpecrequired

The new geometry.

topology_changedbool | Nonedefault None

None infers it: the topology changed when the geometry class differs, or when the old or new geometry has a face tensor and the two are not the same unchanged tensor. True forces a topology change. False declares none; it raises ValueError when Core detects one.

Scene.with_material #

with_material(material_id: MaterialId | int, material: MaterialSpec) -> Scene

Replaces the material of every structure that uses material_id. Advances the material counter.

Raises ValueError if material has a material_id attribute that differs from material_id, and KeyError if no structure uses material_id.

from witwin.core import Box, PhysicalMaterial, Scene, Structure
 
concrete = PhysicalMaterial(eps_r=5.24, material_id=1)
scene = Scene(structures=[Structure(Box(), concrete)])
wet = scene.with_material(1, PhysicalMaterial(eps_r=7.0, material_id=1, version=1))
print(wet.structures[0].material.eps_r)  # 7.0

Scene.with_structure_material #

with_structure_material(
    structure_id: StructureId | int,
    material: MaterialSpec,
    *,
    material_id: MaterialId | int | None = None,
    phase_screen: PhaseScreen | None = None,
) -> Scene

Binds one structure to another material and phase screen. Advances the assignment counter, and the material counter when the material is new to the scene.

structure_idStructureId | intrequired

The structure to rebind. Raises KeyError if unknown.

materialMaterialSpecrequired

The new material.

material_idMaterialId | int | Nonedefault None

The ID to use. None takes material.material_id; raises ValueError if the material has none.

phase_screenPhaseScreen | Nonedefault None

The phase screen for the structure's surface. None removes an existing one.

Raises ValueError if the resolved ID already belongs to a different material object in the scene; use with_material to change a shared material.

Scene.with_endpoints #

with_endpoints(endpoints) -> Scene

Returns a scene with a new endpoint list. Advances the geometry counter.

Scene.snapshot #

snapshot(time_s: ScalarLike = 0.0) -> SceneSnapshot

Returns a static SceneSnapshot at time_s (seconds, a number or a 0-d tensor). No structure or endpoint has motion. Its versions equal the scene's.

SceneSnapshot #

class SceneSnapshot(
    *,
    time_s: ScalarLike,
    topology_version: int,
    geometry_version: int,
    material_version: int,
    assignment_version: int,
    structures,
    endpoints=(),
    metadata: Mapping[str, Any] | None = None,
    source_scene: Scene | None = None,
    dynamic_revision: int | None = None,
    dynamic_sources=(),
)

The world at one time: what solvers read. You normally get one from Scene.snapshot or DynamicScene.at rather than building it. Immutable.

Attribute	Type	Meaning
`time_s`	`float` or 0-d tensor	The snapshot time in seconds. A tensor with more than 0 dimensions raises `ValueError`.
`structures`	`tuple[StructureState, ...]`	Each structure with its optional motion and deformation.
`endpoints`	`tuple[EndpointState, ...]`	Each endpoint with its optional motion.
`metadata`	`Mapping[str, Any]`	Read-only metadata, copied from the scene.
`topology_version`, `geometry_version`, `material_version`, `assignment_version`, `versions`	`int`, `SceneVersions`	The snapshot's versions (properties).

For a snapshot of a scene, the topology, material and assignment versions are the scene's. The geometry version is the scene's for a static snapshot. For a dynamic snapshot it also covers the time, the motion states and the motion sources, and it changes when one of their tensors changes in place.

SceneVersions #

@dataclass(frozen=True, slots=True)
class SceneVersions:
    topology: int = 0
    geometry: int = 0
    material: int = 0
    assignment: int = 0

Four version values. Each must be at least 0, otherwise ValueError. scene.versions returns one; compare two for equality.

SceneVersions.advanced #

advanced(**increments: int) -> SceneVersions

Returns a copy with the named fields increased, for example versions.advanced(geometry=1). Raises TypeError for an unknown field name and ValueError for a negative increment.

StructureState #

@dataclass(frozen=True, slots=True)
class StructureState:
    structure: Structure
    rigid_motion: RigidMotion | None = None
    deformation: DeformationState | None = None

A structure in a snapshot, with the motion and deformation at that time. structure_id (property) returns structure.structure_id.

EndpointState #

@dataclass(frozen=True, slots=True)
class EndpointState:
    antenna: AntennaState
    rigid_motion: RigidMotion | None = None

An endpoint in a snapshot, with its motion at that time.