constraints.null_space

constraints.null_space

Null-space projection and DOF analysis for constrained parameter systems.

Classes

Name	Description
NullSpaceMap	Null-space projection matrix that operates directly on parameter dicts.

NullSpaceMap

constraints.null_space.NullSpaceMap(matrix, params)

Null-space projection matrix that operates directly on parameter dicts.

Wraps the null-space matrix N (shape n_params × n_free) together with the parameter structure so that dict ↔︎ vector conversions are automatic.

Supports

N @ reduced_vec → dict[str, Array] (expand reduced → full space) full_dict @ N → Array (project full → reduced space) full_vec @ N → Array (same, from a flat vector)

The raw matrix is accessible via N.matrix if needed.

Methods

Name	Description
pack	Pack a full-space dict into a flat vector (consistent with params ordering).
unpack	Unpack a flat vector into a full-space dict (inverse of pack).

pack

constraints.null_space.NullSpaceMap.pack(full_dict)

Pack a full-space dict into a flat vector (consistent with params ordering).

unpack

constraints.null_space.NullSpaceMap.unpack(flat)

Unpack a flat vector into a full-space dict (inverse of pack).

Functions

Name	Description
all_parameters	Return a deduplicated list of all parameters referenced by constraints.
null_space	Compute the null-space projection for parameters under constraints.
total_dof_reduction	Return the total number of DOF removed by a list of constraints.

all_parameters

constraints.null_space.all_parameters(constraints)

Return a deduplicated list of all parameters referenced by constraints.

Parameters

Name	Type	Description	Default
constraints	list[Constraint]	List of Constraint objects.	required

Returns

Name	Type	Description
	list[Parameter]	Deduplicated list of Parameter objects, in order of first appearance.

null_space

constraints.null_space.null_space(free_params, metadata)

Compute the null-space projection for parameters under constraints.

Collects constraints from the metadata, linearizes the constraint manifold at the current free_params values, and returns a :class:NullSpaceMap.

Parameters

Name	Type	Description	Default
free_params	dict[str, Array]	Name-keyed dict mapping parameter names to plain Arrays (as returned by :func:~cadjoint.extraction.extract_parameters).	required
metadata	dict[str, Parameter]	Name-keyed dict mapping parameter names to Parameter objects (carries constraints, bounds, type info).	required

Returns

Name	Type	Description
A	NullSpaceMap	class:NullSpaceMap N of shape (n_params, n_free) such that:
	NullSpaceMap	N @ r expands reduced coords to a full-space dict, and
	NullSpaceMap	full_dict @ N projects a full-space dict to reduced coords.

total_dof_reduction

constraints.null_space.total_dof_reduction(constraints)

Return the total number of DOF removed by a list of constraints.

Parameters

Name	Type	Description	Default
constraints	list[Constraint]	List of Constraint objects.	required

Returns

Name	Type	Description
	int	Sum of dof_reduction() across all constraints.