fedoo.constraint.IPCContact

class IPCContact(mesh, surface_mesh=None, extract_surface=False, dhat=0.001, dhat_is_relative=True, barrier_stiffness=None, friction_coefficient=0.0, eps_v=0.001, broad_phase='lbvh', adaptive_barrier_stiffness=True, use_ccd=None, line_search_energy=None, use_ogc=False, use_area_weighting=False, dmin=0.0, name='IPC Contact', space=None)

Contact Assembly based on the IPC (Incremental Potential Contact) method.

Uses the ipctk library to guarantee intersection-free configurations through barrier potentials and optional CCD (Continuous Collision Detection) line search.

The IPC method adds a barrier energy term \(\kappa\,B(\mathbf{x})\) to the total potential energy. The barrier \(B\) grows to infinity as the distance between surfaces approaches zero and vanishes when the distance exceeds dhat. This guarantees that the deformed configuration remains intersection-free at every Newton–Raphson iteration.

Barrier stiffness auto-tuning — When barrier_stiffness is left to None (recommended), the stiffness \(\kappa\) is automatically initialised by ipctk.initial_barrier_stiffness so that it balances the elastic and barrier energy gradients. If no contact exists at the initial configuration (common for self-contact problems), \(\kappa\) is re-initialised the first time collisions appear, using the actual elastic forces at that stage. Afterwards, \(\kappa\) is updated adaptively at each converged time increment via ipctk.update_barrier_stiffness.

Convergence safeguards (SDI) — When the set of active collisions changes during a Newton–Raphson iteration (new contacts appear or existing ones separate), or when the minimum gap drops below 0.1 × d_hat, the solver is forced to perform at least one additional NR iteration even if the displacement criterion is already satisfied. When surfaces are dangerously close (gap < 0.01 × d_hat), at least three extra iterations are forced. This prevents premature convergence when the contact state is still evolving.

CCD line search — When use_ccd=True, the Newton–Raphson step size is clamped to the largest value that keeps all surfaces intersection-free. For the elastic prediction of an increment where no contacts existed at the start, a conservative minimum distance of 0.1 × d_hat is enforced to prevent surfaces from jumping deep into the barrier zone. If this conservative bound yields a zero step (e.g. due to shared mesh edges at zero distance in self-contact), the CCD falls back to the standard min_distance=0 computation.

OGC trust-region — When use_ogc=True, the Offset Geometric Contact (OGC) trust-region method from ipctk.ogc replaces CCD. Instead of uniformly scaling the displacement step by a single scalar, OGC filters the displacement per vertex, clamping each vertex’s move to lie within a trust region that guarantees no intersection. This can provide better convergence by not penalising distant vertices for a tight contact elsewhere. use_ogc and use_ccd are mutually exclusive.

Warning

OGC is only supported for shell / surface meshes where every node lies on the contact surface. Solid meshes with interior nodes must use use_ccd=True instead. An error is raised at initialization if use_ogc=True is used with a solid mesh.

Axisymmetric (2Daxi) — ipctk has no axisymmetric mode: it sees a planar curve in the (r, z) plane. Under a "2Daxi" ModelingSpace each planar collision stands for a ring of contact, so its weight in the barrier potential is multiplied by the circumference 2*pi*R at the contact point (R is the reference radius of the colliding vertex, consistent with ipctk’s rest-configuration weights). The potential then reads \(\kappa \sum_k 2\pi R_k\, w_k\, b(d_k)\) and ipctk returns the matching energy, gradient and hessian, so that the residual, the tangent matrix, the energy line search, the barrier stiffness auto-tuning and friction all use the same weighting. In particular the axial contact forces of a collision pair sum to zero. Vertices on the symmetry axis (r = 0) get weight 0, which is geometrically correct (a ring of zero radius collapses to a point). The planar (r, z) distance equals the true 3D minimum distance between the corresponding circles (closest points share the azimuth), so the barrier distance and CCD are unchanged. The symmetry axis itself is not a contact surface: a bore closing onto the axis is not detected. use_ogc is not available in 2Daxi. Combined with use_area_weighting=True the weight of a collision is the actual area 2*pi*R*ds of the ring, i.e. the axisymmetric reduction of the 3D convergent formulation.

Parameters:

mesh (fedoo.Mesh) – Full volumetric mesh (needed for DOF compatibility).
surface_mesh (fedoo.Mesh, optional) – Pre-extracted surface mesh (lin2 in 2D, tri3 in 3D).
extract_surface (bool, default=False) – If True, automatically extract the surface from the volumetric mesh.
dhat (float, default=1e-3) – Barrier activation distance. Pairs of primitives closer than dhat receive a repulsive barrier force. A smaller value gives a tighter contact (less visible gap) but requires finer time steps.
dhat_is_relative (bool, default=True) – If True, dhat is interpreted as a fraction of the bounding box diagonal of the surface mesh.
dmin (float, default=0.0) – Minimum separation between collision primitives, in absolute model length units, independently of dhat_is_relative. The barrier activates below dmin + dhat and diverges at dmin. For two equal-radius beam centerlines, use their diameter (2 * radius). The initial configuration must have separation strictly above dmin. Connected joints may require a collision filter. Nonzero offsets are not supported with use_ogc=True.
barrier_stiffness (float, optional) – Barrier stiffness \(\kappa\). If None (default), it is automatically computed and adaptively updated — this is the recommended setting. When specified explicitly, the value is kept fixed unless adaptive_barrier_stiffness is True, in which case it is used as the initial value and may be updated.
friction_coefficient (float, default=0.0) – Coulomb friction coefficient \(\mu\). Set to 0 for frictionless contact.
eps_v (float, default=1e-3) – Friction smoothing threshold (only relevant when friction_coefficient > 0): slip over a time increment below which the friction force is regularized. Friction is lagged: the normal forces and sliding directions are those of the start of the increment.
broad_phase (str, default="lbvh") – Broad-phase collision detection method. One of "lbvh", "hash_grid", "brute_force" or "spatial_hash".
adaptive_barrier_stiffness (bool, default=True) – If True, \(\kappa\) is updated adaptively at each converged time increment using ipctk.update_barrier_stiffness.
use_ccd (bool, optional) – Enable Continuous Collision Detection (CCD) line search. When active, the Newton–Raphson step size is limited to prevent interpenetration between iterations. Default is True unless use_ogc is enabled. Note: use_ccd and use_ogc are mutually exclusive.
line_search_energy (bool or None, default=None) – Controls energy-based backtracking after CCD line search. The step is halved until total energy (exact barrier + quadratic elastic approximation) decreases. When None (default), automatically enabled when use_ccd=True — this matches the reference IPC algorithm. Set to False to disable (faster but may degrade convergence). Has no effect when use_ogc is enabled.
use_ogc (bool, default=False) – Enable OGC (Offset Geometric Contact) trust-region step filtering. Per-vertex displacement clamping replaces the uniform scalar step of CCD. Mutually exclusive with use_ccd. Only supported for shell / surface meshes where all nodes are on the surface; raises ValueError for solid meshes with interior nodes.
use_area_weighting (bool, default=False) – Use the convergent IPC formulation [Li et al. 2023]: each collision is weighted by the rest area (length in 2D, ring area 2*pi*R*ds in 2Daxi) of the surface it represents, together with the improved max approximation. The contact response then no longer depends on the surface mesh density.
name (str, default="IPC Contact") – Name of the contact assembly.
space (ModelingSpace, optional) – Modeling space. If None, the active ModelingSpace is used.

Notes

The IPC assembly is used by adding it to the structural assembly with fedoo.Assembly.sum():

solid = fd.Assembly.create(wf, mesh)
ipc   = fd.constraint.IPCContact(mesh, surface_mesh=surf)
assembly = fd.Assembly.sum(solid, ipc)

When using add_output, pass the solid assembly (not the sum) to avoid errors.

`IPCContact.add_rigid_body`(rigid_body[, ...])	Register a `RigidBody` with this IPCContact.
`IPCContact.assemble_global_mat`([compute])	Recompute barrier contributions from cached vertex positions.
`IPCContact.delete_global_mat`()	Delete Global Matrix and Global Vector related to the assembly.
`IPCContact.get_all`()	Return a dict with all the known Assembly (with a name).
`IPCContact.get_global_matrix`()	Get the last computed global matrix.
`IPCContact.get_global_vector`()	Get the last computed global vector.
`IPCContact.initialize`(pb)	Initialize the IPC contact assembly.
`IPCContact.iter_leaf`()	Iterate over the leaf assemblies contained in this object.
`IPCContact.register_global_dofs`(pb)	Register global DOFs required by the assembly on a problem.
`IPCContact.reset`()	Reset the assembly.
`IPCContact.set_start`(pb)	Begin a new time increment.
`IPCContact.to_start`(pb)	Restart the current time increment after NR failure.
`IPCContact.update`(pb[, compute])	Update the IPC assembly for the current Newton–Raphson iteration.

`IPCContact.name`	Name of the assembly if defined.
`IPCContact.space`	Modeling space associated to the assembly.
`IPCContact.current`	Assembly associated to the mesh of the deformed geometry.
`IPCContact.associated_assembly_sum`	AssemblySum object that contains the assembly.