Skip to content

Goals¤

A goal describes a target property of an equilibrium state — a coordinate, a length, a force, an angle — that an optimizer should steer the structure toward. Goals are collected into an error term of a loss function.

Base classes¤

goals ¤

Goal ¤

The base class for all goals.

Attributes:

  • key (Int[Array, ...]) –

    The key of the element the goal acts on. A sequence of keys (a list or a tuple) only for aggregate goals.

  • target (Float[Array, ...]) –

    The value the goal drives its quantity of interest toward.

  • weight (Float[Array, ...]) –

    The relative importance of the goal in the loss.

Notes

A goal is a registered JAX pytree (an equinox Module): its key, target, and weight are dynamic array leaves. Construction stores one element's values unbatched, so a goal is a single-element object; a collection stacks same-type goals along a new leading axis and the error term vmaps the goal over it. The key is resolved to an index against an equilibrium structure at evaluation time. Subclasses supply the quantity of interest via prediction; the target's shape is whatever that prediction returns (a scalar, an xyz vector, or an arbitrary per-element array), and __call__ checks the two agree.

A per-element goal takes exactly one element key; to act on many elements, create one goal per element and let collections vectorize them. Only aggregate goals, which declare is_aggregate = True, accept a list of keys.

goal ¤
goal(target: Float[Array, ...], prediction: Float[Array, ...]) -> Float[Array, ...]

The reference value the prediction is compared against.

Parameters:

  • target (Float[Array, ...]) –

    The goal's target value.

  • prediction (Float[Array, ...]) –

    The current value of the quantity of interest.

Returns:

  • goal ( Float[Array, ...] ) –

    The reference value. The base goal returns the target unchanged; subclasses may combine it with the prediction (e.g. projections).

prediction ¤
prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, ...]) -> Float[Array, ...]

Extract the quantity of interest for one element from an equilibrium state.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the quantity from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against, so a goal can read whole trace-time constants (connectivity, topology) from it. Most goals ignore it.

  • index (Int[Array, ...]) –

    The element index, one for a per-element goal or the whole index row for an aggregate goal. A goal carrying an extra per-element array reads it off self.

Returns:

  • prediction ( Float[Array, ...] ) –

    The current value of the quantity of interest.

keys_from_structure ¤
keys_from_structure(structure: EquilibriumStructure) -> Int[ndarray, 'elements ...']

The structure's canonical keys for this goal's vocabulary.

Parameters:

  • structure (EquilibriumStructure) –

    The structure whose element ordering defines the index.

Returns:

  • keys_canonical ( Int[ndarray, 'elements ...'] ) –

    The node, edge, vertex, or face key ordering the goal's key is resolved against, one entry per element: a node/vertex/face key, or an edge key pair.

Notes

The only per-subclass part of key resolution: a subclass names the canonical ordering its key belongs to (nodes, vertices, faces, or edge pairs) and raises if the structure is the wrong kind. The resolution itself lives once in index, so an author who defines a goal on a new vocabulary overrides this hook alone.

index ¤
index(structure: EquilibriumStructure) -> Int[Array, ...]

The goal's element index, resolved against the structure.

Parameters:

  • structure (EquilibriumStructure) –

    The structure whose element ordering defines the index.

Returns:

  • index ( Int[Array, ...] ) –

    A single index for a per-element goal, or the whole index row for an aggregate goal, which reads its whole selection in one prediction.

Notes

The real work of key resolution: a subclass names its canonical keys via keys_from_structure, and this resolves the goal's key against them in one indices_from_keys call, never a per-key loop. The key stays a compile-time constant (a goal is closed over, never a jitted argument), so the resolution folds to a constant at trace time. The key's own shape distinguishes a per-element goal from an aggregate, so there is no aggregate special case here.

__call__ ¤
__call__(eqstate: EquilibriumState, structure: EquilibriumStructure) -> GoalState

Evaluate the goal for one element against an equilibrium state.

Parameters:

  • eqstate (EquilibriumState) –

    The equilibrium state to evaluate the goal on.

  • structure (EquilibriumStructure) –

    The structure whose element ordering resolves the goal's index.

Returns:

  • goal_state ( GoalState ) –

    The goal state bundling the reference value, the prediction, and the weight for this one element, in the raw shape its hooks return.

Raises:

  • ValueError –

    If the goal and prediction shapes disagree, typically because a scalar goal's prediction returned more than one value per element.

Notes

A goal holds one element, so this is the linear per-element body: resolve the index, read the prediction, form the reference, check the two shapes agree, and bundle the state. A standalone call returns one element's unbatched state.

To evaluate a group of same-type goals, stack them into one pytree and vmap, exactly as one maps any equinox module over a batch::

stacked = tree_stack(goals)
states = jax.vmap(lambda g: g(eqstate, structure))(stacked)

tree_stack is a convenience, not a requirement: a plain tree_map(lambda *leaves: jnp.stack(leaves), *goals) builds the same stacked pytree, so the idiom holds for any stack of a goal's leaves.

evaluate ¤
evaluate(datastructure: FDNetwork | FDMesh, sparse: bool = True) -> GoalState

Evaluate the goal directly on a datastructure, without an optimization.

Parameters:

  • datastructure (FDNetwork | FDMesh) –

    The network or mesh to read the equilibrium state from. Its geometry is used as-is; no form-finding is run.

  • sparse (bool, default: True ) –

    If True, assemble the equilibrium state with the sparse model.

Returns:

  • goal_state ( GoalState ) –

    The goal state bundling the reference value, the prediction, and the weight for this one element.

Notes

A convenience for prototyping a goal on the high-level COMPAS layer: it reads the equilibrium state and structure off the datastructure and evaluates the goal against them in one call.

GoalState ¤

The evaluated state of a goal at an equilibrium state.

Attributes:

  • goal (Float[Array, ...]) –

    The reference value the prediction is compared against.

  • weight (Float[Array, ...]) –

    The relative importance of the goal in the loss.

  • prediction (Float[Array, ...]) –

    The current value of the goal's quantity of interest.

Node goals¤

NodePointGoal ¤

Drive a node toward target xyz coordinates.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, 3]

The current xyz coordinates of the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the coordinates from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, 3] ) –

    The node's xyz coordinates.

NodeLineGoal ¤

Pull a node onto a target line, defined by two points.

Notes

The target is the two points of the line, one (2, 3) array per element; tree_stack adds the leading element axis when goals are grouped.

goal ¤

goal(target: Float[Array, '2 3'], prediction: Float[Array, 3]) -> Float[Array, 3]

The point on the target line closest to the node.

Parameters:

  • target (Float[Array, '2 3']) –

    The two points defining the target line.

  • prediction (Float[Array, 3]) –

    The current node coordinates.

Returns:

  • goal ( Float[Array, 3] ) –

    The closest point on the (infinite) line through the two points.

NodePlaneGoal ¤

Pull a node onto a target plane, defined by a point and a normal.

Notes

The target is the plane's origin and normal, one (2, 3) array per element; tree_stack adds the leading element axis when goals are grouped.

goal ¤

goal(target: Float[Array, '2 3'], prediction: Float[Array, 3]) -> Float[Array, 3]

The point on the target plane closest to the node.

Parameters:

  • target (Float[Array, '2 3']) –

    The origin and normal defining the target plane.

  • prediction (Float[Array, 3]) –

    The current node coordinates.

Returns:

  • goal ( Float[Array, 3] ) –

    The orthogonal projection of the node onto the plane.

NodeSegmentGoal ¤

Pull a node onto a target segment, defined by its two endpoints.

goal ¤

goal(target: Float[Array, '2 3'], prediction: Float[Array, 3]) -> Float[Array, 3]

The point on the target segment closest to the node.

Parameters:

  • target (Float[Array, '2 3']) –

    The two endpoints of the target segment.

  • prediction (Float[Array, 3]) –

    The current node coordinates.

Returns:

  • goal ( Float[Array, 3] ) –

    The closest point on the segment, clamped to lie between the endpoints.

NodeXCoordinateGoal ¤

Drive a node toward a target X coordinate.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The current X coordinate of the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the coordinate from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, ''] ) –

    The node's X coordinate.

NodeYCoordinateGoal ¤

Drive a node toward a target Y coordinate.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The current Y coordinate of the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the coordinate from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, ''] ) –

    The node's Y coordinate.

NodeZCoordinateGoal ¤

Drive a node toward a target Z coordinate.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The current Z coordinate of the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the coordinate from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, ''] ) –

    The node's Z coordinate.

NodeResidualForceGoal ¤

Drive the residual force magnitude at a node toward a target value.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The magnitude of the residual force at the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the residual from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, ''] ) –

    The Euclidean magnitude of the node's residual force.

NodeResidualVectorGoal ¤

Drive the residual force at a node toward a target vector.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, 3]

The residual force vector at the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the residual from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, 3] ) –

    The node's residual force vector.

NodeResidualDirectionGoal ¤

Drive the residual force at a node toward a target direction.

Notes

Both the prediction and the target are unit-normalized, so only direction is compared while magnitude is ignored. Euclidean distance between the normalized vectors gives the same ordering as cosine distance, without the cost of trigonometric operations.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, 3]

The unit direction of the residual force at the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the residual from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, 3] ) –

    The normalized residual force vector.

goal ¤

goal(target: Float[Array, 3], prediction: Float[Array, 3]) -> Float[Array, 3]

The unit direction of the target vector.

Parameters:

  • target (Float[Array, 3]) –

    The target direction vector.

  • prediction (Float[Array, 3]) –

    The current normalized residual, unused.

Returns:

  • goal ( Float[Array, 3] ) –

    The normalized target vector.

NodeResidualPlaneGoal ¤

Drive the residual vector at a node to lie in a target plane.

Notes

The residual is a vector, not a point, so the target plane passes through the origin and is described by its normal vector alone. The normal is unit-normalized internally, as the projection formula is only correct for a unit normal, so the input normal does not have to be unit-length.

The goal returns the residual direction's projection onto the plane, which is the closest in-plane vector to the current prediction. The error term prediction - goal is then the out-of-plane component of the residual direction, which vanishes exactly when the residual lies in the plane.

The prediction is unit-normalized too so that the error depends on direction alone: it measures the sine of the angle between the residual vector and the plane, and cannot be reduced by shrinking the reaction magnitude instead of rotating the reaction into the plane.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, 3]

The unit direction of the residual vector at the node.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the residual from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the node.

Returns:

  • prediction ( Float[Array, 3] ) –

    The normalized residual vector.

goal ¤

goal(target: Float[Array, 3], prediction: Float[Array, 3]) -> Float[Array, 3]

The projection of the predicted residual direction onto the target plane.

Parameters:

  • target (Float[Array, 3]) –

    The target plane's normal vector.

  • prediction (Float[Array, 3]) –

    The current normalized residual direction.

Returns:

  • goal ( Float[Array, 3] ) –

    The prediction projected onto the target plane.

NodesColinearGoal ¤

NodesColinearGoal(key: Sequence[int], weight: float = 1.0)

Minimize length-normalized colinearity energy for an ordered sequence of points. This goal favors solutions where points are evenly spaced.

Notes
  • The goal applies to a collection of ordered nodes.
  • The start and end points are assumed to be fixed.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, points]) -> Float[Array, '']

The length-normalized colinearity energy of the ordered nodes.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the node coordinates from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, points]) –

    The indices of the ordered nodes.

Returns:

  • prediction ( Float[Array, ''] ) –

    The colinearity energy, zero when the nodes are evenly spaced on a line.

NodesCurvatureGoal ¤

NodesCurvatureGoal(key: Sequence[int], weight: float = 1.0)

Minimize curvature energy (i.e., the turning angle) for an ordered sequence of points.

Notes
  • The goal applies to a collection of ordered nodes.
  • The start and end points are assumed to be fixed.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, points]) -> Float[Array, '']

The curvature energy of the ordered nodes.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the node coordinates from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, points]) –

    The indices of the ordered nodes.

Returns:

  • prediction ( Float[Array, ''] ) –

    The curvature energy, the total turning angle along the sequence.

Edge goals¤

EdgeLengthGoal ¤

Drive an edge toward a target length.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The current length of the edge.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the length from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the edge.

Returns:

  • prediction ( Float[Array, ''] ) –

    The edge's length.

EdgesLengthEqualGoal ¤

EdgesLengthEqualGoal(key: Sequence[tuple[int, int]], weight: float = 1.0)

Equalize the lengths of a selection of edges.

Notes

Applies to a collection of edges at once. The goal drives the normalized variance of the lengths to zero.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, elements]) -> Float[Array, '']

The variance of the edge lengths, normalized by their mean.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the lengths from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, elements]) –

    The indices of the edges.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean-normalized variance of the lengths, zero when all equal.

EdgeForceGoal ¤

Drive an edge toward a target internal force.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The current internal force in the edge.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the force from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the edge.

Returns:

  • prediction ( Float[Array, ''] ) –

    The edge's internal force, signed positive in tension.

EdgesForceEqualGoal ¤

EdgesForceEqualGoal(key: Sequence[tuple[int, int]], weight: float = 1.0)

Equalize the internal forces of a selection of edges.

Notes

Applies to a collection of edges at once. The goal drives the normalized variance of the forces to zero.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, elements]) -> Float[Array, '']

The variance of the edge forces, normalized by their mean magnitude.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the forces from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, elements]) –

    The indices of the edges.

Returns:

  • prediction ( Float[Array, ''] ) –

    The magnitude-normalized variance of the forces, zero when all equal.

EdgeDirectionGoal ¤

Align an edge's direction with a target vector.

Notes

Both the prediction and target are unit-normalized, so only direction is compared and edge length is ignored.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, 3]

The unit direction of the edge.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the edge vector from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the edge.

Returns:

  • prediction ( Float[Array, 3] ) –

    The normalized edge vector.

goal ¤

goal(target: Float[Array, 3], prediction: Float[Array, 3]) -> Float[Array, 3]

The unit direction of the target vector.

Parameters:

  • target (Float[Array, 3]) –

    The target direction vector.

  • prediction (Float[Array, 3]) –

    The current normalized edge vector, unused.

Returns:

  • goal ( Float[Array, 3] ) –

    The normalized target vector.

EdgeAngleGoal ¤

EdgeAngleGoal(key: tuple[int, int], target: TargetLike, weight: float = 1.0, *, vector: Float[Array, ...] | Sequence[float])

Drive the angle between an edge and a reference vector toward a target.

Parameters:

  • key (tuple[int, int]) –

    The key of the edge the goal acts on.

  • target (TargetLike) –

    The target angle, in radians.

  • weight (float, default: 1.0 ) –

    The relative importance of the goal in the loss.

  • vector (Float[Array, ...] | Sequence[float]) –

    The reference vector the edge's angle is measured against. Keyword-only and required, since there is no meaningful default reference direction.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The angle between the edge and its reference vector.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the edge vector from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the edge.

Returns:

  • prediction ( Float[Array, ''] ) –

    The angle between the edge and its reference vector, in radians.

Notes

The reference vector is read off self.vector, this element's own vector.

EdgeLoadPathGoal ¤

Drive an edge's load path toward a target value.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The load path of the edge.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the force and length from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The index of the edge.

Returns:

  • prediction ( Float[Array, ''] ) –

    The edge load path, the product of absolute force and length.

Vertex goals¤

Vertex goals are thin counterparts of the node goals above: the goal logic is inherited unchanged, while keys resolve against the vertices of a mesh instead of the nodes of a network. Applying one to a network raises a TypeError pointing to the Node* counterpart, and vice versa. Only the goals with no node equivalent — such as VertexNormalAngleGoal and VertexTangentAngleGoal, which need face topology — implement their own logic.

VertexPointGoal ¤

Drive a vertex toward target xyz coordinates.

VertexLineGoal ¤

Pull a vertex onto a target line, defined by two points.

VertexPlaneGoal ¤

Pull a vertex onto a target plane, defined by a point and a normal.

VertexSegmentGoal ¤

Pull a vertex onto a target segment, defined by its two endpoints.

VertexXCoordinateGoal ¤

Drive a vertex toward a target X coordinate.

VertexYCoordinateGoal ¤

Drive a vertex toward a target Y coordinate.

VertexZCoordinateGoal ¤

Drive a vertex toward a target Z coordinate.

VertexResidualForceGoal ¤

Drive the residual force magnitude at a vertex toward a target value.

VertexResidualVectorGoal ¤

Drive the residual force at a vertex toward a target vector.

VertexResidualDirectionGoal ¤

Drive the residual force at a vertex toward a target direction.

Notes

Both the prediction and the target are unit-normalized, so only direction is compared while magnitude is ignored.

VertexResidualPlaneGoal ¤

Drive the residual vector at a vertex to lie in a target plane.

Notes

The plane passes through the origin and is described by its normal vector alone. Only the residual's direction is compared, so the error cannot be reduced by shrinking the reaction magnitude instead of rotating the reaction into the plane.

VerticesColinearGoal ¤

VerticesColinearGoal(key: Sequence[int], weight: float = 1.0)

Minimize length-normalized colinearity energy for an ordered sequence of vertices. This goal favors solutions where vertices are evenly spaced.

Notes

This goal applies to a collection of ordered vertices and is therefore not collectible.

VerticesCurvatureGoal ¤

VerticesCurvatureGoal(key: Sequence[int], weight: float = 1.0)

Minimize curvature energy (i.e., the turning angle) for an ordered sequence of vertices.

Notes

This goal applies to a collection of ordered vertices and is therefore not collectible.

VertexNormalAngleGoal ¤

VertexNormalAngleGoal(key: int, target: TargetLike, weight: float = 1.0, *, vector: Float[Array, ...] | Sequence[float])

Drive the angle between a vertex normal and a reference vector toward a target.

Parameters:

  • key (int) –

    The key of the vertex the goal acts on.

  • target (TargetLike) –

    The target angle, in radians.

  • weight (float, default: 1.0 ) –

    The relative importance of the goal in the loss.

  • vector (Float[Array, ...] | Sequence[float]) –

    The reference vector each vertex normal's angle is measured against. Keyword-only and required, since there is no meaningful default reference direction.

Notes

The vertex normal is the unitized average of the normals of the faces surrounding the vertex, so this goal only applies to meshes.

The angle is the arccosine of the signed cosine, so it spans [0, pi] and is covariant with the orientation of the vertex normal: a normal within 90 degrees of the reference vector reads as acute, one folded past it as obtuse. Like the edge orientation in EdgeAngleGoal, the winding of the mesh faces is treated as data because it sets the normal's orientation. The mesh must therefore have a unified face winding for the averaged vertex normal, and hence the signed angle, to be meaningful. No runtime check is performed; compas.datastructures.Mesh.unify_cycles unifies the winding of a mesh upfront if needed.

face_normals staticmethod ¤

face_normals(faces_indexed: Int[Array, 'faces vertices'], xyz: Float[Array, 'vertices 3']) -> Float[Array, 'faces 3']

Compute the unnormalized normal of every face in the mesh.

Parameters:

  • faces_indexed (Int[Array, 'faces vertices']) –

    The vertex indices of each face, with -1 padding for absent vertices.

  • xyz (Float[Array, 'vertices 3']) –

    The coordinates of the mesh vertices.

Returns:

  • normals ( Float[Array, 'faces 3'] ) –

    The unnormalized normal of each face, its magnitude proportional to face area.

vertex_normal ¤

vertex_normal(eq_state: EquilibriumState, faces_indexed: Int[Array, 'faces vertices'], index: Int[Array, '']) -> Float[Array, 3]

The unitized normal at a vertex, averaged over its incident faces.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the vertex coordinates from.

  • faces_indexed (Int[Array, 'faces vertices']) –

    The mesh face topology whose incident faces set the vertex normal.

  • index (Int[Array, '']) –

    The index of the vertex.

Returns:

  • normal ( Float[Array, 3] ) –

    The unit normal at the vertex.

Notes

The incident faces are selected by masking the face topology directly: a face is incident when any of its vertex indices equals the queried index. Padding entries (-1) never match a valid index. The area-weighted face normals then sum into the vertex normal before normalizing.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The angle between the vertex normal and the reference vector.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face topology.

  • index (Int[Array, '']) –

    The index of the vertex.

Returns:

  • prediction ( Float[Array, ''] ) –

    The signed angle between the vertex normal and its reference vector, in radians.

Notes

The reference vector is read off self.vector, this element's own vector.

VertexTangentAngleGoal ¤

VertexTangentAngleGoal(key: int, target: TargetLike, weight: float = 1.0, *, vector: Float[Array, ...] | Sequence[float])

Drive the angle between a vertex tangent and a reference vector toward a target.

Parameters:

  • key (int) –

    The key of the vertex the goal acts on.

  • target (TargetLike) –

    The target angle, in radians.

  • weight (float, default: 1.0 ) –

    The relative importance of the goal in the loss.

  • vector (Float[Array, ...] | Sequence[float]) –

    The reference vector each vertex tangent's angle is measured against. Keyword-only and required, since there is no meaningful default reference direction.

Notes

The tangent angle is 90 degrees minus the vertex normal angle, so it is signed and spans [-pi / 2, pi / 2]: positive when the vertex normal points within 90 degrees of the reference vector (the surface rises toward it) and negative when the normal is folded away. The sign follows the winding of the mesh faces, which must be unified; see the notes of VertexNormalAngleGoal.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The angle between the vertex tangent and the reference vector.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face topology.

  • index (Int[Array, '']) –

    The index of the vertex.

Returns:

  • prediction ( Float[Array, ''] ) –

    The signed tangent angle, 90 degrees minus the vertex normal angle, in radians.

Face goals¤

FaceRectangularGoal ¤

FaceRectangularGoal(key: int, weight: float = 1.0, target: TargetLike = 0.0)

Make the internal angles of a quadrilateral mesh face reach 90 degrees.

Notes

This goal is only applicable to quadrilateral mesh faces.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

A measure of how far a face is from rectangular.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the face coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face topology.

  • index (Int[Array, '']) –

    The index of the face.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean absolute cosine of the face's corner angles, zero when every corner is a right angle.

Mesh goals¤

MeshAreaGoal ¤

Drive the total surface area of a mesh toward a target.

Notes

The prediction is the negated total area, so a target of zero paired with a minimizing loss maximizes the mesh area.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The negated total surface area of the mesh.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face indices.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The negated sum of the face areas.

MeshFacesAreaEqualizeGoal ¤

Equalize the areas of the faces of a mesh.

Notes

The goal drives the mean-normalized variance of the face areas to zero.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The variance of the face areas, normalized by their mean.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face indices.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean-normalized variance of the face areas, zero when all equal.

MeshXYZLaplacianGoal ¤

MeshXYZLaplacianGoal(target: TargetLike = 0.0, weight: float = 1.0)

Minimize the Laplacian energy of a mesh's coordinates.

Notes

A thin wrapper of NetworkXYZLaplacianGoal that fixes the key to the mesh sentinel.

MeshXYZFaceLaplacianGoal ¤

Minimize the Laplacian energy of the XYZ faces coordinates of a mesh.

Notes

This goal can be handy to "smoothen" the looks of a mesh.

This energy is computed as the distance of the XYZ coordinates of every vertex to the centroid of the centroids of the faces the vertex is part of.

An energy-minimizing mesh will have every vertex as close as possible to its neighboring faces centroid.

laplacian_vertices ¤

laplacian_vertices(eq_state: EquilibriumState, structure: EquilibriumMeshStructure) -> Float[Array, vertices]

The per-vertex Laplacian energy against neighboring face centroids.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face-vertex connectivity.

Returns:

  • laplacians ( Float[Array, vertices] ) –

    The squared distance from each vertex to the mean of its incident face centroids.

Notes

Formulated as products with the face-vertex connectivity so that the matrix can be stored dense or in sparse format. Each vertex's neighbor centroid is the average of its incident face centroids, weighted by the row-normalized connectivity entries.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The mean per-vertex Laplacian energy of the mesh.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face-vertex connectivity.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean over vertices of the face-centroid Laplacian energy.

MeshLoadPathGoal ¤

MeshLoadPathGoal(target: TargetLike = 0.0, weight: float = 1.0)

Drive the total load path of a mesh toward a target magnitude.

Notes

A thin wrapper of NetworkLoadPathGoal that fixes the key to the mesh sentinel.

MeshSmoothGoal ¤

Smudge a mesh based on the smoothness energy of its vertices.

Notes

Smoothness, or fairness, is an energy that measures the squared distance between the position of a vertex and the centroid of its neighbors' positions.

Based on Eq. 2 in Tang et al. (2013). DOI: 10.1145/2601097.2601213. The fairness is computed only for the free vertices, and each vertex term is reweighted by the square of its valence.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The mean fairness energy over the mesh's free vertices.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the adjacency and free-vertex indices.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean valence-weighted squared distance from each free vertex to its neighbors' centroid.

MeshPlanarityGoal ¤

Planarize the faces of a mesh.

Notes

This goal computes the average planarity of the faces of a mesh. The planarity of a face is the mean absolute dot product between the face's unitized normal vector and its unitized edge vectors, so faces of different degrees score comparably and ngons do not dominate the average. Triangles are planar by construction and contribute zero to the average; padded faces and faces with more than 4 vertices are handled correctly.

The prediction is an energy, not a distance to a target. To minimize it as-is, pair this goal with a PredictionError; a SquaredError would square the energy, flattening its gradient as the faces approach planarity.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumMeshStructure, index: Int[Array, '']) -> Float[Array, '']

The average planarity of the mesh faces.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read vertex coordinates from.

  • structure (EquilibriumMeshStructure) –

    The mesh structure providing the face indices.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean face planarity, zero when every face is planar.

Network goals¤

NetworkLoadPathGoal ¤

Drive the total load path of a network toward a target magnitude.

Notes

The load path of an edge is the absolute value of its force times its length; the network load path is the sum over all edges.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The total load path of the network.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read edge forces and lengths from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The sum of the absolute force-length product over all edges.

NetworkXYZLaplacianGoal ¤

Minimize the Laplacian energy of the XYZ coordinates of a network.

Notes

This goal can be handy to "smoothen" the looks of a network.

The Laplacian energy of some feature vector x is defined as E = x^T @ L @ x, where the unnormalized Laplacian L is related to the connectivity matrix of a network C such that L = C^T @ C.

Given the above relationship and that we want to calculate the energy of the XYZ coordinates of a network in equilibrium (the feature vector x of interest are the XYZ coordinates), then the energy expression becomes: x^T @ (C^T @ C) @ X.

We know that U = C @ X is the matrix with coordinate difference vectors that we obtain from the equilibrium model.

Therefore, we can re-rexpress the energy E in terms of U, and use that definition to calculate the energy for this goal function: E = U^T @ U. Interestingly, this expression is equivalent to minimizing the squared sum of the edge lengths l of the network, E = l^2.

In practice, we are interested in a single scalar value of this energy to minimize with optimization. As a result, we ravel matrix U into a single vector, and calculate the dot product of U in the raveled state.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The Laplacian energy of the network coordinates.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the edge vectors from.

  • structure (EquilibriumStructure) –

    The structure the goal is evaluated against; unused.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The Laplacian energy, equal to the sum of squared edge lengths.

NetworkSmoothGoal ¤

Smudge a network based on the fairness of its nodes.

Notes

Fairness is an energy that measures the smoothness of the position of a node w.r.t. to that of its neighbors.

The fairness energy is computed as the squared length of the vector between every node position and their neighbors' centroid.

prediction ¤

prediction(eq_state: EquilibriumState, structure: EquilibriumStructure, index: Int[Array, '']) -> Float[Array, '']

The mean fairness energy over the network's nodes.

Parameters:

  • eq_state (EquilibriumState) –

    The equilibrium state to read the node coordinates from.

  • structure (EquilibriumStructure) –

    The structure providing the adjacency matrix.

  • index (Int[Array, '']) –

    The sentinel index, unused.

Returns:

  • prediction ( Float[Array, ''] ) –

    The mean over nodes of the squared distance from each node to its neighbors' centroid.