Skip to content

Changelog¤

All releases and changes for the tatva library, pulled directly from GitHub.

0.11.3 (2026-07-16)¤

Bug Fixes¤

  • add jnp.split primitive to tracer (7a5af7d)
  • operator: add make_interpolate to get an interpolator for fixed points (688e61f)

0.11.2 (2026-07-07)¤

This release adds handlers for missing primitives for JAX linear algebra operations at the element level, such as jnp.linalg.inv, jnp.linalg.eig and also for jnp.flip and jnp.stack.

This release also fixes the edge cases with dot_general such as:

  • over-conservatism if one of the operands is just linearly dependent on the solution. Such a case was never checked for how the operand is dependent on the solution because only a nonlinear dependency will lead to a non-zero Hessian entry. The fix records an operand's self-second-order coupling only if it is nonlinear in the solution; the cross second-order coupling between operands is always kept.
  • when we dot_general contract a value that depends on the solution with a constant for example stress @ n (per segment stress times a fixed normal) along an interface, the tracer switched to fallback option as it didnot understand which axes the primitive dot_general was contracting over and fallback on total_union and hence assumed the results depends on every degree of freedom which made the sparsity pattern dense block. The fix tells dot_general which axis is being summed over, so dependencies are combined only along the axis and thus the pattern stays block-diagonal, and no real entry is lost.

This release also adds a warning for the primitives that are not considered.

Enhancements¤

  • add handlers for eigvalues, flip (35c5652)
  • add sparsity handlers for dense linear-algebra ops and stack (d1277a4)
  • add warnings for not considered primitives (e519f3f)

Bug Fixes¤

  • fix over-conservatism in dot_general if one of the operand is linear in solution (f7fe819)
  • make dot_general aware of the contracting axes (f917939)

0.11.1 (2026-06-27)¤

When an energy included a force term like jnp.dot(f_ext, u), the sparsity tracer wrongly marked every DOF as connected to every other one, making the matrix fully dense.

The reason was that the code that handles dot_general (matrix/vector products) always assumed both inputs were variables. But here, one input (f_ext) is a constant, so the term is just linear and adds nothing to the stiffness pattern.

The fix adds to the dot_general handler to skip the coupling when one side is a constant. Now jnp.dot(const, u) and jnp.dot(u, const) stay sparse, while real jnp.dot(u, u) products still get coupled correctly. Added tests to cover both cases.

Bug Fixes¤

  • adds missing case for dot_general jnp.dot (08d034f)

0.11.0 (2026-06-26)¤

This release simplifies and unifies the sparsity pattern generation API across the codebase. It introduces automatic JAX-trace-based sparsity detection directly from energy and virtual work formulations, moves sparsity generation logic out of the Compound class, and consolidates sparsity augmentation/reduction under the Lifter class.

Breaking Changes¤

  • Removed/Deprecated Sparse APIs: The following helper functions have been removed from tatva.sparse and will now raise an ImportError if called:
    • create_sparsity_pattern (replaced by pattern_from_mesh)
    • reduce_sparsity_pattern (replaced by Lifter.adapt_sparsity)
    • create_sparsity_pattern_KKT
    • create_sparsity_pattern_master_slave
    • get_bc_indices
  • Compound Sparsity Method Removed: Removed the class method Compound.get_sparsity() to decouple structure layout from sparsity generation.
  • Coloring Functions Hidden: Removed distance2_colors, largest_degree_first_distance2_colors, and smallest_last_distance2_colors from the public tatva.sparse namespace.

New Features & Refactoring¤

  • Automatic JAX Sparsity Tracing:
    • pattern_from_energy(energy_fn, n_dofs, *static_args): Automatically traces and returns the symmetric CSR sparsity pattern of the Hessian (d²E/du²) for a scalar energy function.
    • pattern_from_virtual_work(virtual_work_fn, n_dofs, trial_arg, test_arg, *static_args): Automatically traces and returns the tangent stiffness matrix sparsity pattern (d²G/dvdu) from a virtual work function.
  • Unified Sparsity Extraction Helpers:
    • pattern_from_mesh(mesh, n_dofs_per_node): Standardized mesh-based sparsity generation.
    • pattern_from_compound(compound_cls, block_wise=False): Extracted compound class sparsity generation to the sparse module.
  • Unified Reduction and Constraint Handling:
    • Added Lifter.adapt_sparsity(sparsity) to automate both the augmentation (adding master-slave coupling) and reduction (retaining only free DOFs) of a sparsity pattern in a single call.

Usage Examples (Tracer with Boundary Conditions)¤

By passing a Lifter as a static argument, you can trace the sparsity of the reduced system (accounting for boundary conditions) directly:

1. Energy-Based Tracer with BCs¤

import jax
import jax.numpy as jnp
from tatva.sparse import pattern_from_energy

@jax.jit
def total_energy(u):
    # Compute full potential energy
    return ...

@jax.jit
def energy_free(u_free, lf):
    # Map free DOFs to full state accounting for BCs
    u_full = lf.lift_from_zeros(u_free)
    return total_energy(u_full)

# Trace sparsity of the reduced Hessian directly
traced_reduced_sparsity = pattern_from_energy(
    energy_free,
    lifter.size_reduced,
    lifter  # Passed as static_args
)

2. Virtual Work-Based Tracer with BCs¤

import jax
import jax.numpy as jnp
from tatva.sparse import pattern_from_virtual_work

@jax.jit
def virtual_work(test, trial):
    # Compute virtual work G(test, trial)
    return ...

@jax.jit
def virtual_work_free(test_free, trial_free, lf):
    # Map free trial and test variables to full states
    test_full = lf.lift_from_zeros(test_free)
    trial_full = lf.lift_from_zeros(trial_free)
    return virtual_work(test_full, trial_full)

# Trace sparsity of the reduced tangent stiffness matrix directly
traced_reduced_sparsity = pattern_from_virtual_work(
    virtual_work_free,
    lifter.size_reduced,
    "trial_free",
    "test_free",
    lifter  # Passed as static_args
)

Features¤

  • changes to the api for creating and reducing sparsity pattern (f2a5d2e)
  • sparse: adds automatic sparsity detection from energy form (4359503)

Bug Fixes¤

  • add custom_vjp/custom_jvp/remat primitives for tracing (38ab604)
  • add full test suite for checking if all jax primitives are covered (558ead9)
  • add test for sparsity tracer based on fem application (3311f78)
  • add tracer for opaque primitive such as ffi/callback and debug (83b0475)
  • only consider trial-test pair for coupling, vectorize python for-loop inside scan_mp for speed up (3f104d4)

0.10.1 (2026-04-27)¤

Bug Fixes¤

  • compound: create basic sparsity pattern from compound classes (9d959d6)
  • compound: incomplete nodal fields takes the local node ids now (a939beb)
  • compound: stack fields with any dims if prefix is same & respect stack=False (cd64646)
  • element: add value based equality for elements (ab784c5)
  • element: corrects the gradient enteries (91aef4c)
  • element: use einsum to support scalar, vector, and tensor fields (19cf253)
  • lifter: add adapt_sparsity which combines augment & reduce (af6db56)

0.10.0 (2026-04-23)¤

Features¤

  • constraint: parallel periodic constraint (f29ac8b)
  • lifter: add reduce_adjoint to reduce a dual vector (deead9c)
  • mesh: add utility function to extract local mesh from global mesh (0673b38)
  • mpi: add a communication plan for partitioned meshes based on Compound layouts (4e98892)
  • mpi: add all reduce plan for parallelization (79fc638)
  • sparse: add sparsity pattern augmentation with lifter constraints (54daf22)

Bug Fixes¤

  • compound: add helper to return global dof indices for Compound fields (e4abd97)
  • compound: allow inheritance of Compound subclasses (1dc9e51)
  • compound: clarify stacking logic & introduce AUTO sizing (3a3168a)
  • compound: correct global indexing into stacked fields (8bae34d)
  • compound: prevent fields with reserved names, prevent stacking with stack=False (5e4947e)
  • compound: remove metaclass and move initialization to init_subclass (1dc9e51)
  • compound: type of fields with AUTO in shape are NODAL by default (356b4a0)
  • constraint: bug in sparsity pattern for periodic constraint (e1069f8)
  • mpi: add function to reduce a dof layout (for lifter) (32173d0)
  • mpi: exchange plan accepts sparsity pattern, allreduce also replace indptr, indices (3dcd509)
  • mpi: makes hessian sparsity as optional arg in allreduce (a1d4b6b)
  • test: update test (79fc638)

0.9.1 (2026-04-12)¤

Bug Fixes¤

  • sparse: add linearized jacfwd with primal output (af72244)

0.9.0 (2026-03-27)¤

Features¤

  • lifter: add lifted method/decorator to lift functions (2077ffb)
  • operator: add an L2 project method (98a16d6)

Bug Fixes¤

  • compound: add Field.size attribute (cf8505d)
  • lifter: make dof arrays dynamic Array (b2222bc)
  • mesh: add _replace helper to update dataclass (2c1d9b6)
  • mesh: add hmin and hmax methods (489b76a)
  • mesh: hmin/hmax is the cell diameter which is 2*circumradius (6167223)
  • mesh: hotfix find_containing_polygons that points exactly on boundary are valid (3f95f2f)
  • minor fixes from code review (97c6bd4)
  • operator: make interpolate jittable (d9fe62b)
  • operator: set batch_size if None given (e57b362)
  • operator: skip element bounds checks in traced context (1b7a0a7)
  • sparse: make default for color_batch_size None but assign 0 (071af07)
  • sparse: revert the default for colored_batch_size to max color (9ee95da)
  • sparse: set default color_batch_size=max_color (2683d89)

Performance Improvements¤

  • mesh: AABB search for interpolation in triangles (32ff68d)

0.8.1 (2026-03-23)¤

Bug Fixes¤

  • make ColoredMatrix compatible with JAX>0.9.0 (ac51668)

0.8.0 (2026-03-16)¤

Features¤

  • add quadratic Tri6 element (37cf37a)
  • compound: add .at(...).set(...) logic to set subspaces (84d0c8d)
  • compound: add ability to provide individual shaped fields in init (921f6c4)
  • utils: add a decorator for virtual residual functions (#32) (c2d6db3)

Bug Fixes¤

  • compound: fix compound stack_fields for scalar fields (92bf79f)
  • compound: include default factory when recreating stacked fields (9ef3972)
  • compound: manage field indices, and arr updates without materializing a dense integer array of all indices (17897a1)
  • compound: preserve shape of scalar fields (don't enforce rank 2) (92bf79f)
  • compound: remove compound metaclass getitem (e42ad40)
  • element: move quadrature to instance, add quadrature as constructor args (#27) (06c9c19)

0.7.1 (2026-02-24)¤

Bug Fixes¤

  • remove jax BCOO based code for master-slave sparsity (ac49fc5)

0.7.0 (2026-02-24)¤

Features¤

  • sparse: add a ColoredMatrix type for sparse differentiation (2ab3214)

Bug Fixes¤

  • adapt sparse benchmark with new api (93d1cf4)
  • sparse: switch to scipy csr matrix in all sparsity pattern creation (2ab3214)

Performance Improvements¤

  • sparse: precompute reconstruction of data from J_compressed (d2f6a37)

0.6.0 (2026-02-20)¤

Features¤

  • element: add quadratic Line3 and Quad8 elements (#18) (37bffdd)
  • lifter: renamed constraints; DirichletBC -> Fixed; PeriodicMap -> (f4b9a78)
  • lifter: reworked Lifter with support for changing values (RuntimeValue) (f4b9a78)

Bug Fixes¤

  • compound: refactor stack_fields into a class decorator (305b87f)
  • element: allow interpolate func to accept nodal_coords (#16) (2042d98)
  • lifter: clarify constraint contract and make constraints hashable for jax.jit static args (ad08049)
  • lifter: support lifters as dynamic and static arguments to jitted (f4b9a78)
  • sparse: pass args and kwargs directly to colored jacobian to prevent recompilation and slowness (2d497df)
  • sparse: single jacfwd function with color batching by default (4f96770)

What's Changed¤

New Contributors¤

Full Changelog: https://github.com/smec-ethz/tatva/compare/v0.5.1...v0.6.0

0.5.1 (2026-02-15)¤

Bug Fixes¤

  • compound: respect default_factory for initialization of compound instances (#9) (7449120)
  • element: corrected Hex8 implementation, test for elements added (70755e6)

0.5.0 (2026-02-10)¤

Features¤

  • sparse: add coloring code (source mpundir) (0623e2c)
  • sparse: add method to generate sparsity pattern with full master-slave dof map (from zrlf) (5d37d56)

Bug Fixes¤

  • operator: removes check on quad points dimnension to be equal to coords dimension, necessary for 2D elements in 3D space (3827149)
  • operator: replaces jax.vmap with batched jax.lax.map for memory efficiency and scalin (fbab11a)
  • sparse: enables sparse jacfwd with args without performance issue (9ba9530)
  • sparse: process color based jacobian in batches, replaces jax.linearize with jax.jvp (6b361d7)
  • sparse: wraps jacfwd func to accept single parameter (9fe01e3)

0.4.0 (2026-01-27)¤

Features¤

  • add solver_utils a Lifter class making bcs easier (29de30b)
  • lifter: include periodic boundary conditions in the lifter (2e7ee32)

Bug Fixes¤

  • lifter: implement improvements based on review (250a4e0)
  • lifter: make constructor arguments 1 and 2 positional only (5230c75)

Documentation¤

  • lifter: extend docs for lifter module (77de185)