You are viewing the documentation for Deformable v0.7.0, an older version. Read the latest, v0.9.0
Python API Reference
Scene
The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
On this page
- Scene
- set_
scale - set_
gravity - set_
worker_ count - add_
material - set_
material - add_
object - set_
object_ material - remove_
object - set_
object_ disabled - set_
self_ collision - set_
never_ sleep - set_
glue_ all - add_
glue_ region - drive
- add_
force - step
- skip_
to - node_
positions - node_
velocities - node_
masses - tetrahedron_
nodes - tetrahedron_
states - face_
events - awake_
tetrahedron_ count - statistics
- closed
- close
- set_
- Material
Parameters - Material
Preset - Material
Region - material_
region_ indices - Object
Options - Glue
Parameters - Driven
Vertex - Step
Report - Step
Outcome - Scene
Statistics - Tetrahedron
State - Face
Event - NODE_
REPLACED
A Scene holds a set of objects and steps them through time. Its calls come first, then the values they take and return, in the order a host meets them: materials and material regions, objects, glue, driven vertices, steps and the outputs of a step.
Scene
Class · deformable.Scene
class Scene:
def __init__(self) -> NoneOne scene a host drives frame by frame: its materials and objects, the glue, driven vertices and forces between steps, the frame step and the outputs a host reads back.
A new scene is empty, with gravity (0, -9.81, 0), scale 1, and as many worker threads as the machine runs in parallel, at most 16. Use it in a with block, or call close(), to free it at a known point; otherwise it is freed when it is collected. Object and material handles are ints counting up from 0 in creation order.
Lengths cross in host units (multiplied by the scale on the way in, divided by it on the way out); time, forces, gravity, masses and material values pass in simulation units. A scene may move between threads; calls on one scene from several threads run one at a time, and close() waits for the call in flight. step runs the scene’s own worker threads, and its results do not depend on their count.
Example
with deformable.Scene() as scene:
scene.set_gravity((0.0, 0.0, -9.81))
# The first step only records the time.
first = scene.step(0, 10)
report = scene.step(1 / 24, 10)
first.outcome, report.outcome
# (<StepOutcome.FIRST_CALL: 1>, <StepOutcome.STEPPED: 0>)See also Guide: Create a scene · C DeformableScene · Rust Scene
Scene.set_scale
Method · deformable.Scene.set_scale
def set_scale(self, scale: float) -> NoneSets the factor from the host length unit to the simulation unit, from 0.001 to 1,000.
A new scene has scale 1: a host unit is a simulation unit, which reads as a metre under the default gravity, and a scene modelled in centimetres sets 0.01. Positions, driven targets and glue plane offsets are multiplied by the scale on the way in, and positions and velocities divided by it on the way out; time, forces, gravity, node masses and material values pass unscaled. The scale applies to later calls: stored state is not rescaled.
The scene lives in a world box that reaches 1,000 simulation units from the origin along each axis. An awake island that leaves it in a step becomes static for good: its nodes stop where they are. Choose the scale so that the scene stays inside.
Parameters
scale(float)The length of one host unit in simulation units, from 0.001 to 1,000.
Raises
DeformableError with one of these statuses:
SCALE_OUT_OF_RANGEscaleis below 0.001, above 1,000, or NaN.
ValueError when the scene is closed.
See also Guide: Create a scene · C deformable_scene_set_scale · Rust Scene::set_scale
Scene.set_gravity
Method · deformable.Scene.set_gravity
def set_gravity(self, gravity: Sequence[float]) -> NoneSets the gravity acceleration, in simulation units: the scale does not apply to it.
A new scene has (0, -9.81, 0): y points up, and a simulation unit reads as a metre. A z-up scene sets (0, 0, -9.81).
Parameters
gravity(Sequence[float])The acceleration, in simulation units per second squared: three numbers.
Raises
DeformableError with one of these statuses:
NON_FINITE_VALUEA component ofgravityis NaN or infinite.
ValueError when gravity does not hold three numbers, or the scene is closed.
See also Guide: Create a scene · C deformable_scene_set_gravity · Rust Scene::set_gravity
Scene.set_worker_count
Method · deformable.Scene.set_worker_count
def set_worker_count(self, count: int) -> NoneSets the number of threads a step uses, the calling thread included; results do not depend on it.
A new scene has as many as the machine runs in parallel, at most 16. Any count from 1 up is accepted, but a step never runs more threads than the machine runs in parallel.
Parameters
count(int)The thread count, at least 1.
Raises
DeformableError with one of these statuses:
INVALID_WORKER_COUNTcountis 0.
ValueError when count is negative, or the scene is closed.
See also Guide: Create a scene · C deformable_scene_set_worker_count · Rust Scene::set_worker_count
Scene.add_material
Method · deformable.Scene.add_material
def add_material(self, parameters: MaterialParameters) -> intCreates a material and returns its handle; handles count up from 0 in creation order.
Each value is clamped to its range (see MaterialParameters), a toughness of 0 or below makes the material unbreakable, and the damping coefficient alpha is youngs_damping / youngs_modulus of the clamped values, at full double precision.
Parameters
parameters(MaterialParameters)The material’s values, such asMaterialParameters.default()or a preset.
Raises
DeformableError with one of these statuses:
NON_FINITE_VALUEA value ofparametersis NaN or infinite.
ValueError when the scene is closed.
See also Guide: Materials · C deformable_scene_add_material · Rust Scene::add_material
Scene.set_material
Method · deformable.Scene.set_material
def set_material(
self,
material: int,
parameters: MaterialParameters,
) -> NoneRewrites the values of material as add_material makes them.
The objects using the material get their materials again at the next step that advances the time with at least one substep, before its substeps: their nodes take the new toughness and the masses of a new density, with their velocities kept (see node_masses), their islands rebuild and nothing wakes.
Parameters
material(int)The material to rewrite.parameters(MaterialParameters)Its new values.
Raises
DeformableError with one of these statuses:
UNKNOWN_MATERIALmaterialnames no material of this scene.NON_FINITE_VALUEA value ofparametersis NaN or infinite.
ValueError when material is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Materials · C deformable_scene_set_material · Rust Scene::set_material
Scene.add_object
Method · deformable.Scene.add_object
def add_object(
self,
mesh: TetrahedralMesh,
materials: int | IndexArray,
options: ObjectOptions | None = None,
) -> intCreates an object from a tetrahedral mesh and returns its handle; handles count up from 0 in creation order.
The mesh is in world space and host units, and its positions are the object’s rest shape: one node per vertex, and one tetrahedron for each of its tetrahedrons, with its material. Every tetrahedron must be positively oriented, as the tools make them; the check runs in simulation units, after the scale. Nothing is created when a check fails or Free’s limit refuses the object; the limit counts the tetrahedrons the scene simulates with this one’s, none when it is created disabled, so a smaller object may still fit. The object is glued at the next step that advances the time with at least one substep.
Parameters
mesh(TetrahedralMesh)The object’s tetrahedral mesh, in world space and host units.materials(intorIndexArray)One material handle for every tetrahedron, or one per tetrahedron in mesh order.options(ObjectOptionsorNone)Self-collision, and whether the object starts disabled; None givesObjectOptions.default().
Raises
DeformableError with one of these statuses:
LENGTH_MISMATCHmaterialsgives one material per tetrahedron, and not as many as the mesh has tetrahedrons.EMPTY_MESHThe mesh has no tetrahedron.INDEX_OUT_OF_RANGEA tetrahedron uses a node index past the positions.NON_FINITE_VALUEA position is NaN or infinite, or becomes infinite once multiplied by the scale.DEGENERATE_TETRAHEDRON_TOO_SMALLA tetrahedron’s orientation determinant is above 1e-15 but at most 1e-9 in simulation units, or NaN: it is positively oriented but too small. The error’s first index names the first one.DEGENERATE_TETRAHEDRON_FLATA tetrahedron is flat: its orientation determinant is within 1e-15 of 0. The error’s first index names the first one.DEGENERATE_TETRAHEDRON_INVERTEDA tetrahedron is inverted: its corners are ordered right-handed. The error’s first index names the first one.UNKNOWN_MATERIALA handle ofmaterialsnames no material of this scene.NON_MANIFOLD_FACEThree or more tetrahedrons share one face.
ValueError when the positions or tetrahedrons of mesh do not form whole groups of three or four numbers, or an index or material handle is negative or does not fit in 32 bits, or the scene is closed.
TetrahedronLimitExceededError under Free, when the scene would simulate more than 2,500 tetrahedrons with the object.
See also Guide: Objects · C deformable_scene_add_object · Rust Scene::add_object
Scene.set_object_material
Method · deformable.Scene.set_object_material
def set_object_material(
self,
object_handle: int,
materials: int | IndexArray,
) -> NoneGives the tetrahedrons of an object new materials at the next step that advances the time with at least one substep, before its substeps.
Their nodes then take the new toughness and the masses of the new densities, with their velocities kept (see node_masses), the object’s islands rebuild and nothing wakes. A later call before that step replaces this one.
Parameters
object_handle(int)The object to change.materials(intorIndexArray)One material handle for every tetrahedron, or one per tetrahedron in mesh order.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.LENGTH_MISMATCHmaterialsgives one material per tetrahedron, and not as many as the object has tetrahedrons.UNKNOWN_MATERIALA handle ofmaterialsnames no material of this scene.
ValueError when object_handle or a material handle is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Objects · C deformable_scene_set_object_material · Rust Scene::set_object_material
Scene.remove_object
Method · deformable.Scene.remove_object
def remove_object(self, object_handle: int) -> NoneDeletes an object at once, with its contacts, glue, driven vertices, queued forces and pending material change.
Its handle becomes unknown to every call and is never given to another object, so the other objects keep theirs. Its tetrahedrons stop counting toward Free’s limit.
Parameters
object_handle(int)The object to delete.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or one already removed.
ValueError when object_handle is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Objects · C deformable_scene_remove_object · Rust Scene::remove_object
Scene.set_object_disabled
Method · deformable.Scene.set_object_disabled
def set_object_disabled(
self,
object_handle: int,
disabled: bool,
) -> NoneDisables an object or enables it again.
Disabling frees the object’s contacts and glue at once, and takes it out of its islands at the next step that runs a substep; its nodes keep their state, it keeps its outputs, and forces on it are ignored while it is disabled. Its driving waits too: its driven vertices hold still, and the drive calls made for it take effect at the first step after it is enabled, where a vertex they release leaves with its last driven velocity. Enabling it again returns its nodes with their stored state, but not its glue: an object that is disabled when the next step glues new objects gets no glue either. Setting the state the object already has does nothing. A disabled object does not count toward Free’s limit; enabled again, it takes part from the next step if it fits under the limit, and is held back as a disabled object is while it does not.
Parameters
object_handle(int)The object to disable or enable.disabled(bool)True disables the object, False enables it.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Objects · C deformable_scene_set_object_disabled · Rust Scene::set_object_disabled
Scene.set_self_collision
Method · deformable.Scene.set_self_collision
def set_self_collision(self, object_handle: int, enabled: bool) -> NoneSets or clears the self-collision of an object: whether its colliders test its own faces against each other.
Each island of the object takes the change when it is next rebuilt. ObjectOptions.self_collision gives the setting an object starts with.
Parameters
object_handle(int)The object to change.enabled(bool)True turns self-collision on, False off.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Objects · C deformable_scene_set_self_collision · Rust Scene::set_self_collision
Scene.set_never_sleep
Method · deformable.Scene.set_never_sleep
def set_never_sleep(
self,
object_handle: int,
node: int,
enabled: bool,
) -> NoneSets or clears the never-sleep flag of node node of an object: an island that holds a tetrahedron of a never-sleep node never sleeps.
Setting the flag on a frozen node wakes the node: its island and the islands around it rebuild at the next step. On an awake node the flag takes effect when its island is next rebuilt, and clearing it does nothing else.
Parameters
object_handle(int)The object that holds the node.node(int)The node, an index into the object’s nodes.enabled(bool)True sets the flag, False clears it.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.INDEX_OUT_OF_RANGEnodeis past the object’s nodes.
ValueError when object_handle or node is negative or does not fit in 32 bits, or the scene is closed.
See also Guide: Sleep · C deformable_scene_set_never_sleep · Rust Scene::set_never_sleep
Scene.set_glue_all
Method · deformable.Scene.set_glue_all
def set_glue_all(self, parameters: GlueParameters | None) -> NoneTurns glue all on with parameters, or off with None, the setting of a new scene.
With glue all on, each new object is glued to every other enabled object where their tetrahedrons overlap. The glue is made by the next step that advances the time with at least one substep, from the positions the objects have then; the new objects are those added since the last such step. Objects that only touch are not glued, and glue made before stays when glue all is turned off. A spring constant of 0 means 4,905, and a damping coefficient of 0 means 2,452.5.
Parameters
parameters(GlueParametersorNone)The spring and damping of the glue, or None to turn glue all off.
Raises
DeformableError with one of these statuses:
NON_FINITE_VALUEA value ofparametersis NaN or infinite.
ValueError when the scene is closed.
See also Guide: Glue · C deformable_scene_set_glue_all · Rust Scene::set_glue_all
Scene.add_glue_region
Method · deformable.Scene.add_glue_region
def add_glue_region(
self,
region: ConvexRegion,
members: Sequence[int],
parameters: GlueParameters,
) -> NoneAdds a glue region: each new member is glued to every other enabled member through their tetrahedrons with a vertex inside region.
The glue is made by the next step that advances the time with at least one substep, from the positions the objects have then; the new members are those added since the last such step, and the region stays for every later such step. The planes are in host units: their offsets are multiplied by the scale when the region is added, their normals are not. A region with no plane holds every point. A spring constant of 0 means 4,905, and a damping coefficient of 0 means 2,452.5.
Parameters
region(ConvexRegion)The convex region, in world space and host units.members(Sequence[int])The handles of the objects the region glues to each other.parameters(GlueParameters)The spring and damping of the glue.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTA handle ofmembersnames no object of this scene, or a removed one.NON_FINITE_VALUEA plane, or a value ofparameters, is NaN or infinite.
ValueError when a handle of members is negative or does not fit in 32 bits, or a plane normal does not hold three numbers, or the scene is closed.
See also Guide: Glue · C deformable_scene_add_glue_region · Rust Scene::add_glue_region
Scene.drive
Method · deformable.Scene.drive
def drive(
self,
object_handle: int,
vertices: Sequence[DrivenVertex],
) -> NoneDrives the listed vertices of an object to their targets from the next step on, in place of the vertices it drove before.
Each listed vertex moves in equal substeps to reach its target, to within rounding, at the end of the next step, whatever the forces on it, then holds the target until a later call for the object. Vertices driven before but not listed are released with their last driven velocity, so a host can throw them; an empty list releases them all. A vertex released by a step that ends with SUBSTEP_TOO_LARGE gets that velocity too, and the next step that runs a substep starts from it. On a disabled object the call waits until the object is enabled, and takes effect at the first step after that (see set_object_disabled). A call that fails changes nothing.
Parameters
object_handle(int)The object whose vertices to drive.vertices(Sequence[DrivenVertex])Each vertex to drive, with its target in host units.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.INDEX_OUT_OF_RANGEA vertex is past the object’s nodes.NON_FINITE_VALUEA target is NaN or infinite.
ValueError when object_handle or a vertex is negative or does not fit in 32 bits, or a target does not hold three numbers, or the scene is closed.
Example
# Each frame, vertex 0 rises 0.01 further before the step.
for frame in range(25):
x, y, z = mesh.positions[0]
target = (x, y + 0.01 * frame, z)
scene.drive(object, [deformable.DrivenVertex(0, target)])
report = scene.step(frame / 24, 10)See also Guide: Drive vertices and add forces · C deformable_scene_drive · Rust Scene::drive
Scene.add_force
Method · deformable.Scene.add_force
def add_force(
self,
object_handle: int,
node: int,
force: Sequence[float],
) -> NoneQueues force on node node of an object for the substeps of the next step call; calls on one node add up.
The next step call that returns a report uses up the queue, whether it runs substeps or not, and skip_to drops it, so a lasting force is queued again before each step. When a substep applies it, a force on a frozen node wakes the node’s connected piece, or for an object with glue the nodes within the material’s wake_up_radius of it, even a zero force; on a node that is not solved, such as a driven one, the force is kept and acts at once on the node’s first solve. Forces on a disabled object are ignored.
Parameters
object_handle(int)The object that holds the node.node(int)The node, an index into the object’s nodes.force(Sequence[float])The force, in simulation units: three numbers, which the scale does not apply to.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.INDEX_OUT_OF_RANGEnodeis past the object’s nodes.NON_FINITE_VALUEA component offorceis NaN or infinite.
ValueError when object_handle or node is negative or does not fit in 32 bits, or force does not hold three numbers, or the scene is closed.
Example
# A push along x on every node, for the next step.
for node in range(len(mesh.positions)):
scene.add_force(object, node, (5.0, 0.0, 0.0))See also Guide: Drive vertices and add forces · C deformable_scene_add_force · Rust Scene::add_force
Scene.step
Method · deformable.Scene.step
def step(
self,
time: float,
substeps: int,
cancel: CancelFlag | None = None,
) -> StepReportAdvances the scene to time, in seconds, in substeps equally long substeps.
A host calls it once per frame with the frame’s time. The first call only records the time, so make it at the start frame. A later call runs its substeps when time has passed, substeps is not 0 and a substep is at most 0.04 s; otherwise the outcome says which of these stopped it. A cancel flag set from another thread stops the step between two substeps, after at least one, with the outcome CANCELLED: the time then stands at the last substep run, so the next call goes on from there.
Every call that returns a report uses up the forces add_force queued. The license is checked at every call: under Free the step simulates the objects that fit under its 2,500 tetrahedrons, in the order they were added, and holds the rest back as disabled objects are until a subscription or a license applies again, which glues them again where they stand.
Parameters
time(float)The frame’s time, in seconds. It may not be before the last time a step orskip_torecorded.substeps(int)How many substeps to run, all of one length; at 24 frames per second, 10 is a good start.cancel(CancelFlagorNone)Stops the step between two substeps when another thread sets it.
Returns
StepReport: How many substeps ran, and what the call did: whether they ran, and if not, why.
Raises
DeformableError with one of these statuses:
NON_FINITE_VALUEtimeis NaN or infinite.TIME_WENT_BACKWARDStimeis before the last time recorded. To go back, create a new scene.
ValueError when the scene or cancel is closed, or substeps is negative or 2**32 or more; after the step ran, when the library reports an outcome this package does not know, which only a newer library does.
Example
for frame in range(3):
report = scene.step(frame / 24, 10)
print(report.outcome.name, report.substeps_run)
# FIRST_CALL 0
# STEPPED 10
# STEPPED 10See also Guide: Stepping · C deformable_scene_step · Rust Scene::step
Scene.skip_to
Method · deformable.Scene.skip_to
def skip_to(self, time: float) -> NoneRecords time as the last time without creating glue, applying driven vertices or stepping, and drops the forces add_force queued.
A host calls it in place of Scene.step while its scene is paused or disabled: the next step goes on from time as if no time had passed. Before the first step it records nothing, so the next step is still a first call.
Parameters
time(float)The time to record, in seconds. It may not be before the last time recorded.
Raises
DeformableError with one of these statuses:
NON_FINITE_VALUEtimeis NaN or infinite.TIME_WENT_BACKWARDStimeis before the last time recorded.
ValueError when the scene is closed.
See also Guide: Stepping · C deformable_scene_skip_to · Rust Scene::skip_to
Scene.node_positions
Method · deformable.Scene.node_positions
def node_positions(self, object_handle: int) -> list[Vector3]The current node positions of an object, in host units.
The first nodes are the vertices of the mesh the object was made from, in order. Fracture clones nodes and adds them after, so the node count grows as the object breaks. The list is a copy, which later calls leave as it is.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
Example
positions = scene.node_positions(object)
# Before any fracture, one node per mesh vertex.
len(positions) == len(mesh.positions)
# TrueSee also Guide: Outputs · C deformable_scene_node_positions · Rust Scene::node_positions
Scene.node_velocities
Method · deformable.Scene.node_velocities
def node_velocities(self, object_handle: int) -> list[Vector3]The current node velocities of an object, in host units per second (divided by the scale), in the order of node_positions.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
See also Guide: Outputs · C deformable_scene_node_velocities · Rust Scene::node_velocities
Scene.node_masses
Method · deformable.Scene.node_masses
def node_masses(self, object_handle: int) -> list[float]The lumped node masses of an object, in simulation units, in the order of node_positions.
Each node, driven or not, takes a quarter of the mass (density times volume) of every tetrahedron it belongs to. A density that set_material or set_object_material changes reaches the masses at the next step that advances the time with at least one substep: each of its tetrahedrons gives its nodes the quarter of the new mass in place of the old one, and the velocities stay as they were, so the momentum changes with the mass. Fracture moves a tetrahedron’s quarter to the clone that takes it.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
See also Guide: Outputs · C deformable_scene_node_masses · Rust Scene::node_masses
Scene.tetrahedron_nodes
Method · deformable.Scene.tetrahedron_nodes
def tetrahedron_nodes(
self,
object_handle: int,
) -> list[tuple[int, int, int, int]]The current four nodes of each tetrahedron of an object, as indices into its nodes (the order of node_positions), in mesh order.
Fracture never deletes or reorders tetrahedrons: tetrahedron i stays tetrahedron i of the mesh. It moves tetrahedrons onto cloned nodes instead, which these indices follow.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
Example
tetrahedrons = scene.tetrahedron_nodes(object)
# Before any fracture, the nodes are those of the mesh.
tetrahedrons == [tuple(nodes) for nodes in mesh.tetrahedrons]
# TrueSee also Guide: Outputs · C deformable_scene_tetrahedron_nodes · Rust Scene::tetrahedron_nodes
Scene.tetrahedron_states
Method · deformable.Scene.tetrahedron_states
def tetrahedron_states(
self,
object_handle: int,
) -> list[TetrahedronState]The output record of each tetrahedron of an object, in mesh order: its corners in host units, its island id or 0, its strain measure and its flags.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
Example
states = scene.tetrahedron_states(object)
replaced = deformable.NODE_REPLACED
sum(1 for state in states if state.flags & replaced)
# 0See also Guide: Outputs · C deformable_scene_tetrahedron_states · Rust Scene::tetrahedron_states
Scene.face_events
Method · deformable.Scene.face_events
def face_events(self, object_handle: int) -> list[FaceEvent]The exposed-face events of an object from the last step: one for each tetrahedron that fracture changed in it.
Every step that returns a report replaces them, so a step without fracture leaves none. The list is a copy, which later calls leave as it is.
Parameters
object_handle(int)The object to read.
Raises
DeformableError with one of these statuses:
UNKNOWN_OBJECTobject_handlenames no object of this scene, or a removed one.
ValueError when object_handle is negative or 2**32 or more, or the scene is closed.
Example
boundary = deformable.boundary_faces(mesh)
for event in scene.face_events(object):
# The faces a crack opened, without the rest surface.
opened = event.exposed_faces & ~boundary[event.tetrahedron]
print(event.tetrahedron, f"{opened:04b}")See also Guide: Find the faces a crack opened · C deformable_scene_face_events · Rust Scene::face_events
Scene.awake_tetrahedron_count
Method · deformable.Scene.awake_tetrahedron_count
def awake_tetrahedron_count(self) -> intThe number of tetrahedrons in awake islands, over the whole scene, counted at each call.
Sleeping tetrahedrons do not count, nor do static ones: those whose four nodes are all driven, and those of an island that left the world box (see set_scale). Nor do those of islands waiting to be rebuilt at the next step that runs a substep, as after a material change, a disable or a fracture. A tetrahedron counts once a step has put it in an island, so a new object counts from the next step that runs substeps.
Raises
ValueError when the scene is closed.
See also Guide: Sleep · C deformable_scene_awake_tetrahedron_count · Rust Scene::awake_tetrahedron_count
Scene.statistics
Method · deformable.Scene.statistics
def statistics(self) -> SceneStatisticsThe solver, contact and island counters of the scene, for measuring it: the solves since the scene was created, and the live contacts and the islands it holds now.
Raises
ValueError when the scene is closed.
See also Guide: Outputs · C deformable_scene_statistics · Rust Scene::statistics
Scene.closed
Property · deformable.Scene.closed
@property
def closed(self) -> boolTrue once the handle has been destroyed.
Scene.close
Method · deformable.Scene.close
def close(self) -> NoneDestroys the handle once the calls in flight on it end; later calls on the object raise ValueError. Closing twice does nothing.
See also Guide: Create a scene · C deformable_scene_destroy
MaterialParameters
Data class · deformable.MaterialParameters
@dataclasses.dataclass(frozen=True)
class MaterialParameters:
youngs_modulus: float
poissons_ratio: float
density: float
toughness: float
youngs_damping: float
yield_strain: float
maximum_yield: float
creep_fraction: float
wake_up_radius: float
friction: floatThe values of a material, as a host gives them to Scene.add_material and Scene.set_material, which clamp each one to its range and refuse a NaN or infinite one.
MaterialParameters.default() gives the defaults below, and MaterialParameters.preset the values of a named material such as "steel". The class is frozen: dataclasses.replace gives a copy with some values changed.
Fields
youngs_modulus(float)Young’s modulus, in pascals in simulation units: the higher, the stiffer.default()gives8e5, clamped to[1e3, 1e10].poissons_ratio(float)Poisson’s ratio, unitless: how much the material bulges sideways when it is squeezed.default()gives0, clamped to[-0.90001, 0.490001].density(float)Mass per unit volume, in simulation units: a tetrahedron weighs its density times its volume.default()gives2500, clamped to[0, 1e4].toughness(float)The fracture threshold: a node can split once half the largest eigenvalue of its separation tensor exceeds the lowest toughness among its tetrahedrons. 0 or less makes the material unbreakable.default()gives2e5, clamped to[0, 1e8].youngs_damping(float)Stiffness-proportional damping; the engine’s damping coefficient isyoungs_damping / youngs_modulus.default()gives0, clamped to[0, 1e9].yield_strain(float)The elastic strain norm above which plastic flow starts.default()gives0, clamped to[0, 1].maximum_yield(float)The bound on the plastic strain norm; 0 resets the plastic strain every solve.default()gives0, clamped to[0, 1].creep_fraction(float)The share of the elastic strain added to the plastic strain once per solve, not per second, while the elastic strain norm exceedsyield_strain; 0 turns plasticity off.default()gives0, clamped to[0, 1].wake_up_radius(float)How far, in simulation units, an impact on this material wakes the sleeping nodes of an object that has glue; an object without glue wakes its whole connected piece instead.default()gives1.2, clamped to[1, 1000].friction(float)The Coulomb friction coefficient; a contact uses the lower of its two materials’ coefficients.default()gives0.6, clamped to[0, 1].
Example
rubber = deformable.MaterialParameters.default(
youngs_modulus=1e6, poissons_ratio=0.45
)
material = scene.add_material(rubber)See also Guide: Materials · C DeformableMaterialParameters · Rust MaterialParameters
MaterialParameters.default
Class method · deformable.MaterialParameters.default
@classmethod
def default(cls, **changes: float) -> MaterialParametersThe values a new material starts from, the defaults the fields list, with the given fields changed.
Parameters
**changes(float)Field values that replace the defaults, by field name.
Raises
TypeError when changes names a field MaterialParameters does not have.
See also Guide: Materials · C deformable_material_parameters_default
MaterialParameters.presets
Class method · deformable.MaterialParameters.presets
@classmethod
def presets(cls) -> list[MaterialPreset]The presets the library ships, in its order: named starting points for a material, by family from the softest solids to the metals.
Density is in kilograms per cubic metre, with one simulation unit a metre. The values are chosen for each material and checked on a cube about one unit across, dropped onto a floor, and on a cantilever: whether the preset shatters, breaks from a fall or survives both, whether it bounces or keeps a dent, and how far it sags. An unbreakable_ preset is its namesake with toughness 0, and a few other presets are unbreakable too. Every value lies inside its clamp range, and every preset keeps the default wake_up_radius.
The names of the presets, by family:
- Soft solids:
sponge,foam,snow,jelly,rubber,unbreakable_rubber,hard_rubber. - Living and wooden:
flesh,bone,plant,straw,cork,tree,wood,plywood,cardboard. - Building materials and stone:
drywall,plaster,asphalt,clay,brick,concrete,reinforced_concrete,sandstone,stone,granite. - Glass and ceramics:
glass,safety_glass,ceramic,diamond. - Plastics and carbon:
plastic,rigid_foam,carbon_fiber,graphite. - Metals:
wire,stiff_wire,steel,sheet_metal,foil,rebar,unbreakable_rebar,lead,iron.
Raises
Only the errors every call can raise, which the conventions describe.
Example
presets = deformable.MaterialParameters.presets()
[preset.name for preset in presets[:3]]
# ['sponge', 'foam', 'snow']See also Guide: Materials · C deformable_material_preset_count · C deformable_material_preset · Rust MaterialParameters::presets
MaterialParameters.preset
Class method · deformable.MaterialParameters.preset
@classmethod
def preset(cls, name: str) -> MaterialParameters | NoneLooks a preset up by its name.
The name must match a preset’s exactly, case included: "steel" is a preset, "Steel" is not.
Parameters
name(str)The preset’s name, such as"concrete"or"unbreakable_rubber".
Returns
MaterialParameters or None: The preset’s values, or None when no preset has this name.
Raises
TypeError when name is not a str.
Example
steel = deformable.MaterialParameters.preset("steel")
material = scene.add_material(steel)
print(deformable.MaterialParameters.preset("Steel"))
# NoneSee also Guide: Materials · C deformable_material_preset_find · Rust MaterialParameters::preset
MaterialPreset
Named tuple · deformable.MaterialPreset
class MaterialPreset(NamedTuple):
name: str
parameters: MaterialParametersA material preset: its name and its values, as MaterialParameters.presets lists them.
Fields
name(str)The preset’s name, in lowercase with underscores between words, such as"concrete"or"unbreakable_rubber".parameters(MaterialParameters)The values, each inside its clamp range, soScene.add_materialkeeps them as they are.
See also Guide: Materials · Rust MaterialPreset
MaterialRegion
Data class · deformable.MaterialRegion
@dataclasses.dataclass
class MaterialRegion:
mesh: PolygonMesh
to_mesh_space: AffineTransform = IDENTITYA material region: a polygon mesh in its own object space, and its map into the object space of a tetrahedral mesh, for material_region_indices.
A region with no polygons holds every tetrahedron.
Fields
mesh(PolygonMesh)The region’s mesh, normally a closed convex polyhedron with outward faces, such as a unit cube: the region is what lies behind all of its face planes.to_mesh_space(AffineTransform)Maps the region’s points into the tetrahedral mesh’s object space: the region’s world matrix times the inverse of the object’s. DefaultIDENTITY.
Example
# The unit cube moved 0.5 along x: it holds the right half of mesh.
identity = deformable.IDENTITY.linear
moved = deformable.AffineTransform(identity, (0.5, 0.0, 0.0))
right_half = deformable.MaterialRegion(polygons, moved)See also Guide: Material regions · C DeformableMaterialRegion · Rust MaterialRegion
material_region_indices
Function · deformable.material_region_indices
def material_region_indices(
mesh: TetrahedralMesh,
regions: Sequence[MaterialRegion],
) -> list[int]Which material region holds each tetrahedron of mesh: 0 when none does, or 1 plus the index in regions of the region that does.
A region holds a tetrahedron when the tetrahedron’s centroid lies behind or on every face plane of the region’s mesh, mapped by to_mesh_space. Where regions overlap, the one whose mesh has the smallest signed volume before the map wins, whatever their order in regions; regions of equal volume may be tried in another order than theirs. A region with no polygons holds every tetrahedron. Each face plane is taken from the mapped polygon, so any invertible map, a non-uniform scale or a zero diagonal included, keeps the region exactly where the map puts it.
The host turns the indices into the per-tetrahedron materials of Scene.add_object or Scene.set_object_material: 0 is the object’s material, and each other index the material of the region one below it in regions.
Parameters
mesh(TetrahedralMesh)The tetrahedral mesh, in the object space the regions map into.regions(Sequence[MaterialRegion])The regions, each a polygon mesh and its map into the object space ofmesh.
Returns
list[int]: One index per tetrahedron, in mesh order.
Raises
DeformableError with one of these statuses:
EMPTY_MESHmeshhas no tetrahedron.INDEX_OUT_OF_RANGEA tetrahedron ofmesh, or a polygon of a region, uses a vertex past the end of its positions.NON_FINITE_VALUEA position ofmeshor of a region’s mesh, or a value of a region’s map, is NaN or infinite.LENGTH_MISMATCHThe polygon sizes of a region’s mesh do not add up to its number of polygon vertices.DEGENERATE_REGIONA polygon of a region has fewer than 3 corners, or a zero normal once mapped; the error’sfirst_indexnames the region, itssecond_indexthe polygon.
ValueError when the positions of mesh or of a region’s mesh do not form whole groups of three numbers, the tetrahedrons of mesh whole groups of four, an index or polygon size is negative or does not fit in 32 bits, or the linear part of a region’s map does not hold three rows of three numbers or its translation three numbers.
Example
halve_x = deformable.AffineTransform(
((0.5, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
)
left_half = deformable.MaterialRegion(polygons, halve_x)
indices = deformable.material_region_indices(mesh, [left_half])
sorted(set(indices))
# [0, 1]See also Guide: Material regions · C deformable_material_region_indices · Rust material_region_indices
ObjectOptions
Data class · deformable.ObjectOptions
@dataclasses.dataclass(frozen=True)
class ObjectOptions:
self_collision: bool
disabled: boolThe per-object settings a host gives when it creates an object with Scene.add_object.
ObjectOptions.default() turns self-collision on and leaves the object enabled. Scene.set_self_collision and Scene.set_object_disabled change them later.
Fields
self_collision(bool)The object’s colliders test its own faces against each other.default()givesTrue.disabled(bool)The object is created disabled: it takes no part in the scene untilScene.set_object_disabledenables it, and it gets no glue if it is still disabled when the next step glues new objects.default()givesFalse.
Example
options = deformable.ObjectOptions.default(self_collision=False)
cube = scene.add_object(mesh, material, options)See also Guide: Objects · C DeformableObjectOptions · Rust ObjectOptions
ObjectOptions.default
Class method · deformable.ObjectOptions.default
@classmethod
def default(cls, **changes: bool) -> ObjectOptionsThe object defaults, self-collision on and enabled, with the given fields changed.
Parameters
**changes(bool)Field values that replace the defaults, by field name.
Raises
TypeError when changes names a field ObjectOptions does not have.
See also C deformable_object_options_default
GlueParameters
Named tuple · deformable.GlueParameters
class GlueParameters(NamedTuple):
spring_constant: float
damping_coefficient: floatThe spring and damping of glue, for Scene.set_glue_all and Scene.add_glue_region.
Glue holds two overlapping tetrahedrons at the overlap volume they had when it was made, as a spring with a damper; the library scales the spring by the mass of the lighter of the two glued islands. A spring constant of 0 means 4,905, and a damping coefficient of 0 means 2,452.5.
Fields
spring_constant(float)The spring constant; 0 means 4,905.damping_coefficient(float)The damping coefficient; 0 means 2,452.5.
Example
# A stiffer spring than the default, with the default damping.
glue = deformable.GlueParameters(
spring_constant=2e4, damping_coefficient=0.0
)
scene.set_glue_all(glue)See also Guide: Glue · C DeformableGlueParameters · Rust GlueParameters
DrivenVertex
Named tuple · deformable.DrivenVertex
class DrivenVertex(NamedTuple):
vertex: int
target: Sequence[float]A vertex of an object driven to a target, in host units, for Scene.drive.
Fields
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: three numbers. It holds the target until a laterScene.drivecall for the object moves or releases it.
Example
# Vertex 0, lifted 0.1 above where the mesh has it.
x, y, z = mesh.positions[0]
lifted = deformable.DrivenVertex(0, (x, y + 0.1, z))
scene.drive(object, [lifted])See also Guide: Drive vertices and add forces · C DeformableDrivenVertex · Rust DrivenVertex
StepReport
Named tuple · deformable.StepReport
class StepReport(NamedTuple):
substeps_run: int
outcome: StepOutcomeThe result of a Scene.step call: how many substeps ran, and what the call did.
Fields
substeps_run(int)The number of substeps simulated: all of them forStepOutcome.STEPPED, fewer forStepOutcome.CANCELLED, 0 for the other outcomes.outcome(StepOutcome)What the call did.
See also Guide: Stepping · C DeformableStepReport · Rust StepReport
StepOutcome
Enum · deformable.StepOutcome
class StepOutcome(enum.IntEnum):
STEPPED = 0
FIRST_CALL = 1
NO_TIME_ELAPSED = 2
NO_SUBSTEPS = 3
SUBSTEP_TOO_LARGE = 4
CANCELLED = 5What a Scene.step call did.
Values
STEPPED(0)The substeps ran.FIRST_CALL(1)The first call only records the time.NO_TIME_ELAPSED(2)The time equals the last time; nothing is stepped.NO_SUBSTEPS(3)Zero substeps were asked for; the time advances without a step.SUBSTEP_TOO_LARGE(4)A substep would be longer than 0.04 s. The time advances, and the step’s new glue, material changes and driven-vertex changes are made, but no substep runs; a vertex released now gets its last driven velocity, and the next step that runs a substep starts from it.CANCELLED(5)The cancel flag stopped the step aftersubsteps_runsubsteps; the time advances by as many substeps, so the next step goes on from there. The queued forces are used up and do not reach the substeps that remain.
See also Guide: Stepping · C DeformableStepOutcome · Rust StepOutcome
SceneStatistics
Named tuple · deformable.SceneStatistics
class SceneStatistics(NamedTuple):
systems: int
conjugate_gradient_updates: int
contacts: int
islands: intThe solver, contact and island counters of a scene, for measuring it, as Scene.statistics returns them; nothing in the scene uses them.
Fields
systems(int)The linear systems solved since the scene was created: one per contact island, and one per awake island outside every contact island, in each substep.conjugate_gradient_updates(int)The conjugate gradient solution updates, summed over every solve since the scene was created.contacts(int)The live contacts, glue contacts included.islands(int)The islands it holds: awake, asleep and static (driven, or out of the world box), those waiting to be rebuilt at the next step included.
See also Guide: Outputs · C DeformableSceneStatistics · Rust SceneStatistics
TetrahedronState
Data class · deformable.TetrahedronState
@dataclasses.dataclass(frozen=True)
class TetrahedronState:
corners: tuple[Vector3, Vector3, Vector3, Vector3]
island: int
strain_measure: float
flags: intThe output record of one tetrahedron, as Scene.tetrahedron_states reads it.
Fields
corners(tuple[Vector3, Vector3, Vector3, Vector3])The current corner positions in host units, in the order of the tetrahedron’s nodes.island(int)The id of the tetrahedron’s island, the group of tetrahedrons solved together, or 0 while it has none.strain_measure(float)The squared norm of the total co-rotated strain, plastic part included, measured with the tetrahedron’s stored rotation:ε_xx² + ε_yy² + ε_zz² + 2(γ_yz² + γ_xz² + γ_xy²), with no square root taken.flags(int)Bit k (0 to 3) is set once face k, opposite corner k, has been reported exposed, and stays set; bitNODE_REPLACEDis set while a fracture has moved the tetrahedron onto a cloned node.
See also Guide: Outputs · C DeformableTetrahedronState · Rust TetrahedronState
TetrahedronState.face_centroid
Method · deformable.TetrahedronState.face_centroid
def face_centroid(self, face: int) -> Vector3The centroid of the face face, the one opposite corner face, in the unit of the corners.
Parameters
face(int)The face, 0 to 3.
Raises
DeformableError with one of these statuses:
INDEX_OUT_OF_RANGEfaceis above 3.
ValueError when face is negative or 2**32 or more.
See also Guide: Find the faces a crack opened · C deformable_tetrahedron_state_face_centroid · Rust TetrahedronState::face_centroid
TetrahedronState.face_normal
Method · deformable.TetrahedronState.face_normal
def face_normal(self, face: int) -> Vector3The outward unit normal of the face face, the one opposite corner face, for a positively oriented tetrahedron; the zero vector for a face of zero area.
Parameters
face(int)The face, 0 to 3.
Raises
DeformableError with one of these statuses:
INDEX_OUT_OF_RANGEfaceis above 3.
ValueError when face is negative or 2**32 or more.
See also Guide: Find the faces a crack opened · C deformable_tetrahedron_state_face_normal · Rust TetrahedronState::face_normal
FaceEvent
Named tuple · deformable.FaceEvent
class FaceEvent(NamedTuple):
tetrahedron: int
exposed_faces: intAn exposed-face event: a tetrahedron fracture changed in the last step and the faces it now shares with no other tetrahedron.
The mask holds every exposed face of the tetrahedron, not only those the step opened: the faces on the surface of the rest mesh, which boundary_faces gives, count too. A tetrahedron that a later fracture changes again gets a new event, with the faces reported before still set.
Fields
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 shared with no other tetrahedron.
See also Guide: Find the faces a crack opened · C DeformableFaceEvent · Rust FaceEvent
NODE_REPLACED
Constant · deformable.NODE_REPLACED
NODE_REPLACED = 0x10The bit of TetrahedronState.flags set while one of the tetrahedron’s nodes is no longer the node it was created with: a fracture moved the tetrahedron onto a clone of that node. It is worked out again for every read, not kept like the face bits.
See also C DEFORMABLE_NODE_REPLACED · Rust NODE_REPLACED