interaction contact#

Describes the entry contact at version 0.4.0, registered by mime.interactions.contact.Contact.

Kept registered beside it: contact at version 0.1.0, by mime.interactions._previous.CentreContact, which a document naming that version loads; its differences are in the hand-written part’s versions.

At a glance#

interaction contact, version 0.4.0, namespace mime
Family: contact, with 1 built rung among its members
Rungs built: projection
Derivative: piecewise_jump
Validity: 10 declared lines

What it models, and when not to use it#

A body against a surface#

What it models. A rigid body kept on the free side of a fixed structure’s surface, every point of its hull at least margin from it: the side the surface faces (tube.inner_surface faces the lumen), the body’s orientation read, so a long body turned across a narrow tube meets the wall at its ends and not at its centre.

experiment.attach(Contact.Projection(margin=mm(0.1)), body=umr, surface=tube.inner_surface)

It builds no node of its own. Its record, a confinement, goes to the body’s dynamics at construction, and the dynamics holds the body inside its implicit solve each step and projects the pose back after it (RigidInertialNode is the dynamics that takes it). The hull’s points, sampled at spacing on every patch, are split into groups, and each group is searched from as many places as its shape can hold local deepest points that its samples do not order (counted when the experiment is built). Where the hull’s kind answers the support query (Geometry.support: closed forms for the sphere, the ellipsoid, the cylinder and the capsule, Newton’s steps on its own surface for the screw), the contact holds the body’s own point that a converged search reaches, so the touching point moves continuously along the body as it turns. At each held point the outward velocity is taken away with the body’s rotation coupled in (a turned body touching at two points takes the couple that holds it), inelastic and frictionless, by projected Gauss-Seidel over the points. A body with no hull (no parts, its extent declared) is held as a sphere of its extent about its centre, which is exact for a sphere.

It is admissibility only: it says where the body may be and the force that keeps it there, and it adds no near-wall lubrication, which a drag that includes it declares (Interaction.includes_lubrication); the plan refuses a second law on the body that includes it. One contact per body, against a fixed structure’s surface. Its rung is projection; penalty is reserved. Contact.Projection(...) is Contact(rung="projection", ...) and saves identically.

What a run says of it, as flags: touching where a point takes a force, unconverged where the solve left more of the free step’s speed unmet than its tolerance allows, held_by_samples where a kind with no support query is held at its samples, and support_short where the body may reach past a held point. Its derivative is piecewise: it jumps where two of the body’s own deepest points tie or where a step changes the contact’s branch, as the switches on this page say.

When not to use it.

Where friction, adhesion or a compliant wall matters: it is inelastic, frictionless and rigid, and friction at the contact is to be decided with the near-contact physics.
For flow near the wall: the lubrication that a close wall adds to the drag is the drag’s to include, not the contact’s.
For a hull whose kind has no support query (the box, a lab’s mesh), where the held point is a sample and the hold acts as a friction and a shaking that the spacing sets: the validity lines say so, and held_by_samples flags it (MIME-ANO-131 holds the measurements).
For two bodies against each other: it is only against a fixed structure’s surface.
For a study that moves a setting of the hull far: the groups, their starts and their candidates are fixed from the hull kind’s settings as built, while the points are evaluated each step from the live settings. A derivative in a setting keeps them; a far move keeps the old candidates, which may then seed otherwise than all the points would, and that is not measured.

The surface and its free side. A surface faces the region it bounds, and the contact keeps the body on that side: the scene note.

Versions. contact 0.4.0 chooses each group’s point again in the second pass of the projection after the step, at the pose the first pass left, and holds it beside the first pass’s points: a group can hold two of the body’s local deepest points (a screw’s rim and the crest pass beside it), and the first pass’s turn could leave the one it did not hold past the margin (MIME-ANO-136). 0.3.0, which was in no release, held the first pass’s points alone; it started each group’s search from as many places as the hull’s shape needs and held the point only of a search that converged (MIME-ANO-134 and MIME-ANO-135 record what the earlier search did). 0.2.0, which was in no release, held the hull’s points and climbed a fixed count of steps from the group’s nearest sample. 0.1.0 held the body’s centre by its extent about its own axis and never read its orientation, so a body that turned across a narrow tube passed through the wall (MIME-ANO-131); it stays registered (mime.interactions.KEPT), so a folder saved with it loads and reproduces, and a script that writes Contact gets 0.4.0. For a body whose hull no point reaches the margin of, the body steps as the free body does, to the last bit, in every version.

Settings#

Setting	Type	Default	Dimension	Role	Default’s kind
`margin`	`Annotated[Quantity, Length]`	`{"required": true}`	length (m)	numerical	none
`rule`	`str`	`remove_outward`	none	physical	convention
`rung`	`str \| None`	`null`	none	design	none
`spacing`	`Annotated[Quantity \| None, Length]`	`null`	length (m)	numerical	numerical

Each role and default’s kind is the entry’s setting_roles (mime.registry.SettingRole); a setting that declares none is required.

Each default is a claim (mime.registry.DefaultKind): a determined default is resolved in every profile, a convention taken in every profile, a numerical default taken in exploratory only and stamped pending. Their rules and bases:

rule (convention): the setting’s written default; a frictionless contact that does not bounce: the projection removes the velocity into the surface, a physical model of the contact, not a solver’s choice
spacing (numerical): for a body with a hull, the contact’s margin, no finer than SPACING_FLOOR of the hull’s size: the hull’s points about a margin apart; a stated rule, never a converged value: the body reaches past its points by no more than its farthest point lies from the nearest of them, so a spacing of the margin keeps the body within the margin’s share of it, and a margin too small to say how finely to seed the body takes the floor

Roles, reads and deliveries#

Roles, bound by keyword when the entry is attached: body (body), surface (surface).

Reads, values and deliveries that its plan adds for a particular construction are not in these tables: they list what the class declares, and plan is code the build runs when the entry is attached.

Rungs#

A rung is a section of this page, and the entry’s rung setting names it; there is no default.

Rung projection#

Builds no node of its own.

Supported constructions, by what each bound thing’s dynamics or field provider must offer:

Requires	Note
body: flag projects_confinement, accepts `body.confinement`	the body’s dynamics holds a confinement in its own update

Rung penalty#

Reserved, not built: penalty contact, delivering loads into each side’s applied wrench, comes later

Gradient status#

The derivative through this entry is piecewise_jump: not the exact derivative of what it computes everywhere.

Switches the law evaluates, each declared once by its owner:

Switch	Indicator	Orders, per output group	Route to exact
`contact.band`	the body’s signed distance past its surface shrunk by its extent and margin, m; on the surface within CONTACT_ULPS units in the last place of \|x\| plus that inset (a band)	`pose` -1 (a jump); `twist` -1 (a jump)	a landing located within the step and its time differentiated, as MADDENING’s events will be (planned for MADDENING 0.5 and MIME 0.4.0); until then a fit starts in contact and keeps it
`contact.outward`	the outward speed the solve leaves the body with, less the speed that closes its gap in the step, m/s	`pose` 0 (a kink); `twist` 0 (a kink)	none: the held and free twists are equal where it is zero, and their derivatives are not
`contact.hold`	the outward speed the hold removes while the body is in the band, m/s	`pose` -1 (a jump); `twist` -1 (a jump)	its jump, at the band’s edge, is carried by contact.band’s declaration, whose row measures it: along its own indicator, the outward speed, the held and free twists meet at zero, so its row measures it continuous; the route is contact.band’s, and contact.outward’s across the outward speed
`contact.closing`	the gap to the shrunk surface, m (positive inside)	`pose` 0 (a kink); `twist` 0 (a kink)	none: the speed that closes the gap is its positive part
`contact.scale`	the body’s distance from the world’s origin, m, which the band’s width grows with	`pose` 0 (a kink); `twist` 0 (a kink)	a band width smooth in the position, such as one from a norm smoothed at the origin
`contact.project`	the body’s signed distance past the shrunk surface at the end of the step, m	`pose` 0 (a kink)	none: the projection removes that distance’s positive part
`contact.rule`	the body’s signed distance past the shrunk surface at the end of the step, m	`twist` -1 (a jump)	as contact.band’s: a landing located within the step
`contact.rule_outward`	the velocity’s component along the outward normal where the body was projected, m/s	`twist` 0 (a kink)	none: the rule removes that component’s positive part
`contact.point`	for a kind with a support, the gap of the deepest point a group’s starts reach apart from the one it keeps, less the kept one’s; for a kind held by its samples, the gap of a group’s second nearest candidate to the shrunk surface less its nearest’s; m (zero where two tie)	`pose` -1 (a jump); `twist` -1 (a jump)	none where the hull’s kind has a support: each start only seeds the body’s own deepest point near it, which two starts of one surface’s neighbourhood reach alike, and the group keeps the deepest point its starts reach, so the step jumps only where two of the body’s own local deepest points tie (a screw’s crest passes and rims, a cylinder’s ends), as the body’s contact does; for a kind held by its samples the point moves from one sample to the next, a jump falling with the spacing
`contact.search`	for a kind with a support, how far within its tolerance (the square root of the dtype’s resolution of the hull’s size) a group’s search, after its bounded steps, stands of the support at its direction, m (negative where it has not converged)	`pose` -1 (a jump); `twist` -1 (a jump)	none: a search that has not converged within its bounded steps has no point of its own to hold, its last step’s point set by the rounding, so the group holds its nearest place, a point of the body; a longer bound moves where the switch lies, not its jump
`contact.gap`	a held point’s gap to the shrunk surface at the step’s start, m (positive inside)	`pose` 0 (a kink); `twist` 0 (a kink)	none: the speed a point may close in the step is its gap’s positive part
`contact.impulse`	the force a sweep’s update leaves a held point, N (negative where it would pull the body to the surface)	`pose` 0 (a kink); `twist` 0 (a kink)	none: a point takes a force where the step would move it into the surface faster than its gap allows, and the twists either side meet where that force is zero; the derivative is that of the active set
`contact.push`	the multiplier a sweep of the projection after the step leaves a point, kg m (negative where it would pull the point outward)	`pose` 0 (a kink)	none: the projection moves a point back to the shrunk surface where it ended past it, and the poses either side meet where it ends on it

Validity#

Declared validity lines: free text, not parsed, and not yet checked against the operating point or the region each one describes.

projection: a rigid body against a fixed surface, each point at least the margin from it: where the hull’s kind answers the support query (the sphere, the ellipsoid, the cylinder, the capsule: closed forms; the screw: Newton’s steps on its own surface), at the body’s own point the search from the deepest of each group’s starts converges to (its nearest sample and each next nearest apart from those taken, as many as the hull’s shape can hold local deepest points against a flat wall), so the body keeps the margin to the support’s convergence (rounding); within the samples’ shortfall where a group’s search does not converge within its bound and the group holds its nearest sample, raising support_short when that sample is within the margin; the starts are counted against a flat wall, and against a curved one more of a group’s places can stand within the shortfall, unflagged (measured on screws at the coarsest spacings the guard admits, MIME-ANO-134 records how often); a kind with neither (the box, a lab’s mesh) at its samples, so the body reaches past them by up to their shortfall (the build report states it, and a spacing whose shortfall passes the margin is refused)
projection: a kind held by its samples is held at them, not at its line of contact, and a turning body’s samples arrive at the wall off it: the inelastic hold acts as a friction and a shaking set by the spacing, which a body of revolution spun on the floor shows by losing most of its spin, and script A’s screw by a contact that carries a share of the field’s torque (MIME-ANO-131 records the measurements, by samples and by support), raising the flag held_by_samples
projection: a screw held by its support still loses part of its spin rolling on the floor, where a smooth cylinder keeps its spin to the last bit, by an amount nearly flat in the spacing (MIME-ANO-131 records it), its cause not shown
projection: the margin is kept to what a fixed count of sweeps leaves: two points whose rows are coupled at c converge by c squared a sweep, and a body pressed into both walls with short levers is held to that, the pose projected back after the step taking the rest; the solve’s residual is the state’s contact_residual, and a step that leaves more than CONVERGED of the free step’s speed at the held points unmet raises unconverged: it reads the motion at those points, and a harder drive reads smaller for the same speed left unmet, not how far each point’s force is, which rows sharing a rim do not fix
projection: inelastic and frictionless (no traction along the surface, no static friction, no adhesion): friction at the contact is to be decided with the near-contact physics, and its seam is left in the sweeps
projection: admissibility only: it adds no near-wall lubrication, which a drag that includes it declares, and the plan refuses a second law on the body that includes it
projection: a rigid surface and a rigid body: no compliance of the wall or the body
projection: each step it holds one point of each of the hull’s eight groups, the deepest its starts reach: a body touching in more places than its groups (a screw lying along the floor on several crest passes in one group) is held at the group’s deepest of them, the rest taken by the projection after the step when they pass the margin: its first pass holds each group’s deepest where the step ended, its second each group’s deepest where the first left the body, beside the first’s points, and what the second’s turn leaves past the margin the next step takes
projection: the starts a group takes, its places and the samples’ shortfall are counted from the hull’s settings as built, as its candidates are: a study that moves a setting far keeps them
projection: a body with no hull is held as a sphere of its declared extent about its centre

Family#

Declared: contact. The family’s conformance suite is run by a test of the lab or of MIME; which test, and in which lane, is resolved when the evidence resolver lands.

References#

[@StewartTrinkle1996]

Other declarations#

Class variable	Type	Value
`holds_off`	`ClassVar[str \| None]`	`margin`
`id_roles`	`ClassVar[tuple[str, ...] \| None]`	`null`
`moving`	`ClassVar[bool]`	`false`