Role-Explicit Specs#

These helper specs make test/trial/unknown or master/slave roles explicit in the public API while reusing the same underlying assembly and space objects.

For volume assembly, prefer the *Spaces family over transitional helpers. Deprecated compatibility paths are summarized in migration_role_spaces.rst; this page focuses on the preferred public API.

Volume#

class fluxfem.NamedSpace(name: str, space: FESpaceClosure)#: Public wrapper that binds a symbolic space name to an FE space.

class fluxfem.LinearSpaces(test: NamedSpace)#: Public wrapper for the test space used in linear-form assembly.

class fluxfem.BilinearSpaces(test: NamedSpace, trial: NamedSpace)#: Public wrapper for distinct test/trial spaces in bilinear assembly.

class fluxfem.ResidualSpaces(test: NamedSpace, unknown: NamedSpace)#: Public wrapper for distinct test/unknown spaces in residual assembly.

class fluxfem.JacobianSpaces(test: NamedSpace, trial: NamedSpace)#: Public wrapper for distinct test/trial spaces in Jacobian assembly.

fluxfem.assemble_linear_form(space: SpaceLike, form: FormKernel[P], params: P, *, domain=None, backend: str | None = None, kernel: ElementLinearKernel | None = None, sparse: bool = False, vector_accumulation: Literal['segment', 'scatter'] = 'scatter', n_chunks: int | None = None, dep: jnp.ndarray | None = None, elem_data: FormContext | None = None, include_x_q: bool | None = None, lightweight_context: bool | None = None, chunk_build_context: bool | None = None, pad_trace: bool | None = None, policy: AssemblyPolicy | None = None) → LinearReturn#: Expects form(ctx, params) -> (n_q, n_ldofs) and integrates Σ_q form * wJ for RHS. If kernel is provided: kernel(ctx) -> (n_ldofs,). backend=None auto-selects JAX when any input is JAX-like; otherwise it uses the default backend for this API.

fluxfem.assemble_bilinear_form(space: SpaceLike, form: FormKernel[P], params: P, *, backend: str | None = None, pattern: SparsityPattern | None = None, n_chunks: int | None = None, dep: jnp.ndarray | None = None, elem_data: FormContext | None = None, include_x_q: bool | None = None, lightweight_context: bool | None = None, chunk_build_context: bool | None = None, kernel: ElementBilinearKernel | None = None, jit: bool = True, pad_trace: bool | None = None, policy: AssemblyPolicy | None = None) → FluxSparseMatrix | FluxSparseOperator#

Assemble a sparse bilinear form into a FluxSparseMatrix.

Expects form(ctx, params) -> (n_q, n_ldofs, n_ldofs). If kernel is provided: kernel(ctx) -> (n_ldofs, n_ldofs). backend=None auto-selects JAX when any input is JAX-like; otherwise it uses the default backend for this API.

fluxfem.assemble_residual(space: SpaceLike, form: Callable[[jax.tree_util.register_pytree_node_class, jax.numpy.ndarray, P], jax.numpy.ndarray], u: jax.numpy.ndarray, params: P, *, backend: str | None = None, kernel: ElementResidualKernel | None = None, sparse: bool = False, vector_accumulation: Literal['segment', 'scatter'] = 'scatter', n_chunks: int | None = None, pad_trace: bool | None = None, policy: AssemblyPolicy | None = None) → jax.numpy.ndarray | tuple[jax.numpy.ndarray, jax.numpy.ndarray, int]#: Assemble a residual vector. backend=None auto-selects from the inputs.

fluxfem.assemble_jacobian(space: SpaceLike, res_form: Callable[[jax.tree_util.register_pytree_node_class, jax.numpy.ndarray, P], jax.numpy.ndarray], u: jax.numpy.ndarray, params: P, *, kernel: ElementJacobianKernel | None = None, pattern: Any | None = None, n_chunks: int | None = None, pad_trace: bool | None = None, policy: AssemblyPolicy | None = None) → Any#

Mixed#

class fluxfem.MixedSpaces(fields: Mapping[str, NamedSpace | LinearSpaces | BilinearSpaces | ResidualSpaces | JacobianSpaces])#: Public spec that maps mixed field names to named FE space-role specs.

Contact#

class fluxfem.ContactSpaces(master: ContactSide, slave: ContactSide, field_master: str = 'a', field_slave: str = 'b')#: Public spec that binds contact roles to contact sides.

class fluxfem.ContactGroupSpaces(master: ContactSide, slaves: Sequence[ContactSide], field_master: str = 'master', field_slave: str = 'slave')#: Public spec that binds one-master/many-slave contact roles.

class fluxfem.OneSidedContactSpaces(side: ContactSide, surface_master: SurfaceMesh | None = None, elem_conn_master: ndarray | None = None, facet_to_elem_master: ndarray | None = None)#: Public spec that binds one-sided contact roles to a contact side.

Sparse operators#

class fluxfem.FluxSparseOperator(rows: ndarray, cols: ndarray, data: ndarray, shape: tuple[int, int], meta: dict | None = None)#

Sparse operator wrapper (COO) for rectangular or square operators.

This is intentionally narrower than FluxSparseMatrix: - stores raw COO rows/cols/data - tracks a general shape=(n_rows, n_cols) - supports dense conversion and forward/adjoint matvec

It is intended as the first rectangular sparse abstraction for Petrov-Galerkin-style bilinear assembly without destabilizing existing square-matrix solver paths.