MPMEntity（材料点法实体）

class genesis.engine.entities.mpm_entity.MPMEntity(scene, solver, material, morph, surface, particle_size, idx, particle_start, vvert_start, vface_start, name: str | None = None)

Bases: ParticleEntity

MPM-based particle entity.

Parameters:

• scene (Scene) – Scene object this entity belongs to.

• solver (Solver) – The solver responsible for simulating this entity.

• material (Material) – Material used to determine physical behavior (e.g., Snow, Sand, Muscle).

• morph (Morph) – Shape description used for particle sampling.

• surface (Surface) – Surface or texture representation.

• particle_size (float) – Particle size for discretization.

• idx (int) – Unique index of the entity.

• particle_start (int) – Starting particle index.

• vvert_start (int) – Start index for visual vertices (unused if no skinning).

• vface_start (int) – Start index for visual faces (unused if no skinning).

init_tgt_keys()

Initialize target keys used for buffer-based state tracking.

Sets up the list of keys for target states, including velocity, position, activeness, and finally actuation (for muscle only).

add_grad_from_state(state)

Accumulate gradients from a recorded state back into the solver.

Parameters:

state (MPMEntityState) – The state object containing gradients for physical quantities.

process_input(in_backward=False)

Push position, velocity, and activation target states into the simulator.

Parameters:

in_backward (bool, default=False) – Whether the simulation is in the backward gradient pass.

process_input_grad()

Process gradients for buffered inputs and backpropagate using custom kernels.

get_state()

Get the current physical state of the particle entity.

Returns:

state – The current state of all physical properties of the entity.

Return type:

MPMEntityState

get_frame(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x10917d0f0>, pos: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None), vel: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None), C: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None), F: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None), Jp: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None), active: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))

Extract the state of particles at the given substep.

Parameters:

• f (int) – Local substep index to query.

• pos (ndarray) – Particle positions, shape (B, n_particles, 3).

• vel (ndarray) – Particle velocities, shape (B, n_particles, 3).

• C (ndarray) – Affine matrix C, shape (B, n_particles, 3, 3).

• F (ndarray) – Deformation gradient F, shape (B, n_particles, 3, 3).

• Jp (ndarray) – Volume ratio, shape (B, n_particles).

• active (ndarray) – Particle activeness state, shape (B, n_particles).

set_particles_pos(poss, particles_idx_local=None, envs_idx=None)

Set the position of some particles.

Parameters:

• poss (torch.Tensor, shape (M, N, 3)) – Target position of each particle.

• particles_idx_local (torch.Tensor, shape (M, N)) – Index of the particles relative to this entity. If None, all particles will be considered. Defaults to None.

• envs_idx (torch.Tensor, shape (M,)) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

get_particles_pos(envs_idx=None)

Retrieve current particle positions from the solver.

Parameters:

envs_idx (None | int | array_like, shape (M,), optional) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

Returns:

poss – Tensor of particle positions.

Return type:

torch.Tensor, shape (M, n_particles, 3)

set_particles_vel(vels, particles_idx_local=None, envs_idx=None)

Set the velocity of some particles.

Parameters:

• vels (torch.Tensor, shape (M, N, 3)) – Target velocity of each particle.

• particles_idx_local (torch.Tensor, shape (M, N)) – Index of the particles relative to this entity. If None, all particles will be considered. Defaults to None.

• envs_idx (torch.Tensor, shape (M,)) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

get_particles_vel(envs_idx=None)

Retrieve current particle velocities from the solver.

Parameters:

envs_idx (None | int | array_like, shape (M,), optional) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

Returns:

poss – Tensor of particle velocities, shape (M, n_particles, 3).

Return type:

torch.Tensor

set_particles_active(actives, particles_idx_local=None, envs_idx=None)

Set the velocity of some particles.

Parameters:

• actives (torch.Tensor, shape (M, N, 3)) – Activeness boolean flags for each particle.

• particles_idx_local (torch.Tensor, shape (M, N)) – Index of the particles relative to this entity. If None, all particles will be considered. Defaults to None.

• envs_idx (torch.Tensor, shape (M,)) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

get_particles_active(envs_idx=None)

Retrieve current particle activeness boolean flags from the solver.

Parameters:

envs_idx (None | int | array_like, shape (M,), optional) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

Returns:

poss – Tensor of particle activeness boolean flags.

Return type:

torch.Tensor, shape (M, n_particles, 3)

set_actuation(actus, envs_idx=None)

Set actuation values for each muscle group individually.

Parameters:

• actus (int | array_like, shape ([M,] [n_particles,] [n_groups,])) – Tensor of actuation values.

• envs_idx (None | int | array_like, shape (M,), optional) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

set_particles_actu(actus, particles_idx_local=None, envs_idx=None)

Set particle actuation values.

Parameters:

• actus (torch.Tensor, shape (M, N, 3)) – Activation value of each particle.

• particles_idx_local (torch.Tensor, shape (M, N)) – Index of the particles relative to this entity.

• envs_idx (torch.Tensor, shape (M,)) – The indices of the environments to set. If None, all environments will be considered. Defaults to None.

get_particles_actu(envs_idx=None)

set_muscle_group(muscle_group)

Set the muscle group index for each particle.

Parameters:

muscle_group (torch.Tensor, shape ([n_particles,])) – A tensor with integer group IDs.

get_muscle_group()

Retrieve the muscle group index for each particle.

Returns:

muscle_group – A tensor containing the muscle group ID of each particle.

Return type:

torch.Tensor, shape (n_particles,)

set_muscle_direction(muscle_direction)

Set the muscle fiber direction for each particle.

Parameters:

muscle_direction (torch.Tensor, shape ([n_particles,] 3)) – A tensor with unit vectors representing muscle directions.

set_muscle(muscle_group=None, muscle_direction=None)

Set both the muscle group indices and direction vectors.

Parameters:

• muscle_group (torch.Tensor, shape ([n_particles,]), optional) – A tensor with group indices.

• muscle_direction (torch.Tensor, shape ([n_particles,] 3), optional) – A tensor with unit vectors.

set_free(free)

Set particles as free or constrained.

Parameters:

free (torch.Tensor, shape ([n_particles,])) – A tensor indicating if each particle is free (1) or fixed (0).

get_free()

Get free/fixed status for all particles.

Returns:

free – A tensor indicating free (1) or fixed (0) status.

Return type:

torch.Tensor, shape (n_particles,)

get_particles_in_bbox(bbox_min, bbox_max)

Get boolean mask for particles within a bounding box.

Parameters:

• bbox_min (array_like, shape (3,)) – Minimum corner of the bounding box [x, y, z].

• bbox_max (array_like, shape (3,)) – Maximum corner of the bounding box [x, y, z].

Returns:

mask – Boolean mask where True indicates particle is within the bounding box.

Return type:

torch.Tensor, shape (n_envs, n_particles)

set_particle_constraints(particles_mask, link_idx, stiffness)

Attach MPM particles to a rigid link using soft constraints.

The particles will be pulled toward their relative position on the link using spring forces with critical damping.

Parameters:

• particles_mask (torch.Tensor, shape (n_envs, n_particles)) – Boolean mask indicating which particles to constrain.

• link_idx (int) – Index of the rigid link to attach particles to.

• stiffness (float) – Spring stiffness for the constraint.

remove_particle_constraints(particles_mask=None)

Remove constraints from specified particles, or all if None.

Parameters:

particles_mask (torch.Tensor, shape (n_envs, n_particles), optional) – Boolean mask indicating which particles to unconstrain. If None, removes all constraints for this entity.