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.
CPython 3.10-3.14, PyTorch 2.10 or newer, and an NVIDIA GPU are supported for the main WiTwin simulation workflows.
pip install witwinRelease wheels are built for Linux x86_64 and Windows x86_64 with CUDA 12.8. Each platform wheel carries one PyTorch Stable ABI native library built against PyTorch 2.10 and reused across supported Python and PyTorch versions; CI currently verifies PyTorch 2.10-2.12. The fat binaries contain native code for compute capabilities 7.0, 7.5, 8.0, 8.6, 8.9, 9.0, 10.0, 10.1, and 12.0, plus compute 12.0 PTX for forward-compatible Blackwell execution. This includes native coverage for RTX 2080-class Turing GPUs and current data-center and RTX/RTX PRO Blackwell families.
Linux wheels target manylinux_2_35_x86_64. The installed NVIDIA driver must support the CUDA 12.x runtime supplied by PyTorch; the CUDA toolkit is only needed for source/JIT builds.
For full CUDA 12.8 and Blackwell support, use at least driver 570.26 on Linux or 570.65 on Windows. Pre-Blackwell systems can use NVIDIA's CUDA 12.x minor-version compatibility floor (525.60.13 on Linux or 528.33 on Windows), subject to NVIDIA's compatibility-mode feature limits.
- 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.
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.
