deformable 0.1.0__py3-none-win_amd64.whl

deformable/simulation.py

@@ -0,0 +1,468 @@
+"""The simulation a host drives frame by frame, with its value types.
+
+Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The simulation's
+scale converts host lengths to simulation lengths.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import dataclasses
+import numbers
+from collections.abc import Callable, Sequence
+from typing import Any, NamedTuple
+
+from . import conversion, library, native
+from .cancel_flag import CancelFlag, cancel_handle
+from .errors import Status, check
+from .handles import OwnedHandle
+from .meshes import tetrahedral_mesh_view
+from .values import StepOutcome, Vector3
+
+_UNIFORM = 0
+_PER_TETRAHEDRON = 1
+
+
+@dataclasses.dataclass(frozen=True)
+class MaterialParameters:
+    """Material values as a host gives them, before the library clamps them."""
+
+    youngs_modulus: float
+    """Young's modulus E, in pascals in simulation units."""
+    poissons_ratio: float
+    """Poisson's ratio ν, unitless."""
+    density: float
+    """Mass per unit volume; a tetrahedron weighs density·V."""
+    toughness: float
+    """Fracture threshold on half the largest separation-tensor eigenvalue; 0 or negative means unbreakable."""
+    youngs_damping: float
+    """Stiffness-proportional damping; the engine uses alpha = youngs_damping / youngs_modulus."""
+    yield_strain: float
+    """Plastic flow starts when the elastic strain norm exceeds this."""
+    maximum_yield: float
+    """Bound on the plastic strain norm; 0 resets the plastic strain every solve."""
+    creep_fraction: float
+    """Fraction, 0 to 1, of the elastic strain added to the plastic strain once per solve, not per second, while its
+    norm exceeds yield_strain; 0 disables plasticity."""
+    wake_up_radius: float
+    """Radius of the impact wake flood fill, in simulation units."""
+    friction: float
+    """Coulomb friction coefficient."""
+
+    @classmethod
+    def default(cls, **changes: float) -> MaterialParameters:
+        """The values a new material starts from, with the given fields changed."""
+        structure = native.MaterialParameters()
+        check(library.load().deformable_material_parameters_default(ctypes.byref(structure)))
+        return dataclasses.replace(cls._from_native(structure), **changes)
+
+    @classmethod
+    def presets(cls) -> list[MaterialPreset]:
+        """The presets the library ships, in its order: from the softest to the metals."""
+        functions = library.load()
+        return [cls._preset_at(functions, index) for index in range(functions.deformable_material_preset_count())]
+
+    @classmethod
+    def preset(cls, name: str) -> MaterialParameters | None:
+        """The preset with this name, or None. The name must match exactly, case included ("unbreakable_rubber")."""
+        if not isinstance(name, str):
+            raise TypeError(f"a preset name is a str, not {type(name).__name__}")
+        if "\0" in name:
+            return None
+        # Lone surrogates pass through as bytes that are not UTF-8, which no preset name matches.
+        encoded = ctypes.create_string_buffer(name.encode("utf-8", errors="surrogatepass"))
+        structure = native.MaterialParameters()
+        code = library.load().deformable_material_preset_find(encoded, ctypes.byref(structure))
+        if code == Status.INVALID_ARGUMENT:
+            return None
+        check(code)
+        return cls._from_native(structure)
+
+    @classmethod
+    def _preset_at(cls, functions: ctypes.CDLL, index: int) -> MaterialPreset:
+        name = ctypes.POINTER(ctypes.c_char)()
+        structure = native.MaterialParameters()
+        check(functions.deformable_material_preset(index, ctypes.byref(name), ctypes.byref(structure)))
+        return MaterialPreset(ctypes.string_at(name).decode("utf-8"), cls._from_native(structure))
+
+    @classmethod
+    def _from_native(cls, structure: native.MaterialParameters) -> MaterialParameters:
+        return cls(**{field.name: getattr(structure, field.name) for field in dataclasses.fields(cls)})
+
+    def _native(self) -> native.MaterialParameters:
+        return native.MaterialParameters(**dataclasses.asdict(self))
+
+
+class MaterialPreset(NamedTuple):
+    """A material preset the library ships: its name and its values."""
+
+    name: str
+    """The preset's lowercase snake_case name, such as "concrete" or "unbreakable_rubber"."""
+    parameters: MaterialParameters
+    """The values, each inside its clamp range, so add_material keeps them as they are."""
+
+
+@dataclasses.dataclass(frozen=True)
+class ObjectOptions:
+    """The per-object settings."""
+
+    self_collision: bool
+    """The object's colliders test its own faces against each other."""
+    disabled: bool
+    """The object is created disabled."""
+
+    @classmethod
+    def default(cls, **changes: bool) -> ObjectOptions:
+        """The object defaults (self-collision on, enabled), with the given fields changed."""
+        structure = native.ObjectOptions()
+        check(library.load().deformable_object_options_default(ctypes.byref(structure)))
+        values = {"self_collision": bool(structure.self_collision), "disabled": bool(structure.disabled)}
+        return cls(**{**values, **changes})
+
+    def _native(self) -> native.ObjectOptions:
+        return native.ObjectOptions(bool(self.self_collision), bool(self.disabled))
+
+
+class GlueParameters(NamedTuple):
+    """The spring and damping of glue; a zero spring constant or damping coefficient takes 4905 or 2452.5, each on
+    its own."""
+
+    spring_constant: float
+    """The spring constant k."""
+    damping_coefficient: float
+    """The damping coefficient c."""
+
+
+class Plane(NamedTuple):
+    """A bounding plane of a convex region: the inside is normal · p + offset <= 0."""
+
+    normal: Sequence[float]
+    """The outward normal n, of any length."""
+    offset: float
+    """The offset d."""
+
+
+@dataclasses.dataclass(frozen=True)
+class ConvexRegion:
+    """A convex region: the points inside all of its planes; with no plane it holds every point."""
+
+    planes: Sequence[Plane]
+    """The bounding planes, each a Plane or a (normal, offset) pair."""
+
+    def contains(self, point: Sequence[float]) -> bool:
+        """True when normal · point + offset <= 0 for every plane: the test a host runs for passive regions."""
+        inside = native.Boolean()
+        check(
+            library.load().deformable_convex_region_contains(
+                ctypes.byref(self._native()), conversion.vector3(point), ctypes.byref(inside)
+            )
+        )
+        return bool(inside.value)
+
+    def _native(self) -> native.ConvexRegion:
+        planes = conversion.structure_array(
+            self.planes, native.Plane, lambda plane: native.Plane(conversion.vector3(plane[0]), plane[1])
+        )
+        return native.ConvexRegion(planes, len(planes))
+
+
+class DrivenVertex(NamedTuple):
+    """A vertex of an object driven to a target, in host units."""
+
+    vertex: int
+    """The vertex, an index into the object's nodes."""
+    target: Sequence[float]
+    """Where the vertex is at the end of the next step, in host units."""
+
+
+class StepReport(NamedTuple):
+    """The result of a Simulation.step call."""
+
+    substeps_run: int
+    """The number of substeps simulated."""
+    outcome: StepOutcome
+    """What the call did."""
+
+
+@dataclasses.dataclass(frozen=True)
+class TetrahedronState:
+    """The output record of one tetrahedron."""
+
+    corners: tuple[Vector3, Vector3, Vector3, Vector3]
+    """The current corner positions in host units."""
+    island: int
+    """The id of the tetrahedron's island, or 0 while it has none."""
+    strain_measure: float
+    """The squared norm of the total co-rotated strain, plastic part included."""
+    flags: int
+    """The exposed-face bits 0-3 reported so far (sticky), plus NODE_REPLACED."""
+
+    def face_centroid(self, face: int) -> Vector3:
+        """The centroid of face face (0-3, the face opposite corner face)."""
+        return self._face_query("deformable_tetrahedron_state_face_centroid", face)
+
+    def face_normal(self, face: int) -> Vector3:
+        """The outward unit normal of face face (0-3) of a positively oriented (left-handed) state; zero for a face of
+        zero area."""
+        return self._face_query("deformable_tetrahedron_state_face_normal", face)
+
+    def _face_query(self, function_name: str, face: int) -> Vector3:
+        result = native.Vector3()
+        function = getattr(library.load(), function_name)
+        check(function(ctypes.byref(self._native()), conversion.unsigned(face), ctypes.byref(result)))
+        return conversion.from_vector3(result)
+
+    def _native(self) -> native.TetrahedronState:
+        corners = (native.Vector3 * 4)(*(conversion.vector3(corner) for corner in self.corners))
+        return native.TetrahedronState(corners, self.island, self.strain_measure, self.flags)
+
+    @classmethod
+    def _from_native(cls, structure: native.TetrahedronState) -> TetrahedronState:
+        corners = tuple(conversion.from_vector3(corner) for corner in structure.corners)
+        return cls(corners, structure.island, structure.strain_measure, structure.flags)
+
+
+class FaceEvent(NamedTuple):
+    """A tetrahedron fracture changed in the last step and the faces it now shares with no other tetrahedron."""
+
+    tetrahedron: int
+    """The tetrahedron's index in its object's mesh."""
+    exposed_faces: int
+    """Bit k is set when face k, opposite corner k, is exposed; original boundary faces count as exposed."""
+
+
+class SimulationStatistics(NamedTuple):
+    """The solver, contact and island counters."""
+
+    systems: int
+    """Systems solved so far."""
+    conjugate_gradient_updates: int
+    """Conjugate gradient solution updates summed over every solve so far."""
+    contacts: int
+    """Live contacts, glue contacts included."""
+    islands: int
+    """Islands, awake and asleep."""
+
+
+def tetrahedron_materials(materials: int | Sequence[int] | Any) -> native.TetrahedronMaterials:
+    """One material handle for every tetrahedron, or one handle per tetrahedron in mesh order."""
+    if isinstance(materials, numbers.Integral):
+        return native.TetrahedronMaterials(_UNIFORM, conversion.unsigned(materials), None, 0)
+    per_tetrahedron = conversion.index_array(materials, "materials")
+    return native.TetrahedronMaterials(_PER_TETRAHEDRON, 0, per_tetrahedron, len(per_tetrahedron))
+
+
+class Simulation(OwnedHandle):
+    """One scene: gravity (0, -9.81, 0), scale 1 and min(available parallelism, 16) workers when created.
+
+    Use it in a with block, or call close(), to free it at a known point. It may move between threads; calls on one
+    simulation from several threads run one at a time, and close() waits for the call in flight. Object and material
+    handles are ints counting up from 0 in creation order.
+    """
+
+    _destroy_name = "deformable_simulation_destroy"
+    _description = "simulation"
+    _one_call_at_a_time = True
+
+    def __init__(self) -> None:
+        super().__init__("deformable_simulation_create")
+
+    def set_scale(self, scale: float) -> None:
+        """Sets the host length unit → simulation unit factor, in [0.001, 1000]; it applies to later conversions."""
+        self._call("deformable_simulation_set_scale", scale)
+
+    def set_gravity(self, gravity: Sequence[float]) -> None:
+        """Sets the gravity in simulation units, not scaled."""
+        self._call("deformable_simulation_set_gravity", conversion.vector3(gravity))
+
+    def set_worker_count(self, count: int) -> None:
+        """Sets the worker count, at least 1 and including the calling thread; results do not depend on it."""
+        self._call("deformable_simulation_set_worker_count", conversion.size(count))
+
+    def add_material(self, parameters: MaterialParameters) -> int:
+        """Creates a material, each value clamped to its range, and returns its handle."""
+        material = native.Index()
+        self._call("deformable_simulation_add_material", ctypes.byref(parameters._native()), ctypes.byref(material))
+        return material.value
+
+    def set_material(self, material: int, parameters: MaterialParameters) -> None:
+        """Rewrites a material's values; the objects using it take them before the next step's substeps."""
+        self._call(
+            "deformable_simulation_set_material", conversion.unsigned(material), ctypes.byref(parameters._native())
+        )
+
+    def add_object(self, mesh: Any, materials: int | Sequence[int] | Any, options: ObjectOptions | None = None) -> int:
+        """Creates an object from a tetrahedral mesh in world space and host units, and returns its handle.
+
+        materials is one material handle for every tetrahedron or one per tetrahedron; options defaults to
+        ObjectOptions.default(). A degenerate tetrahedron or a face shared by three tetrahedrons raises a
+        DeformableError naming it, and nothing is created then.
+        """
+        options = ObjectOptions.default() if options is None else options
+        object_handle = native.Index()
+        self._call(
+            "deformable_simulation_add_object",
+            ctypes.byref(tetrahedral_mesh_view(mesh)),
+            ctypes.byref(tetrahedron_materials(materials)),
+            ctypes.byref(options._native()),
+            ctypes.byref(object_handle),
+        )
+        return object_handle.value
+
+    def set_object_material(self, object_handle: int, materials: int | Sequence[int] | Any) -> None:
+        """Reassigns an object's materials before the next step's substeps; it rebuilds islands and wakes nothing."""
+        self._call(
+            "deformable_simulation_set_object_material",
+            conversion.unsigned(object_handle),
+            ctypes.byref(tetrahedron_materials(materials)),
+        )
+
+    def remove_object(self, object_handle: int) -> None:
+        """Deletes an object; its contacts and glue are freed and its handle becomes unknown."""
+        self._call("deformable_simulation_remove_object", conversion.unsigned(object_handle))
+
+    def set_object_disabled(self, object_handle: int, disabled: bool) -> None:
+        """Disables or enables an object; a disabled object keeps its outputs and ignores forces and driving."""
+        self._call("deformable_simulation_set_object_disabled", conversion.unsigned(object_handle), bool(disabled))
+
+    def set_self_collision(self, object_handle: int, enabled: bool) -> None:
+        """Sets or clears an object's self-collision; an island takes the change at its next rebuild."""
+        self._call("deformable_simulation_set_self_collision", conversion.unsigned(object_handle), bool(enabled))
+
+    def set_never_sleep(self, object_handle: int, node: int, enabled: bool) -> None:
+        """Sets or clears the never-sleep flag of a node: its island never sleeps, and setting it wakes the node."""
+        self._call(
+            "deformable_simulation_set_never_sleep",
+            conversion.unsigned(object_handle),
+            conversion.unsigned(node),
+            bool(enabled),
+        )
+
+    def set_glue_all(self, parameters: GlueParameters | None) -> None:
+        """Glues each new object to every other enabled object where they overlap; None turns glue all off."""
+        glue = None if parameters is None else ctypes.byref(native.GlueParameters(*parameters))
+        self._call("deformable_simulation_set_glue_all", glue)
+
+    def add_glue_region(self, region: ConvexRegion, members: Sequence[int], parameters: GlueParameters) -> None:
+        """Glues each new member to every other enabled member through their tetrahedrons with a vertex inside every
+        plane of region; plane offsets are in host units."""
+        member_handles = conversion.index_array(members, "members")
+        self._call(
+            "deformable_simulation_add_glue_region",
+            ctypes.byref(region._native()),
+            member_handles,
+            len(member_handles),
+            ctypes.byref(native.GlueParameters(*parameters)),
+        )
+
+    def drive(self, object_handle: int, vertices: Sequence[DrivenVertex]) -> None:
+        """Drives the listed vertices toward their targets (host units) from the next step on, until the next call
+        for the object; previously driven vertices not listed are released with their last driven velocity."""
+        driven = conversion.structure_array(
+            vertices,
+            native.DrivenVertex,
+            lambda vertex: native.DrivenVertex(conversion.unsigned(vertex[0]), conversion.vector3(vertex[1])),
+        )
+        self._call("deformable_simulation_drive", conversion.unsigned(object_handle), driven, len(driven))
+
+    def add_force(self, object_handle: int, node: int, force: Sequence[float]) -> None:
+        """Queues a force in simulation units on a node for every substep of the next step; calls add up."""
+        self._call(
+            "deformable_simulation_add_force",
+            conversion.unsigned(object_handle),
+            conversion.unsigned(node),
+            conversion.vector3(force),
+        )
+
+    def step(self, time: float, substeps: int, cancel: CancelFlag | None = None) -> StepReport:
+        """Advances to time (seconds) in substeps equal substeps. The first call only records the time.
+
+        A cancel flag set from another thread stops the step between two substeps, after at least one.
+        """
+        report = native.StepReport()
+        with cancel_handle(cancel) as cancel_address:
+            self._call(
+                "deformable_simulation_step", time, conversion.unsigned(substeps), cancel_address, ctypes.byref(report)
+            )
+        return StepReport(report.substeps_run, StepOutcome(report.outcome))
+
+    def skip_to(self, time: float) -> None:
+        """Scene disable: records time as the last time without stepping, and drops the queued forces."""
+        self._call("deformable_simulation_skip_to", time)
+
+    def node_positions(self, object_handle: int) -> list[Vector3]:
+        """The current node positions of an object in host units; fracture adds nodes."""
+        return self._read_lent(
+            "deformable_simulation_node_positions", object_handle, native.Vector3, conversion.read_vector3_list
+        )
+
+    def node_velocities(self, object_handle: int) -> list[Vector3]:
+        """The current node velocities of an object in host units per second, in node-position order."""
+        return self._read_lent(
+            "deformable_simulation_node_velocities", object_handle, native.Vector3, conversion.read_vector3_list
+        )
+
+    def node_masses(self, object_handle: int) -> list[float]:
+        """The lumped node masses of an object in simulation units."""
+        return self._read_lent(
+            "deformable_simulation_node_masses",
+            object_handle,
+            ctypes.c_double,
+            lambda pointer, count: conversion.read_scalars(pointer, ctypes.c_double, count),
+        )
+
+    def tetrahedron_nodes(self, object_handle: int) -> list[tuple[int, int, int, int]]:
+        """The current four nodes of each tetrahedron of an object, in mesh order."""
+        return self._read_lent(
+            "deformable_simulation_tetrahedron_nodes",
+            object_handle,
+            native.TetrahedronIndices,
+            lambda pointer, count: conversion.read_groups(pointer, ctypes.c_uint32, count, 4),
+        )
+
+    def tetrahedron_states(self, object_handle: int) -> list[TetrahedronState]:
+        """The output record of each tetrahedron of an object, in mesh order."""
+        return self._read_lent(
+            "deformable_simulation_tetrahedron_states",
+            object_handle,
+            native.TetrahedronState,
+            lambda pointer, count: [
+                TetrahedronState._from_native(state)
+                for state in conversion.lent_array(pointer, native.TetrahedronState, count)
+            ],
+        )
+
+    def face_events(self, object_handle: int) -> list[FaceEvent]:
+        """The exposed-face events of an object from the last step, one per tetrahedron fracture changed."""
+        return self._read_lent(
+            "deformable_simulation_face_events",
+            object_handle,
+            native.FaceEvent,
+            lambda pointer, count: [
+                FaceEvent(event.tetrahedron, event.exposed_faces)
+                for event in conversion.lent_array(pointer, native.FaceEvent, count)
+            ],
+        )
+
+    def awake_tetrahedron_count(self) -> int:
+        """The number of tetrahedrons in awake islands."""
+        count = native.Count()
+        self._call("deformable_simulation_awake_tetrahedron_count", ctypes.byref(count))
+        return count.value
+
+    def statistics(self) -> SimulationStatistics:
+        """The solver, contact and island counters."""
+        statistics = native.SimulationStatistics()
+        self._call("deformable_simulation_statistics", ctypes.byref(statistics))
+        return SimulationStatistics(
+            statistics.systems, statistics.conjugate_gradient_updates, statistics.contacts, statistics.islands
+        )
+
+    def _read_lent(self, function_name: str, object_handle: int, element_type, read: Callable[[Any, int], Any]) -> Any:
+        """Copies an array the simulation lends with read(pointer, count) before another call can change it."""
+        pointer = ctypes.POINTER(element_type)()
+        count = native.Count()
+        with self._use() as address:
+            function = getattr(library.load(), function_name)
+            check(function(address, conversion.unsigned(object_handle), ctypes.byref(pointer), ctypes.byref(count)))
+            return read(pointer, count.value)