Top-level API#

Core#

For role-explicit assembly and mixed/contact setup, prefer the *Spaces family listed here. Lower-level constructors remain available in the deeper API reference, but they are no longer the preferred public entry points.

fluxfem.FESpace#

alias of FESpaceClosure

class fluxfem.FormContext(test: FormFieldLike, trial: FormFieldLike, x_q: jnp.ndarray, w: jnp.ndarray, elem_id: jnp.ndarray | int = 0, spaces: dict[str, 'FieldPair'] | None = None, default_space: str | None = None)

Bundle test/trial fields and quadrature data for element assembly.

class fluxfem.LinearForm(fn, *, kind: str)

Linear form wrapper with volume/surface backends.

class fluxfem.BilinearForm(fn, *, kind: str)

Bilinear form wrapper with volume/surface backends.

class fluxfem.ResidualForm(fn)

Residual form wrapper.

class fluxfem.NamedSpace(name: str, space: FESpaceClosure)

Public wrapper that binds a symbolic space name to an FE space.

class fluxfem.BilinearSpaces(test: NamedSpace, trial: NamedSpace)

Public wrapper for distinct test/trial spaces in bilinear assembly.

class fluxfem.LinearSpaces(test: NamedSpace)

Public wrapper for the test space used in linear-form 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.

class fluxfem.MixedSpaces(fields: Mapping[str, NamedSpace | LinearSpaces | BilinearSpaces | ResidualSpaces | JacobianSpaces])

Public spec that maps mixed field names to named FE space-role specs.

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.

fluxfem.make_hex_space(mesh: HexMesh, dim: int = 1, intorder: int = 2) → FESpaceClosure#

Create a trilinear hex space (8-node elements).

fluxfem.make_tet_space(mesh: TetMesh, dim: int = 1, intorder: int = 2) → FESpaceClosure#

Create a linear or quadratic tet space based on mesh nodes.

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

Physics#

fluxfem.lame_parameters(E: float, nu: float) → tuple[float, float]#

Return Lamé parameters (lambda, mu) from Young’s modulus and Poisson ratio.

fluxfem.isotropic_3d_D(E: float, nu: float) → jax.numpy.ndarray#

Return 3D isotropic linear elasticity constitutive matrix in Voigt form.

fluxfem.linear_elasticity_form(ctx: jax.tree_util.register_pytree_node_class, D: jax.numpy.ndarray) → jax.numpy.ndarray#

Linear-elasticity bilinear form in Voigt notation.

Returns the per-quadrature integrand for Bv^T D Bu, where B is the symmetric-gradient operator for the test/trial fields.

fluxfem.diffusion_form(ctx: jax.tree_util.register_pytree_node_class, kappa: float) → jax.numpy.ndarray#

Scalar diffusion bilinear form: kappa * grad_v · grad_u.

Returns the per-quadrature integrand for a standard Laplacian term.

fluxfem.neo_hookean_residual_form(ctx: jax.tree_util.register_pytree_node_class, u_elem: jax.numpy.ndarray, params: Mapping[str, float] | tuple[float, float]) → jax.numpy.ndarray#

Compressible Neo-Hookean residual (Total Lagrangian, PK2). params: dict-like with keys “mu”, “lam” or tuple (mu, lam) returns: (n_q, n_ldofs)

Solvers#

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.

class fluxfem.LinearSolver(method: str = 'spsolve', tol: float = 1e-08, maxiter: int = 200)

Lightweight wrapper for solving linear systems with optional Dirichlet BCs.

Supports dense arrays or FluxSparseMatrix and can either condense or enforce Dirichlet conditions before solving with the chosen backend.

class fluxfem.NonlinearSolver(space: FESpaceClosure, res_form: Any, params: Any, *, tol: float = 1e-08, maxiter: int = 20, linear_method: str = 'spsolve', line_search: bool = False, max_ls: int = 10, ls_c: float = 0.0001, linear_tol: float | None = None, dirichlet: DirichletBC | tuple[ndarray, ndarray] | None = None, external_vector: ndarray | None = None, linear_maxiter: int | None = None, jacobian_pattern: Any | None = None)

Backward-compatible Newton-based nonlinear solver.

This is a thin wrapper around newton_solve kept for legacy code paths. Prefer NonlinearAnalysis + NewtonSolveRunner for new workflows.

class fluxfem.NonlinearAnalysis(space: Any, residual_form: Callable[[jax.tree_util.register_pytree_node_class, jax.numpy.ndarray, Any], jax.numpy.ndarray], params: Any, base_external_vector: ndarray | None = None, dirichlet: tuple[ndarray, ndarray] | None = None, extra_terms: list[Callable[[ndarray], tuple[ndarray, ndarray] | tuple[ndarray, ndarray, dict[str, Any]] | None]] | None = None, assembly_policy: Any | None = None, jacobian_pattern: Any | None = None, dtype: Any = jax.numpy.float64)

Bundle problem data needed for a Newton solve with load scaling.

Variables:

  • space (Any) – FE space containing topology/dofs.

  • residual_form (Any) – Internal residual form (e.g., neo_hookean_residual_form).

  • params (Any) – Parameters forwarded to the residual form.

  • base_external_vector (Any | None) – Unscaled external load vector (scaled by load factor in external_for_load).

  • dirichlet (tuple | None) – (dofs, values) for Dirichlet boundary conditions.

  • extra_terms (list[callable] | None) – Optional extra term assemblers returning (K, f[, metrics]).

  • assembly_policy (Any | None) – Optional volume assembly execution policy forwarded to residual/Jacobian assembly.

  • jacobian_pattern (Any | None) – Optional sparsity pattern to reuse between load steps.

  • dtype (Any) – dtype for the solution vector (defaults to float64).

class fluxfem.NewtonSolveRunner(analysis: NonlinearAnalysis, config: NewtonLoopConfig)

Run one or more Newton solves across load factors.

This orchestrates load stepping, assembles external load per step, and returns the full (Dirichlet-expanded) solution and per-step history.