Module system 

Constraint systems: values a solve moves, in blocks (Variables — a number, a pose), and terms on them (Equations) — constraints that hold where their residuals vanish (or, for a limit, stay at most zero), and preferences a solve pulls towards among where the constraints hold. Written once, for every system of the kernel: a sketch’s numbers (geop_core_sketch) and a program’s state, where its parts are (geop_core_program::solve), are each only an Equations.

On a System — the equations, how each block may move, the system’s size — the algorithms are generic:

• Groups. Blocks no term ties together are solved, enclosed and measured apart (System::structure): a plate with hundreds of screws is hundreds of systems of one screw. The answer is the same, since what a solve minimizes is a sum over the groups; a group whose constraints hold and that nothing pulls is not solved at all. Within a group, a block whose constraints only hang it off others — a screw on a bracket, the bracket on a link — is a pendant: solved and enclosed after them, alone ([structure]), so a chain of links carrying hundreds of parts is a small system and hundreds of tiny ones, not one dense system of every part. The groups of a layer are worked on in lockstep ([lockstep]): one evaluation answers every group waiting, so the evaluations a solve takes do not grow with the number of groups.
• Solve (System::solve) by the driver every solve shares ([driver]): the constraints held exactly, the preferences and staying put (Variable::stay) only choosing among where they hold. Each block moves by steps along it (Variable::retract). A limit (Bound::AtMost) is kept by an active set: solved without the limits first, every one the solve ends beyond is held at its bound, and the group is solved again from where it started.
• What holds (System::held), to RELATIVE_TOLERANCE of the size.
• Enclosure (System::enclose): a rigorous box around a true solution near where a solve ended — Krawczyk’s test over the independent rows, chosen over a box — or why there is none to be had: a singular configuration, or constraints that conflict, by name.
• Freedom (System::freedom): how many independent ways each block can still move, decided over the box the enclosure proved. A limit leaves the motion away from it free.
• Conflicts (System::conflicting): a smallest set of constraints that cannot all hold together.

A block is enclosed in its own step coordinates around where it is: a value x = retract(x̃, δ) for a box of steps δ. The Jacobian of a term by δ is its Jacobian by the steps at x — what Equations gives — times the differential of the retraction (Variable::differential): the identity for a number, the right Jacobian of the exponential map for a pose.

Structs

Enclosure

An enclosure of a true solution, group by group, and how free the blocks are (see System::enclose).

Freedom

How free the blocks are (see System::freedom).

Group

Blocks a solve works on together, and the terms on them (see Structure): a core no term ties to another, or a pendant hanging off blocks of earlier layers.

Held

Which constraints hold, and the largest residual: an upper bound, infinite where one cannot be made.

Linearized

A term’s residuals where the blocks are, each a length, and their derivatives: per block it reads, by index, one row per residual — its derivative by that block’s step from where it is.

Phase

One minimization of a solve: why it stopped, after how many steps, and the largest residual it left — an upper bound.

Solution

Where a solve put the blocks, and how it went.

Structure

The groups of a system’s blocks a solve works on (see the module docs), in layers: every group’s Group::on blocks are in groups of earlier layers.

System

A system: its equations, how each block may move — every one a solve may move, Mobility::Held or Mobility::Follows — and its size.

Enums

Bound

What a constraint asks of its residuals.

EncloseError

Why no enclosure of a solution is proven.

Mobility

What a solve may do with a value.

Term

A term of a system: a constraint or a preference, by index.

Constants

DAMPING

How strongly every value a solve may move and nothing pulls is held where it was, as a ratio to a pull, which weighs one: the damping that makes a solve prefer, among the many configurations the constraints allow, the one nearest where things were. A value the constraints leave free stays put; one they need moves as far as they need, and no further.

RELATIVE_TOLERANCE

A residual holds once it is within this fraction of the system’s size: one part in RELATIVE_TOLERANCE.

Traits

Equations

The terms of a system: what an adapter — a sketch, a program — says of its constraints and preferences.

Variable

A value a solve moves: a block of variables, stepped along its own tangent space.

Functions

tolerance

How near zero a residual of a system of size scale must be to hold: one part in RELATIVE_TOLERANCE of it.