jax-modal-analysis

name	jax-modal-analysis
description	3D tetrahedral FEM modal analysis of a membrane STL. Takes a binary STL (mm units) + material properties JSON, repairs surface mesh, generates tetrahedral volume mesh via TetGen, assembles 3D stiffness/mass matrices with jax-fem, solves the generalised eigenvalue problem, and reports eigenfrequencies + mode shapes. Returns artifact JSON with eigenfrequencies_hz, eigenfrequencies_khz, modes_in_range, target_range_pass, and paths to summary PNG and CSV.
metadata	{"category":"materials-design","requires":"stl_modal_pipeline, tetgen, pyvista, meshio, trimesh, scipy, jax","conda_env":"jax_fem"}

JAX 3D Modal Analysis

Full 3D tetrahedral FEM eigenvalue solver for ribbed membrane resonators. Complements fem-analysis (2D Kirchhoff plate approximation) by accounting for 3D volumetric effects, frame stiffness, and out-of-plane deformation.

Usage

python3 {baseDir}/scripts/jax_modal_analysis.py \
  --stl /path/to/membrane.stl \
  --material '{"E_Pa":3e9,"nu":0.35,"rho_kg_m3":1500}' \
  --num-modes 12 \
  --solver-backend jax-iterative \
  --stl-length-scale 1e-3 \
  --target-freq-min 2000 \
  --target-freq-max 8000 \
  --output-dir /tmp/jax_modal_results

Arguments

Flag	Type	Default	Description
--stl	path	required	Binary STL file (mm units assumed)
--material	JSON str	required	{"E_Pa":3e9,"nu":0.35,"rho_kg_m3":1500}
--num-modes	int	12	Number of modes to compute
--solver-backend	str	jax-iterative	arpack, jax-iterative, or jax-xla
--stl-length-scale	float	1e-3	Scale factor to convert STL units → metres
--target-freq-min	float	2000	Lower bound of target frequency band (Hz)
--target-freq-max	float	8000	Upper bound of target frequency band (Hz)
--output-dir	path	auto	Directory for all output files

Output JSON

{
  "stl_path": "/path/to/membrane.stl",
  "topology": "v1_cricket_fine",
  "num_modes_computed": 12,
  "eigenfrequencies_hz":  [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 2153.0, 2388.1, ...],
  "eigenfrequencies_khz": [0.000, 0.000, 0.000, 0.000, 0.000, 0.000, 2.153, 2.388, ...],
  "modes_in_range_hz":  [2153.0   
      
    
    
   
   
   
   
   
   

Chaining with fem-analysis

fem-analysis and jax-modal-analysis are complementary, not alternatives:

Skill	Model	Speed	Best for
fem-analysis	2D Kirchhoff plate	~1 s	Fast screening, flat membranes
jax-modal-analysis	3D tetrahedral FEM	30–120 s	Full 3D validation, ribbed/curved geometries

Recommended workflow:

1. Run fem-analysis to shortlist candidates (fast 2D pass/fail)
2. Run jax-modal-analysis on shortlisted STLs for full 3D validation