gs.options.IPCCouplerOptions#

Configures the inter-solver coupler built on Incremental Potential Contact (IPC), including its Newton solver settings. Time step, gravity, and differentiable simulation mode are inherited from SimOptions and should not be set here.

class genesis.options.solvers.IPCCouplerOptions(*, _show_ipc_gui: bool = False, newton_max_iterations: int | None = None, newton_min_iterations: int | None = None, newton_tolerance: float | None = None, newton_ccd_tolerance: float | None = None, newton_use_adaptive_tolerance: bool | None = None, newton_translation_tolerance: float | None = None, newton_semi_implicit_enable: bool | None = None, newton_semi_implicit_beta_tolerance: float | None = None, n_linesearch_iterations: int | None = None, linesearch_report_energy: bool | None = None, linear_system_solver: Literal['linear_pcg', 'direct'] | None = None, linear_system_tolerance: float | None = None, contact_enable: bool | None = None, contact_d_hat: float | None = None, contact_friction_enable: bool | None = None, contact_resistance: float = 1000000000.0, contact_eps_velocity: float | None = None, contact_constitution: Literal['ipc', 'isometric'] | None = None, collision_detection_method: Literal['linear_bvh', 'spatial_hash'] | None = None, cfl_enable: bool | None = None, sanity_check_enable: bool | None = None, constraint_strength_translation: float = 100.0, constraint_strength_rotation: float = 100.0, enable_rigid_ground_contact: bool = True, enable_rigid_rigid_contact: bool = True, two_way_coupling: bool = True, enable_rigid_dofs_sync: bool = False, free_base_driven_by_ipc: bool = False) → None[source]#

Options configuring the Incremental Potential Contact (IPC) coupler.

Time step, gravity, and differentiable simulation mode are derived from SimOptions (dt, gravity, requires_grad) and should not be set here.

Parameters:

  • Options (Genesis Coupling) –

  • --------------------- –

  • newton_max_iterations (int, optional) – Maximum iterations for Newton solver. Defaults to None (use libuipc default: 1024).

  • newton_min_iterations (int, optional) – Minimum iterations for Newton solver. Defaults to None (use libuipc default: 1).

  • newton_tolerance (float, optional) – Velocity tolerance for Newton solver convergence. Defaults to None (use libuipc default: 0.05).

  • newton_ccd_tolerance (float, optional) – CCD (Continuous Collision Detection) tolerance for Newton solver. Defaults to None (use libuipc default: 1.0).

  • newton_use_adaptive_tolerance (bool, optional) – Whether Newton solver should use adaptive tolerance. Defaults to None (use libuipc default: False).

  • newton_translation_tolerance (float, optional) – Translation rate tolerance for Newton solver. Defaults to None (use libuipc default: 0.1).

  • newton_semi_implicit_enable (bool, optional) – Whether to enable semi-implicit Newton solver mode. Defaults to None (use libuipc default: False).

  • newton_semi_implicit_beta_tolerance (float, optional) – Beta tolerance for semi-implicit Newton solver. Defaults to None (use libuipc default: 1e-3).

  • Options –

  • ------------------- –

  • n_linesearch_iterations (int, optional) – Maximum iterations for line search. Defaults to None (use libuipc default: 8).

  • linesearch_report_energy (bool, optional) – Whether to report energy during line search. Defaults to None (use libuipc default: False).

  • Options –

  • --------------------- –

  • linear_system_solver (str, optional) – Linear system solver type. Options: ‘linear_pcg’, ‘direct’, etc. Defaults to None (use libuipc default: ‘linear_pcg’).

  • linear_system_tolerance (float, optional) – Tolerance for linear system solver. Defaults to None (use libuipc default: 1e-3).

  • Options –

  • --------------- –

  • contact_enable (bool, optional) – Whether to enable contact detection. Defaults to None (use libuipc default: True).

  • contact_d_hat (float, optional) – Contact distance threshold. Defaults to None (use libuipc default: 0.01).

  • contact_friction_enable (bool, optional) – Whether to enable friction in contact. Defaults to None (use libuipc default: True).

  • contact_resistance (float, optional) – Ground/default contact resistance/stiffness. It is used for ground contact pairs and as the per-entity fallback when a material does not define contact_resistance. For ground pairs, it is combined with entity material.contact_resistance via geometric mean. Defaults to 1e9.

  • contact_eps_velocity (float, optional) – Epsilon velocity for contact. Defaults to None (use libuipc default: 0.01).

  • contact_constitution (str, optional) – Contact constitution model. Options: ‘ipc’, ‘isometric’. Defaults to None (use libuipc default: ‘ipc’).

  • Options –

  • --------------------------- –

  • collision_detection_method (str, optional) – Collision detection method. Options: ‘linear_bvh’, ‘spatial_hash’, etc. Defaults to None (use libuipc default: ‘linear_bvh’).

  • Options –

  • ----------- –

  • cfl_enable (bool, optional) – Whether to enable CFL (Courant-Friedrichs-Lewy) condition. Defaults to None (use libuipc default: False).

  • Options –

  • -------------------- –

  • sanity_check_enable (bool, optional) – Whether to enable sanity checks. Defaults to None (use libuipc default: True).

  • Options –

  • ------------------------ –

  • constraint_strength_translation (float, optional) – Translation strength for IPC soft transform constraint coupling. Higher values create stiffer position coupling between Genesis rigid bodies and IPC ABD objects. Defaults to 100.0.

  • constraint_strength_rotation (float, optional) – Rotation strength for IPC soft transform constraint coupling. Higher values create stiffer orientation coupling between Genesis rigid bodies and IPC ABD objects. Defaults to 100.0.

  • enable_rigid_ground_contact (bool, optional) – Whether to enable ground contact in IPC system. When False, objects in IPC will not collide with the ground plane. Defaults to True.

  • enable_rigid_rigid_contact (bool, optional) – Whether to enable contact detection between rigid bodies (ABD objects) in the IPC system. When False, only soft-soft and soft-rigid collisions are detected by IPC; rigid-rigid collisions within IPC are skipped. Defaults to True.

  • two_way_coupling (bool, optional) – Whether to apply coupling forces/torques from IPC back to Genesis rigid bodies. Defaults to True.

  • enable_rigid_dofs_sync (bool, optional) – Whether to synchronize the IPC reference DOF state with Genesis each step for external_articulation entities. When True, IPC gets tighter coupling with Genesis joint state but may amplify small divergences. When False, IPC uses its own DOF reference without per-step updates. Defaults to False.

  • free_base_driven_by_ipc (bool, optional) – For external_articulation with non-fixed base: whether base link is fully driven by IPC physics. When False, base link uses SoftTransformConstraint controlled by Genesis. When True, base link is fully driven by IPC physics. Defaults to False.

  • _show_ipc_gui (bool, optional) – [Dev/debug] Enable the libuipc built-in polyscope GUI viewer for inspecting the IPC scene. Defaults to False.