rlx-fdm

Force density method (FDM) for pin-jointed structures in RLX, with logic ported from jax_fdm.

Borrowed from jax_fdm

Quick start

use rlx_fdm::{Network, fdm};

let network = Network::arch_chain(5.0, 10, -1.0, -0.2);
let eq = fdm(&network).expect("equilibrium");
// Free-node z should sag negative under vertical load.
assert!(eq.xyz[[1, 2]] < 0.0);

Features

Sparse + nonlinear

use rlx_fdm::{Network, fdm_with_options, FdmOptions};

let mut net = Network::arch_chain(5.0, 10, -1.0, 0.0);
net.edges_load_uniform([0.0, 0.0, -0.05]);

let opts = FdmOptions::nonlinear(50, 1e-6, true);
let eq = fdm_with_options(&net, &opts)?;

• sparse: SparseStiffness CSR + PCG (sparse.rs, solve.rs)
• nonlinear: fixed-point x ← K⁻¹ P(x) with edge loads × length (iterative.rs, loads.rs)

Deferred features (implemented)

Inverse design

cargo run -p rlx-fdm --example inverse_design
cargo run -p rlx-fdm --example constrained_arch

• inverse_design: manual GD on q for one edge-length target.
• constrained_arch: constrained_fdm with NetworkLoadpath + EdgeLength goals and EdgeQ / length caps.

use rlx_fdm::{constrained_fdm, Constraint, Goal, Network, OptimizeConfig};

let net = Network::arch_chain(5.0, 10, -1.0, -0.2);
let goals = vec![Goal::network_loadpath(12.0, 1.0)];
let constraints = vec![Constraint::all_edge_q(-50.0, -0.5, 0.01)];
let cfg = OptimizeConfig::arch_form_finding(); // L-BFGS + linear FDM + sparse PCG
let res = constrained_fdm(&net, &goals, &constraints, &cfg)?;

End-to-end loop (one iteration): equilibrium solve → goal + constraint grads → implicit dL/dq using EquilibriumModel::pack_xyz_free (no extra fixed-point re-solve). Topology is cached in OptWorkspace; L-BFGS line search trials only vary q.

Fused MIR (feature ir, fuse_mir): FusedEquilibriumRunner compiles q → x_f once per topology and reuses it inside constrained_fdm (enabled by default in OptimizeConfig::arch_form_finding). With feature fuse, FusedAutodiffFormFinding adds loss + dL/dq through sparse PCG in one compiled graph.

Chain rule: goals_grad_xyz_free + constraint grads → grad_loss_wrt_q (implicit adjoint).

Design parameters, losses, optimizers (jax_fdm 1–5)

• DesignParam / DesignVector: all-edge q, single EdgeQ, support XYZ, free-node loads.
• Loss + ErrorKind: squared / RMS / absolute / prediction / log-max aggregation (pass via OptimizeConfig::losses or default from goals).
• OptimizerKind::Slsqp / Ipopt: penalty + L-BFGS on box x with FD on nonlinear inequalities (Constraint::edge_angle, node tangent / normal).
• OptimizeConfig::force_dense_with_constraints: dense FDM when constraints are active (jax_fdm policy).

Goals (jax_fdm subset)

Mesh I/O (feature io)

use rlx_fdm::io::{from_json_path, mesh_from_json_str, merge_mesh, to_json_str, MeshDocument};

let mut net = from_json_path("data/quad_mesh.json")?;
let mesh = mesh_from_json_str(r#"{"faces":[[0,1,2]],"faces_load":[[0,0,-1]]}"#)?;
merge_mesh(&mut net, &mesh);
let json = to_json_str(&net)?;

MIR optimizer hook (feature ir + rlx-sparse)

With features = ["ir", "rlx-sparse"], FdmMirOptimizer::build_equilibrium_graph wires fdm_q → fdm.assemble_csr_values → rlx_sparse.pcg_solve (×3) with param fdm_P. Autodiff through the graph matches the host PCG adjoint in solve_adjoint_columns.

MIR optimizer hook (feature ir)

use rlx_fdm::mir_opt::{FdmMirOptimizer, FdmGradMode, goals_grad_wrt_q};
use rlx_fdm::graph::{fdm_dense_graph, build_grad_q_custom_fn, FdmGradQSignature};

let opt = FdmMirOptimizer { grad_mode: FdmGradMode::FixedPoint(cfg), ..Default::default() };
let gq = goals_grad_wrt_q(&opt, &network, &goals, None)?;

build_grad_q_custom_fn emits fdm_dq param; fill with set_grad_q_param before Session::run for host dL/dq in fused graphs.

RLX integration path

1. Today: nonlinear fixed-point adjoint (edge loads), full goal library, mesh JSON, FdmMirOptimizer + constrained_fdm.
2. Next: IPOPT interface (external); tighter PCG-VJP vs host linear adjoint.

Anderson acceleration: set IterativeConfig::anderson_depth > 0 on nonlinear solves. Implicit adjoint unrolls a full tmax trajectory (eta = 0) so it matches central-difference dL/dq.