WiTwin Core is the shared logical-world and geometry package of the WiTwin stack. It defines solver-neutral scene, material, antenna, dynamics, snapshot, and geometry contracts. Solver packages compile those contracts into their own runtime resources and results.
Core supports CPython 3.10-3.14 and PyTorch 2.10 or newer.
pip install witwinCore ships as a platform-independent py3-none-any wheel and contains no C++ or
CUDA sources. Mesh SDF evaluation always has a PyTorch implementation. Solver
packages may register their own optional accelerators; Maxwell owns and packages
the CUDA mesh-SDF implementation used by Maxwell workflows.
- Canonical
Scene,SceneSnapshot,Structure, and stable logical IDs - Solver-neutral
PhysicalMaterial, layers, roughness, dispersion, and phase-screen assignments - Logical TX/RX antenna state, planar receiver grids, rigid motion, trajectories, and deformation state
- Stable structure, surface, material, assignment, primitive, and antenna identities
- Typed mesh UV topology and explicit finite/perfect conductor material identity
- Runtime-checkable
GeometrySpecandMaterialSpeccontracts - Shared analytic geometry primitives and differentiable mesh/SDF utilities
- Granular topology, geometry, material, and assignment versions
Core owns the logical Scene; each solver owns its compiled scene lifecycle, native resources, caches, and results. Radar-specific SMPL geometry lives in witwin.radar.geometry; Maxwell-specific PolySlab geometry lives in witwin.maxwell.geometry.
The supported public API is the set of names exported by witwin.core.__all__.
Applications should import contracts, geometry types, identity allocators, and
math utilities directly from witwin.core. CI locks this symbol set so adding,
removing, or renaming a public symbol requires an intentional API change.
Modules and names outside that export set are implementation details and may be
reorganized between releases.
Antenna orientation maps endpoint-local coordinates into world coordinates.
Euler orientation is (yaw, pitch, roll) in radians with intrinsic Z-Y-X
rotations; quaternion orientation is scalar-first (w, x, y, z).
Polarization and antenna element positions are endpoint-local, while
ReceiverGrid.x_axis and y_axis are world-frame grid directions. Core's
Torch rotation and projection helpers preserve autograd.
Snapshot deformation is composed before motion: absolute deformation vertices
replace authored local mesh vertices, or offsets are added to them; authored
geometry transforms are applied next. RigidMotion.rotation then left-composes
the authored rotation and its world-frame translation is added last. Endpoint
motion follows the same rule after antenna-local orientation.
PhysicalMaterial(conductor_model="perfect"), or the equivalent
PhysicalMaterial.perfect_conductor(), carries explicit PEC identity while
keeping finite logical material parameters. Solver-owned compilers map that
identity to their native material ABI; Core does not encode native model IDs or
effective conductivity constants.
Mesh.vertices,Mesh.faces,Mesh.world_vertices, andMesh.bounds_worldare tensor-valued contracts.bounds_worldhas shape(2, 3), with minimum coordinates in row 0 and maximum coordinates in row 1.- Tensor-authored geometry is never implicitly moved to the requested device. Place authored tensors explicitly before construction; conflicting devices fail loudly.
- CUDA-authored meshes do not run host topology diagnostics or build a host BVH.
fill_mode="auto"therefore requires an explicit topology decision before an SDF query. Materialis removed.PhysicalMaterialis the only public name for the material contract; the two were aliases of one class. Replacefrom witwin.core import Materialwithfrom witwin.core import PhysicalMaterial.StructureandMaterialAssignmentnow live inwitwin.core.structurerather thanwitwin.core.material, which keeps only material specifications. Both remain exported fromwitwin.core, so package-level imports are unaffected.- Continuous physical quantities are annotated
ScalarLike(float | torch.Tensor) instead ofAny.ScalarLikeandComplexLikeare exported fromwitwin.core. This is a typing change only; the accepted runtime values are unchanged. witwin.core.identitydocuments its two allocation modes. Usereserve_*_id(value)whenever identities must be reproducible across processes;new_*_id()draws from a process-global counter and is order-dependent.
