SAPCoupler

The SAPCoupler resolves cross-solver contact with the Semi-Analytic Primal (SAP) contact solver used in Drake. It targets accurate rigid-deformable contact, including hydroelastic contact against implicit FEM bodies. Select it by passing gs.options.SAPCouplerOptions to the scene.

Options

class genesis.options.solvers.SAPCouplerOptions(*, n_sap_iterations: int = 5, n_pcg_iterations: int = 100, n_linesearch_iterations: int = 10, sap_convergence_atol: float = 1e-06, sap_convergence_rtol: float = 1e-05, sap_taud: float = 0.1, sap_beta: float = 1.0, sap_sigma: float = 0.001, pcg_threshold: float = 1e-06, linesearch_ftol: float = 1e-06, linesearch_max_step_size: float = 1.5, hydroelastic_stiffness: float = 100000000.0, point_contact_stiffness: float = 100000000.0, fem_floor_contact_type: Literal['tet', 'vert', 'none'] = 'tet', enable_fem_self_tet_contact: bool = True, rigid_floor_contact_type: Literal['tet', 'vert', 'none'] = 'tet', enable_rigid_fem_contact: bool = True, rigid_rigid_contact_type: Literal['tet', 'vert', 'none'] = 'tet') → None

Options configuring the inter-solver coupling for the Semi-Analytic Primal (SAP) contact solver used in Drake.

Note

Paper reference: https://arxiv.org/abs/2110.10107 Drake reference: https://drake.mit.edu/release_notes/v1.5.0.html

Parameters:

• n_sap_iterations (int, optional) – Number of iterations for the SAP solver. Defaults to 5.

• n_pcg_iterations (int, optional) – Number of iterations for the Preconditioned Conjugate Gradient solver. Defaults to 100.

• n_linesearch_iterations (int, optional) – Max number of iterations for the line search solver. Defaults to 10.

• sap_convergence_atol (float, optional) – Absolute tolerance for SAP convergence. Defaults to 1e-6.

• sap_convergence_rtol (float, optional) – Relative tolerance for SAP convergence. Defaults to 1e-5.

• sap_taud (float, optional) – Dissipation time scale for SAP. Defaults to 0.1.

• sap_beta (float, optional) – Normal regularization parameter for SAP. Defaults to 1.0.

• sap_sigma (float, optional) – Friction regularization parameter for SAP. Defaults to 1e-3.

• pcg_threshold (float, optional) – Threshold for the Preconditioned Conjugate Gradient solver. Defaults to 1e-6.

• linesearch_ftol (float, optional) – Line search sufficient value close to zero for exact linesearch. Defaults to 1e-6.

• linesearch_max_step_size (float, optional) – Maximum step size for exact linesearch. Defaults to 1.5.

• hydroelastic_stiffness (float, optional) – Stiffness for hydroelastic contact. Defaults to 1e8.

• point_contact_stiffness (float, optional) – Stiffness for point contact. Defaults to 1e8.

• fem_floor_contact_type (str, optional) – Type of contact against the floor. Defaults to “tet”. Can be “tet”, “vert”, or “none”. TET would be the default choice for most cases. VERT would be preferable when the mesh is very coarse, such as a single cube or a tetrahedron.

• enable_fem_self_tet_contact (bool, optional) – Whether to use tetrahedral based self-contact. Defaults to True.

• rigid_rigid_type (str, optional) – Type of contact between rigid bodies. Defaults to “tet”. Can be “tet”, “vert”, or “none”.

• rigid_floor_contact_type (str, optional) – Type of contact against the floor. Defaults to “tet”. Can be “tet”, “vert”, or “none”. Tet would be the default choice for most cases. Vert would be preferable when the mesh is very coarse, such as a single cube or a tetrahedron.

• enable_rigid_fem_contact (bool, optional) – Whether to enable coupling between rigid and FEM solvers. Defaults to True.

SAPCoupler

class genesis.engine.couplers.sap_coupler.SAPCoupler(simulator: Simulator, options: SAPCouplerOptions)

Bases: RBC

This class handles all the coupling between different solvers using the Semi-Analytic Primal (SAP) contact solver used in Drake.

Note

For now all batches have the same constraints, such as joint equality constraints are consistent among all batches. Paper reference: https://arxiv.org/abs/2110.10107 Drake reference: https://drake.mit.edu/release_notes/v1.5.0.html Code reference: RobotLocomotion/drake

build() → None

reset(envs_idx=None)

rigid_update_volume_verts_pressure_gradient(geoms_state: GeomsState)

rigid_compute_pressure_gradient_rest()

preprocess(i_step)

precompute(i_step)

update_contact(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, links_info: ~genesis.utils.array_class.LinksInfo, faces_info: ~genesis.utils.array_class.FacesInfo, verts_info: ~genesis.utils.array_class.VertsInfo, free_verts_state: ~genesis.utils.array_class.VertsState, fixed_verts_state: ~genesis.utils.array_class.VertsState, geoms_info: ~genesis.utils.array_class.GeomsInfo, dofs_state: ~genesis.utils.array_class.DofsState, links_state: ~genesis.utils.array_class.LinksState) → tuple[bool, bool]

couple(i_step)

couple_grad(i_step)

update_vel(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, dofs_state: ~genesis.utils.array_class.DofsState)

update_fem_vel(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

update_rigid_vel(dofs_state: DofsState)

fem_compute_pressure_gradient(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

update_bvh(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

update_fem_surface_tet_bvh(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

update_rigid_tri_bvh()

update_rigid_tet_bvh()

compute_fem_surface_tet_aabb(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

compute_rigid_tri_aabb(faces_info: FacesInfo, free_verts_state: VertsState, fixed_verts_state: VertsState, verts_info: VertsInfo)

compute_rigid_tet_aabb()

sap_solve(i_step)

check_sap_convergence(rigid_info: RigidInfo)

clear_sap_norms()

add_fem_norms()

add_rigid_norms(rigid_info: RigidInfo)

update_batch_active()

compute_regularization(dofs_state: DofsState, entities_info: EntitiesInfo, rigid_info: RigidInfo)

compute_unconstrained_gradient_diag(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, iter: int)

init_unconstrained_gradient_diag(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

init_fem_unconstrained_gradient_diag(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

init_rigid_unconstrained_gradient(dofs_state: DofsState)

compute_unconstrained_gradient()

compute_fem_unconstrained_gradient()

compute_rigid_unconstrained_gradient(rigid_info: RigidInfo)

compute_constraint_contact_gradient_hessian_diag_prec()

clear_impulses()

clear_fem_impulses()

clear_rigid_impulses()

compute_preconditioner()

compute_fem_preconditioner()

compute_fem_pcg_matrix_vector_product()

compute_rigid_pcg_matrix_vector_product(rigid_info: RigidInfo)

compute_elastic_products(i_b, i_e, S, i_vs, src)

compute_fem_matrix_vector_product(src, dst, active)

Compute the FEM matrix-vector product, including mass matrix and elasticity stiffness matrix.

init_pcg_solve(entities_info: EntitiesInfo, rigid_info: RigidInfo)

init_pcg_state()

init_fem_pcg_solve()

compute_rigid_mass_mat_vec_product(vec, out, active, rigid_info: RigidInfo)

Compute the rigid mass matrix-vector product.

rigid_solve_pcg(vec, out, entities_info: EntitiesInfo, rigid_info: RigidInfo)

rigid_solve_jacobian(vec, out, n_contact_pairs, i_bs, dim, entities_info: EntitiesInfo, rigid_info: RigidInfo)

init_rigid_pcg_solve(entities_info: EntitiesInfo, rigid_info: RigidInfo)

init_pcg_active()

one_pcg_iter()

compute_pcg_matrix_vector_product(rigid_info: RigidInfo)

Compute the matrix-vector product Ap used in the Preconditioned Conjugate Gradient method.

clear_pcg_state()

compute_pcg_pTAp()

Compute the product p^T @ A @ p used in the Preconditioned Conjugate Gradient method.

Notes

Reference: https://en.wikipedia.org/wiki/Conjugate_gradient_method#The_preconditioned_conjugate_gradient_method

compute_fem_pcg_pTAp()

compute_rigid_pcg_pTAp()

compute_alpha()

compute_pcg_state(entities_info: EntitiesInfo, rigid_info: RigidInfo)

compute_fem_pcg_state()

compute_rigid_pcg_state(entities_info: EntitiesInfo, rigid_info: RigidInfo)

check_pcg_convergence()

compute_p()

compute_fem_p()

compute_rigid_p()

pcg_solve()

compute_total_energy(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, energy: <quadrants.types.annotations.Template object at 0x797f487713a0>, dofs_state: ~genesis.utils.array_class.DofsState, rigid_info: ~genesis.utils.array_class.RigidInfo)

compute_fem_energy(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, energy: <quadrants.types.annotations.Template object at 0x797f48380ec0>)

compute_rigid_energy(energy: <quadrants.types.annotations.Template object at 0x797f4838b140>, dofs_state: ~genesis.utils.array_class.DofsState, rigid_info: ~genesis.utils.array_class.RigidInfo)

init_exact_linesearch(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, dofs_state: ~genesis.utils.array_class.DofsState, rigid_info: ~genesis.utils.array_class.RigidInfo)

init_newton_linesearch()

compute_line_energy_gradient_hessian(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, dofs_state: ~genesis.utils.array_class.DofsState)

init_linesearch_energy_gradient_hessian()

compute_fem_gradient_alpha(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

compute_rigid_gradient_alpha(dofs_state: DofsState)

compute_fem_energy_alpha(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, energy: <quadrants.types.annotations.Template object at 0x797f4838af30>)

compute_rigid_energy_alpha(energy: <quadrants.types.annotations.Template object at 0x797f487e47a0>, dofs_state: ~genesis.utils.array_class.DofsState)

prepare_search_direction_data(rigid_info: RigidInfo)

compute_d2ellA_dalpha2()

compute_fem_d2ellA_dalpha2()

compute_rigid_d2ellA_dalpha2()

prepare_fem_search_direction_data()

prepare_rigid_search_direction_data(rigid_info: RigidInfo)

check_initial_exact_linesearch_convergence()

update_initial_fem_state()

update_initial_rigid_state()

one_linesearch_iter(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

update_velocity_linesearch()

update_fem_velocity_linesearch()

update_rigid_velocity_linesearch()

exact_linesearch(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>)

Note

Exact line search using rtsafe RobotLocomotion/drake

one_exact_linesearch_iter(i_step: <quadrants._lib.core.quadrants_python.DataTypeCxx object at 0x798033d1b9b0>, dofs_state: ~genesis.utils.array_class.DofsState)

compute_f_df_bracket()

Compute the function (derivative of total energy) value and its derivative to alpha. Update the bracket for the next step size.

The bracket is defined by [alpha_min, alpha_max] which is the range that contains the root of df/dalpha = 0.

find_next_step_size()

property active_solvers

All the active solvers managed by the scene’s simulator.

See also

• Couplers: coupler overview and how to choose one.

• Coupling: the theory behind each coupler.