Skip to content

Lifter¤

tatva.lifter.Lifter ¤

Lifter(size: int, /, *constraints: Constraint)

Create a lifter that maps between reduced and full vectors.

Parameters:

  • size ¤

    (int) –

    Total number of dofs in the full vector.

  • *constraints ¤

    (Constraint, default: () ) –

    Extra constraints (e.g., periodic maps).

Examples::

lifter = Lifter(
    6,
    Fixed(jnp.array([0, 5]), 0.0),
    Periodic(dofs=jnp.array([2]), master_dofs=jnp.array([1])),
)
u_reduced = jnp.array([10.0, 20.0, 30.0])
u_full = lifter.lift_from_zeros(u_reduced)
# u_full -> [0., 10., 10., 20., 30., 0.]
u_reduced_back = lifter.reduce(u_full)

Methods:

  • tree_flatten –
  • tree_unflatten –
  • add –

    Return a new lifter with condition appended to constraints.

  • lift –

    Lift reduced displacement vector to full size.

  • lift_from_zeros –

    Lift reduced vector to a full vector starting from zeros.

  • reduce –

    Extract the reduced vector by selecting free dofs from u_full.

  • reduce_adjoint –

    Extract the reduced dual (residual/gradient) vector from r_full.

  • with_values –

    Update the internal runtime values mapping with the given updates.

  • adapt_sparsity –

    Augment and reduce the sparsity pattern to account for all constraints. From

  • augment_sparsity –

    Augment the sparsity pattern to account for all constraints.

  • reduce_sparsity –

    Reduce the sparsity pattern to the free DOF layout.

  • adapt_layout –

    MPI only. Augment the local layout to account for all constraints.

Attributes:

  • free_dofs (Array) –

    Array of free dofs as integer indices (not constrained).

  • constrained_dofs (Array) –

    Array of constrained dofs as integer indices.

  • size (int) –

    Total number of dofs in the full vector.

  • size_reduced (int) –

    Number of dofs in the reduced vector (free dofs only).

  • constraints (tuple[Constraint, ...]) –

    Tuple of constraints, which are applied in order during lifting. Constraints must

  • at (RuntimeValueIndexer) –

    Return a ValueIndexer for setting runtime values by key.

free_dofs instance-attribute ¤

free_dofs: Array

Array of free dofs as integer indices (not constrained).

constrained_dofs instance-attribute ¤

constrained_dofs: Array

Array of constrained dofs as integer indices.

size instance-attribute ¤

size: int = size

Total number of dofs in the full vector.

size_reduced instance-attribute ¤

size_reduced: int

Number of dofs in the reduced vector (free dofs only).

constraints class-attribute instance-attribute ¤

constraints: tuple[Constraint, ...] = tuple(
    (_bind(self)) for cond in constraints
)

Tuple of constraints, which are applied in order during lifting. Constraints must specify which dofs they apply to, and can optionally specify runtime values that are provided to the lifter at runtime. These constraints are bound to the lifter instance, which allows them to access the lifter's runtime values when applying the lift.

at property ¤

at: RuntimeValueIndexer

Return a ValueIndexer for setting runtime values by key.

tree_flatten ¤

tree_flatten() -> tuple[tuple[Any, ...], tuple[Any, ...]]

tree_unflatten classmethod ¤

tree_unflatten(
    aux_data: tuple[Any, ...], children: tuple[Any, ...]
) -> Self

add ¤

add(condition: Constraint) -> Self

Return a new lifter with condition appended to constraints.

lift ¤

lift(u_reduced: Array, u_full: Array) -> Array

Lift reduced displacement vector to full size.

Parameters:

  • u_reduced ¤
    (Array) –

    Vector on free dofs (length size_reduced).

  • u_full ¤
    (Array) –

    Base full vector to modify; typically previous solution.

Returns:

  • Array –

    Full vector with free dofs set to u_reduced and constraints

  • Array –

    applied (Dirichlet, periodic, etc.).

lift_from_zeros ¤

lift_from_zeros(u_reduced: Array) -> Array

Lift reduced vector to a full vector starting from zeros.

reduce ¤

reduce(u_full: Array) -> Array

Extract the reduced vector by selecting free dofs from u_full.

reduce_adjoint ¤

reduce_adjoint(r_full: Array) -> Array

Extract the reduced dual (residual/gradient) vector from r_full.

This applies the adjoint of each constraint in reverse order to ensure that contributions from constrained dofs are correctly mapped back to the reduced space (e.g., summing residuals for periodic dofs).

Parameters:

  • r_full ¤
    (Array) –

    Full dual vector (e.g., residual or gradient).

Returns:

  • Array –

    Reduced dual vector on free dofs.

with_values ¤

with_values(updates: RuntimeValueMap) -> Self

Update the internal runtime values mapping with the given updates.

adapt_sparsity ¤

adapt_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

Augment and reduce the sparsity pattern to account for all constraints. From the built-in constraints, only Periodic and PeriodicMPI have non-trivial implementations of this method, which add entries to the sparsity pattern to account for the coupling between master and slave dofs. Returns the reduced sparsity pattern for the free DOFs.

Parameters:

  • sparsity ¤
    (csr_matrix) –

    Sparsity pattern in SciPy CSR format.

Returns:

  • csr_matrix –

    Augmented and reduced sparsity pattern in SciPy CSR format.

augment_sparsity ¤

augment_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

Augment the sparsity pattern to account for all constraints.

Parameters:

  • sparsity ¤
    (csr_matrix) –

    Sparsity pattern in SciPy CSR format.

Returns:

  • csr_matrix –

    Augmented sparsity pattern in SciPy CSR format.

reduce_sparsity ¤

reduce_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

Reduce the sparsity pattern to the free DOF layout.

Parameters:

  • sparsity ¤
    (csr_matrix) –

    Full sparsity pattern in SciPy CSR format.

Returns:

  • csr_matrix –

    Reduced sparsity pattern in SciPy CSR format.

adapt_layout ¤

adapt_layout(
    layout: _LocalLayout, comm: Comm
) -> tuple[_LocalLayout, Lifter]

MPI only. Augment the local layout to account for all constraints.

This may add extra ghost dofs to the local array to account for periodic constraints, for example.

Parameters:

  • layout ¤
    (_LocalLayout) –

    Local layout to augment.

Returns:

  • tuple[_LocalLayout, Lifter] –

    A tuple of (augmented_reduced_layout, augmented_lifter).

tatva.lifter.lifted ¤

lifted(
    fn: Callable[P, Array] | None = None,
    *,
    argnums: tuple[int, ...] | int = 0,
    output: Literal["primal", "dual"] | None = None,
) -> Callable

Lift a function that operates on reduced vectors to one that operates on full vectors.

This is a decorator that can be used to lift a function that takes reduced vectors as input and/or output to one that takes full vectors. The lifter instance is passed as the first argument to the lifted function, and the specified arguments are lifted from reduced to full vectors before being passed to the original function.

Parameters:

  • fn ¤

    (Callable[P, Array] | None, default: None ) –

    Function to lift; must take reduced vectors as input and/or output.

  • argnums ¤

    (tuple[int, ...] | int, default: 0 ) –

    Indices of arguments to lift from reduced to full vectors; can be an int or a tuple of ints. Default is 0 (lift the first argument).

  • output ¤

    (Literal['primal', 'dual'] | None, default: None ) –

    Whether to reduce the output of the original function. If "primal", the output is reduced using Lifter.reduce. If "dual", the output is reduced using Lifter.reduce_adjoint (useful for residuals or gradients). Default is None.

Returns:

  • Callable –

    A new function that takes a lifter instance as the first argument, followed by the same

  • Callable –

    arguments as fn, but with the specified arguments lifted from reduced to full vectors,

  • Callable –

    and optionally with the output reduced from a full vector to a reduced vector.

tatva.lifter.Constraint ¤

Constraint(dofs: Array)

Base class for conditions applied during lifting.

Subclasses define how constrained degrees of freedom (dofs) are enforced when mapping a reduced vector back to the full vector.

Methods:

  • augment_sparsity –

    Augment the sparsity pattern to account for this constraint.

  • apply_lift –

    Apply the constraint to a full vector and return the modified copy.

  • apply_transpose –

    Apply the transpose of the constraint to a full residual vector.

Attributes:

  • dofs (Array) –

    The dofs to constrain; every constraint must specify which dofs it applies to.

dofs instance-attribute ¤

dofs: Array = dofs

The dofs to constrain; every constraint must specify which dofs it applies to.

augment_sparsity ¤

augment_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

Augment the sparsity pattern to account for this constraint.

Parameters:

  • sparsity ¤
    (csr_matrix) –

    Sparsity pattern in SciPy CSR format.

Returns:

  • csr_matrix –

    Augmented sparsity pattern in SciPy CSR format.

apply_lift ¤

apply_lift(u_full: Array) -> Array

Apply the constraint to a full vector and return the modified copy.

apply_transpose ¤

apply_transpose(r_full: Array) -> Array

Apply the transpose of the constraint to a full residual vector.

tatva.lifter.Fixed ¤

Fixed(
    dofs: Array,
    values: ArrayLike
    | RuntimeValue[ArrayLike]
    | None = None,
)

Parameters:

  • dofs ¤

    (Array) –

    The dofs to constrain; these will be set to fixed values during lifting.

  • values ¤

    (ArrayLike | RuntimeValue[ArrayLike] | None, default: None ) –

    Fixed values to set on the constrained dofs during lifting; Can be

Methods:

Attributes:

  • dofs (Array) –

    The dofs to constrain; these will be set to fixed values during lifting.

  • values (ArrayLike | RuntimeValue[ArrayLike]) –

    Values to set on the constrained dofs during lifting; Defaults to 0.0 if not

dofs instance-attribute ¤

dofs: Array = dofs

The dofs to constrain; these will be set to fixed values during lifting.

values instance-attribute ¤

values: ArrayLike | RuntimeValue[ArrayLike] = (
    values if values is not None else 0.0
)

Values to set on the constrained dofs during lifting; Defaults to 0.0 if not provided at init or runtime.

augment_sparsity ¤

augment_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

Augment the sparsity pattern to account for this constraint.

Parameters:

  • sparsity ¤
    (csr_matrix) –

    Sparsity pattern in SciPy CSR format.

Returns:

  • csr_matrix –

    Augmented sparsity pattern in SciPy CSR format.

apply_lift ¤

apply_lift(u_full: Array) -> Array

Set constrained dofs to values.

apply_transpose ¤

apply_transpose(r_full: Array) -> Array

Zero out residuals on fixed dofs.

tatva.lifter.Periodic ¤

Periodic(dofs: Array, master_dofs: Array)

Methods:

Attributes:

  • dofs (Array) –

    The dofs to constrain; these will be set equal to the corresponding master_dofs during lifting.

  • master_dofs (Array) –

    The master dofs that the constrained dofs will be set equal to during lifting.

dofs instance-attribute ¤

dofs: Array

The dofs to constrain; these will be set equal to the corresponding master_dofs during lifting.

master_dofs instance-attribute ¤

master_dofs: Array = master_dofs

The master dofs that the constrained dofs will be set equal to during lifting.

augment_sparsity ¤

augment_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

apply_lift ¤

apply_lift(u_full: Array) -> Array

Copy values from master_dofs into the constrained dofs.

apply_transpose ¤

apply_transpose(r_full: Array) -> Array

Add residuals from constrained dofs to master_dofs.

tatva.lifter.PeriodicMPI ¤

PeriodicMPI(
    dofs: Array,
    master_dofs: Array,
    layout: _LocalLayout,
    *,
    comm: Comm | None = None,
)

Periodicity based on nodal mapping, for use in MPI parallel computations where dofs on different processes may be constrained together.

This is a global constraint that is synchronized across all processes. It requests the global dof indices of the slaves and masters. You can access these with CompoundCls._g.field_name[global_node, slice, ...].

Methods:

Attributes:

  • dofs (Array) –

    The dofs to constrain; these will be set equal to the corresponding master_dofs during lifting.

  • master_dofs (Array) –

    The master dofs that the constrained dofs will be set equal to during lifting.

dofs instance-attribute ¤

dofs: Array

The dofs to constrain; these will be set equal to the corresponding master_dofs during lifting.

master_dofs instance-attribute ¤

master_dofs: Array = master_dofs

The master dofs that the constrained dofs will be set equal to during lifting.

augment_sparsity ¤

augment_sparsity(sparsity: csr_matrix) -> sps.csr_matrix

apply_lift ¤

apply_lift(u_full: Array) -> Array

Copy values from master_dofs into the constrained dofs.

apply_transpose ¤

apply_transpose(r_full: Array) -> Array

Add residuals from constrained dofs to master_dofs.

tatva.lifter.RuntimeValue ¤

RuntimeValue(
    key: Hashable | None = None, default: T | None = None
)

Descriptor for a constraint value that must be provided at runtime.

Parameters:

  • key ¤

    (Hashable | None, default: None ) –

    A hashable key to identify this runtime value; used for setting values on the lifter and for error messages when the value is missing at runtime.

  • default ¤

    (T | None, default: None ) –

    An optional default value to use. If not provided, the lifter will raise an error if this value is not set at runtime.

Methods:

  • get_value –

    Get the value of this attribute from the given lifter instance.

Attributes:

key instance-attribute ¤

key = key or uuid4()

default instance-attribute ¤

default = default

get_value ¤

get_value(runtime_values: RuntimeValueMap) -> T

Get the value of this attribute from the given lifter instance.

tatva.lifter.LifterError ¤

Error raised when there is a problem with the lifter, e.g., missing runtime values.