MPMEntity#

class genesis.engine.entities.mpm_entity.MPMEntity(scene, solver, material, morph, surface, particle_size, idx, particle_start, vvert_start, vface_start)[source]#

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).

  • 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()[source]#

Initialize target keys used for buffer-based state tracking.

Sets up the list of keys for target states, including velocity, position, activeness, and actuation.

set_pos(f, pos)[source]#

Set particle positions at a specific frame.

Parameters:

  • f (int) – The current substep index.

  • pos (gs.Tensor) – A tensor of shape (n_envs, n_particles, 3) representing particle positions.

set_pos_grad(f, pos_grad)[source]#

Set gradients for particle positions at a specific frame.

Parameters:

  • f (int) – The current substep index.

  • pos_grad (gs.Tensor) – A tensor of shape (n_particles, 3) containing gradients for particle positions.

set_vel(f, vel)[source]#

Set particle velocities at a specific frame.

Parameters:

  • f (int) – The current substep index.

  • vel (gs.Tensor) – A tensor of shape (n_particles, 3) representing particle velocities.

set_vel_grad(f, vel_grad)[source]#

Set gradients for particle velocities at a specific frame.

Parameters:

  • f (int) – The current substep index.

  • vel_grad (gs.Tensor) – A tensor of shape (n_particles, 3) containing gradients for particle velocities.

set_actu(f, actu)[source]#

Set particle actuation values at a specific frame.

Parameters:

  • f (int) – The current substep index.

  • actu (gs.Tensor) – A tensor of shape (n_particles,) or (n_groups,) or (B, n_groups) representing actuation values.

set_actu_grad(f, actu_grad)[source]#

Set gradients for particle actuation values.

Parameters:

  • f (int) – The current substep index.

  • actu_grad (gs.Tensor) – A tensor containing gradients for actuation inputs.

set_muscle_group(muscle_group)[source]#

Set the muscle group index for each particle.

Parameters:

muscle_group (gs.Tensor) – A tensor of shape (n_particles,) with integer group IDs.

get_muscle_group()[source]#

Retrieve the muscle group index for each particle.

Returns:

muscle_group – A tensor of shape (n_particles,) containing the muscle group ID of each particle.

Return type:

gs.Tensor

set_muscle_direction(muscle_direction)[source]#

Set the muscle fiber direction for each particle.

Parameters:

muscle_direction (gs.Tensor) – A tensor of shape (n_particles, 3) with unit vectors representing muscle directions.

set_active(f, active)[source]#

Set the activeness state of all particles.

Parameters:

  • f (int) – The current substep index.

  • active (int) – Value indicating whether particles are active (gs.ACTIVE) or inactive (gs.INACTIVE).

set_active_arr(f, active)[source]#

Set per-particle activeness using an array.

Parameters:

  • f (int) – The current substep index.

  • active (gs.Tensor) – A tensor of shape (n_particles,) with activeness values.

set_actuation(actu)[source]#

Set actuation values for muscle groups.

Parameters:

actu (torch.Tensor) – A tensor with shape matching the number of groups or the batch size and number of groups. Supported shapes: (), (n_groups,), (n_particles,), (B, n_groups), (B, n_particles), (B, self.n_particles, n_groups).

set_muscle(muscle_group=None, muscle_direction=None)[source]#

Set both the muscle group indices and direction vectors.

Parameters:

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

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

set_free(free)[source]#

Set particles as free or constrained.

Parameters:

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

get_free()[source]#

Get free/fixed status for all particles.

Returns:

free – A tensor of shape (n_particles,) indicating free (1) or fixed (0) status.

Return type:

gs.Tensor

clear_grad(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>)[source]#

Clear all gradients for particle properties at the given substep.

Parameters:

f (int) – The current substep index.

process_input(in_backward=False)[source]#

Process buffered target inputs and set them into the solver.

Parameters:

in_backward (bool, optional) – Whether to load target values from the backward pass buffer.

process_input_grad()[source]#

Process gradients for buffered inputs and backpropagate using custom kernels.

get_frame(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, 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))[source]#

Extract the state of particles at the given frame.

Parameters:

  • f (int) – Frame 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_frame_add_grad_pos(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, pos_grad: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))[source]#

Accumulate gradients to particle positions for a frame.

Parameters:

  • f (int) – Frame index.

  • pos_grad (ndarray) – Gradient of particle positions, shape (B, n_particles, 3).

set_frame_add_grad_vel(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, vel_grad: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))[source]#

Accumulate gradients to particle velocities for a frame.

Parameters:

  • f (int) – Frame index.

  • vel_grad (ndarray) – Gradient of particle velocities, shape (B, n_particles, 3).

set_frame_add_grad_C(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, C_grad: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))[source]#

Accumulate gradients to affine matrices C for a frame.

Parameters:

  • f (int) – Frame index.

  • C_grad (ndarray) – Gradient of C matrices, shape (B, n_particles, 3, 3).

set_frame_add_grad_F(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, F_grad: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))[source]#

Accumulate gradients to deformation gradients F for a frame.

Parameters:

  • f (int) – Frame index.

  • F_grad (ndarray) – Gradient of F matrices, shape (B, n_particles, 3, 3).

set_frame_add_grad_Jp(f: <gstaichi._lib.core.gstaichi_python.DataTypeCxx object at 0x7d47a6882530>, Jp_grad: NdarrayType(dtype=None, ndim=None, layout=Layout.AOS, needs_grad=None))[source]#

Accumulate gradients to plastic volume ratios Jp for a frame.

Parameters:

  • f (int) – Frame index.

  • Jp_grad (ndarray) – Gradient of Jp values, shape (B, n_particles).

add_grad_from_state(state)[source]#

Accumulate gradients from a recorded state back into the solver.

Parameters:

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

get_particles()[source]#

Retrieve current particle positions from the solver.

Returns:

pos – Array of particle positions, shape (B, n_particles, 3).

Return type:

np.ndarray

get_state()[source]#

Get the current physical state of the particle entity.

Returns:

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

Return type:

MPMEntityState