use crate::SolverSelection;
use crate::beam_fem::{
BeamElement, BeamModel, BeamNode, BeamSection, BeamSolver, Dof, FemError, ReducedSystem,
};
use crate::fea::mechanism::diagnose_reduced;
use crate::material::Material;
use std::collections::VecDeque;
pub use crate::fea::mechanism::StructuralDiagnostic;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct NodeHandle(usize);
impl NodeHandle {
pub fn index(self) -> usize {
self.0
}
pub fn from_index(index: usize) -> Self {
Self(index)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MemberHandle(usize);
impl MemberHandle {
pub fn index(self) -> usize {
self.0
}
pub fn from_index(index: usize) -> Self {
Self(index)
}
}
const EQUILIBRIUM_REL_TOL: f64 = 1e-6;
const EQUILIBRIUM_COND_FACTOR: f64 = 1e-2;
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EquilibriumReport {
pub fx_residual: f64,
pub fy_residual: f64,
pub mz_residual: f64,
pub applied_fx: f64,
pub applied_fy: f64,
pub applied_mz: f64,
pub reaction_fx: f64,
pub reaction_fy: f64,
pub reaction_mz: f64,
pub tolerance: f64,
f_mag: f64,
m_mag: f64,
l_char: f64,
cond_rel_floor: f64,
}
fn equilibrium_scales(f_mag: f64, m_mag: f64, l_char: f64) -> (f64, f64) {
if l_char > 0.0 {
(f_mag + m_mag / l_char, m_mag + f_mag * l_char)
} else {
(f_mag, m_mag)
}
}
impl EquilibriumReport {
pub fn is_balanced(&self) -> bool {
let (f_scale, m_scale) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
let rel = self.effective_rel_tol();
self.fx_residual.abs() <= rel * f_scale
&& self.fy_residual.abs() <= rel * f_scale
&& self.mz_residual.abs() <= rel * m_scale
}
fn effective_rel_tol(&self) -> f64 {
EQUILIBRIUM_REL_TOL.max(self.cond_rel_floor)
}
pub fn force_tolerance(&self) -> f64 {
let (f_scale, _) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
self.effective_rel_tol() * f_scale
}
pub fn moment_tolerance(&self) -> f64 {
let (_, m_scale) = equilibrium_scales(self.f_mag, self.m_mag, self.l_char);
self.effective_rel_tol() * m_scale
}
}
#[derive(Debug, Clone)]
pub struct FrameModel {
inner: BeamModel,
}
impl Default for FrameModel {
fn default() -> Self {
Self::new()
}
}
impl FrameModel {
pub fn new() -> Self {
Self {
inner: BeamModel::new(),
}
}
pub fn n_nodes(&self) -> usize {
self.inner.nodes.len()
}
pub fn n_members(&self) -> usize {
self.inner.elements.len()
}
pub fn add_node(&mut self, x: f64, y: f64) -> Result<NodeHandle, FemError> {
if !x.is_finite() || !y.is_finite() {
return Err(FemError::InvalidInput(format!(
"node coordinates must be finite, got ({x}, {y})"
)));
}
let idx = self.inner.nodes.len();
self.inner.add_node(BeamNode::new(idx, x, y));
Ok(NodeHandle(idx))
}
pub fn add_member(
&mut self,
a: NodeHandle,
b: NodeHandle,
material: Material,
section: BeamSection,
) -> Result<MemberHandle, FemError> {
let ia = self.check_node(a)?;
let ib = self.check_node(b)?;
if ia == ib {
return Err(FemError::ZeroLengthMember(format!(
"member connects node {ia} to itself"
)));
}
let (pa, pb) = (self.inner.nodes[ia].point(), self.inner.nodes[ib].point());
let (dx, dy) = (pb.x - pa.x, pb.y - pa.y);
if !dx.is_finite() || !dy.is_finite() || dx * dx + dy * dy <= 0.0 {
return Err(FemError::ZeroLengthMember(format!(
"nodes {ia} and {ib} coincide at ({}, {})",
pa.x, pa.y
)));
}
let (e, area, inertia) = (material.youngs_modulus, section.area, section.second_moment);
if !e.is_finite() || e <= 0.0 {
return Err(FemError::InvalidInput(format!(
"Young's modulus must be finite and positive, got {e}"
)));
}
if !area.is_finite() || area <= 0.0 {
return Err(FemError::InvalidInput(format!(
"cross-section area must be finite and positive, got {area}"
)));
}
if !inertia.is_finite() || inertia <= 0.0 {
return Err(FemError::InvalidInput(format!(
"second moment of area must be finite and positive, got {inertia}"
)));
}
let (lo, hi) = if ia < ib { (ia, ib) } else { (ib, ia) };
for existing in &self.inner.elements {
let (elo, ehi) = if existing.node_i < existing.node_j {
(existing.node_i, existing.node_j)
} else {
(existing.node_j, existing.node_i)
};
if elo == lo && ehi == hi {
return Err(FemError::DuplicateMember(format!(
"a member already connects nodes {lo} and {hi}; parallel members are not supported"
)));
}
}
let element = BeamElement::new(ia, ib, material, section)?;
self.inner.add_element(element);
Ok(MemberHandle(self.inner.elements.len() - 1))
}
pub fn fix(&mut self, node: NodeHandle) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.try_fix_node(i)
}
pub fn pin(&mut self, node: NodeHandle) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.try_fix_dof(i, Dof::Ux.index(), 0.0)?;
self.inner.try_fix_dof(i, Dof::Uy.index(), 0.0)
}
pub fn roller_y(&mut self, node: NodeHandle) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.try_fix_dof(i, Dof::Uy.index(), 0.0)
}
pub fn roller_x(&mut self, node: NodeHandle) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.try_fix_dof(i, Dof::Ux.index(), 0.0)
}
pub fn restrain(&mut self, node: NodeHandle, dof: Dof, value: f64) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.try_override(i, dof, value)
}
pub fn nodal_load(&mut self, node: NodeHandle, fx: f64, fy: f64) -> Result<(), FemError> {
let i = self.check_node(node)?;
if !fx.is_finite() {
return Err(FemError::InvalidInput(format!(
"nodal force Fx must be finite, got {fx}"
)));
}
if !fy.is_finite() {
return Err(FemError::InvalidInput(format!(
"nodal force Fy must be finite, got {fy}"
)));
}
self.inner.try_add_nodal_force(i, Dof::Ux.index(), fx)?;
self.inner.try_add_nodal_force(i, Dof::Uy.index(), fy)
}
pub fn nodal_moment(&mut self, node: NodeHandle, mz: f64) -> Result<(), FemError> {
let i = self.check_node(node)?;
self.inner.add_applied_moment(i, mz)
}
pub fn member_udl(&mut self, member: MemberHandle, qx: f64, qy: f64) -> Result<(), FemError> {
let i = self.check_member(member)?;
self.inner.add_distributed_load(i, qx, qy)
}
pub fn member_point_load(
&mut self,
member: MemberHandle,
xi: f64,
fx: f64,
fy: f64,
mz: f64,
) -> Result<(), FemError> {
let i = self.check_member(member)?;
self.inner.add_point_load(i, xi, fx, fy, mz)
}
pub fn solve(&self) -> Result<FrameAnalysisResult, FemError> {
self.solve_with(SolverSelection::Auto)
}
pub fn solve_with(&self, selection: SolverSelection) -> Result<FrameAnalysisResult, FemError> {
FrameSolver::new(self).with_selection(selection).solve()
}
pub fn solver(&self) -> FrameSolver<'_> {
FrameSolver::new(self)
}
pub fn validate(&self) -> Result<(), FemError> {
let inner = &self.inner;
if inner.nodes.is_empty() {
return Err(FemError::InvalidModel(
"frame has no nodes; add at least one node and one member".to_string(),
));
}
if inner.elements.is_empty() {
return Err(FemError::InvalidModel(
"frame has no members; add at least one member".to_string(),
));
}
let mut used = vec![false; inner.nodes.len()];
for e in &inner.elements {
used[e.node_i] = true;
used[e.node_j] = true;
}
if let Some(i) = used.iter().position(|u| !u) {
let p = inner.nodes[i].point();
return Err(FemError::OrphanNode(format!(
"node {i} at ({}, {}) is not connected to any member",
p.x, p.y
)));
}
let components = count_components(inner.nodes.len(), &inner.elements);
if components > 1 {
return Err(FemError::DisconnectedStructure(format!(
"frame has {components} disconnected components; a single connected \
structural system is required"
)));
}
Ok(())
}
pub fn diagnostic(&self) -> Result<StructuralDiagnostic, FemError> {
self.validate()?;
let mut beam = BeamSolver::from_model(&self.inner)?;
Ok(self.classify(beam.condense()))
}
fn classify(&self, reduced: &ReducedSystem) -> StructuralDiagnostic {
let rigid = self.rigid_candidates(reduced.free_to_global());
diagnose_reduced(reduced.k_ff(), &rigid)
}
fn rigid_candidates(&self, free_to_global: &[usize]) -> Vec<Vec<f64>> {
let n_free = free_to_global.len();
let mut tx = vec![0.0; n_free];
let mut ty = vec![0.0; n_free];
let mut rz = vec![0.0; n_free];
for (r, &global) in free_to_global.iter().enumerate() {
let point = self.inner.nodes[global / 3].point();
match global % 3 {
0 => {
tx[r] = 1.0;
rz[r] = -point.y;
}
1 => {
ty[r] = 1.0;
rz[r] = point.x;
}
_ => rz[r] = 1.0,
}
}
vec![tx, ty, rz]
}
pub fn node_handle(&self, index: usize) -> Result<NodeHandle, FemError> {
if index >= self.inner.nodes.len() {
return Err(FemError::InvalidNode(format!(
"node index {index} is out of range (max: {})",
self.inner.nodes.len().saturating_sub(1)
)));
}
Ok(NodeHandle(index))
}
pub fn member_handle(&self, index: usize) -> Result<MemberHandle, FemError> {
if index >= self.inner.elements.len() {
return Err(FemError::InvalidMember(format!(
"member index {index} is out of range (max: {})",
self.inner.elements.len().saturating_sub(1)
)));
}
Ok(MemberHandle(index))
}
fn check_node(&self, node: NodeHandle) -> Result<usize, FemError> {
if node.0 >= self.inner.nodes.len() {
return Err(FemError::InvalidNode(format!(
"node handle {} is not valid for this frame (max: {})",
node.0,
self.inner.nodes.len().saturating_sub(1)
)));
}
Ok(node.0)
}
fn check_member(&self, member: MemberHandle) -> Result<usize, FemError> {
if member.0 >= self.inner.elements.len() {
return Err(FemError::InvalidMember(format!(
"member handle {} is not valid for this frame (max: {})",
member.0,
self.inner.elements.len().saturating_sub(1)
)));
}
Ok(member.0)
}
}
fn count_components(n_nodes: usize, elements: &[BeamElement]) -> usize {
let mut adj: Vec<Vec<usize>> = vec![Vec::new(); n_nodes];
for e in elements {
adj[e.node_i].push(e.node_j);
adj[e.node_j].push(e.node_i);
}
let mut seen = vec![false; n_nodes];
let mut components = 0;
for start in 0..n_nodes {
if seen[start] || adj[start].is_empty() {
continue;
}
components += 1;
seen[start] = true;
let mut queue = VecDeque::from([start]);
while let Some(u) = queue.pop_front() {
for &v in &adj[u] {
if !seen[v] {
seen[v] = true;
queue.push_back(v);
}
}
}
}
components
}
pub struct FrameSolver<'a> {
model: &'a FrameModel,
selection: SolverSelection,
}
impl<'a> FrameSolver<'a> {
pub fn new(model: &'a FrameModel) -> Self {
Self {
model,
selection: SolverSelection::Auto,
}
}
pub fn with_selection(mut self, selection: SolverSelection) -> Self {
self.selection = selection;
self
}
pub fn set_solver(&mut self, selection: SolverSelection) {
self.selection = selection;
}
pub fn solve(&self) -> Result<FrameAnalysisResult, FemError> {
self.model.validate()?;
let mut beam = BeamSolver::from_model(&self.model.inner)?;
beam.set_solver(self.selection.clone());
if let Err(e) = beam.solve_configured() {
let diagnosis = beam.reduced_system().map(|rs| self.model.classify(rs));
return Err(with_structural_diagnosis(e, diagnosis));
}
Ok(FrameAnalysisResult {
beam,
model: self.model.clone(),
})
}
}
fn with_structural_diagnosis(err: FemError, diagnosis: Option<StructuralDiagnostic>) -> FemError {
match (err, diagnosis) {
(FemError::SolverError { source, message }, Some(d))
if !matches!(d, StructuralDiagnostic::Stable) =>
{
FemError::SolverError {
source,
message: format!("{message}; structural diagnosis: {d}"),
}
}
(other, _) => other,
}
}
pub struct FrameAnalysisResult {
beam: BeamSolver,
model: FrameModel,
}
impl std::fmt::Debug for FrameAnalysisResult {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("FrameAnalysisResult")
.field("nodes", &self.model.n_nodes())
.field("members", &self.model.n_members())
.field("solver", &self.beam.solver_name())
.finish_non_exhaustive()
}
}
impl FrameAnalysisResult {
pub fn solver_name(&self) -> Option<&str> {
self.beam.solver_name()
}
pub fn n_nodes(&self) -> usize {
self.model.n_nodes()
}
pub fn n_members(&self) -> usize {
self.model.n_members()
}
pub fn displacements(&self) -> &[f64] {
self.beam.displacements()
}
pub fn reactions(&self) -> Vec<f64> {
self.beam.reactions()
}
pub fn displacement(&self, node: NodeHandle, dof: Dof) -> Result<f64, FemError> {
self.check_node(node)?;
self.beam.displacement_dof(node.index(), dof)
}
pub fn reaction(&self, node: NodeHandle, dof: Dof) -> Result<f64, FemError> {
self.check_node(node)?;
self.beam.reaction_dof(node.index(), dof)
}
pub fn member_end_forces(&self, member: MemberHandle) -> Result<[f64; 6], FemError> {
let i = self.check_member(member)?;
let all = self.beam.element_end_forces()?;
all.get(i)
.copied()
.ok_or_else(|| FemError::InvalidMember(format!("member handle {} is out of range", i)))
}
pub fn member_end_forces_global(&self, member: MemberHandle) -> Result<[f64; 6], FemError> {
let i = self.check_member(member)?;
let all = self.beam.element_end_forces_global()?;
all.get(i)
.copied()
.ok_or_else(|| FemError::InvalidMember(format!("member handle {} is out of range", i)))
}
pub fn equilibrium(&self) -> EquilibriumReport {
let m = &self.model.inner;
let mut applied_fx = 0.0;
let mut applied_fy = 0.0;
let mut applied_mz = 0.0;
let mut applied_f_mag = 0.0;
let mut applied_m_mag = 0.0;
for (node, dof, v) in &m.nodal_forces {
let p = m.nodes[*node].point();
match *dof {
0 => {
applied_fx += v;
applied_mz += -p.y * v;
applied_f_mag += v.abs();
}
1 => {
applied_fy += v;
applied_mz += p.x * v;
applied_f_mag += v.abs();
}
_ => {
applied_mz += v;
applied_m_mag += v.abs();
}
}
}
for am in &m.applied_moments {
applied_mz += am.value;
applied_m_mag += am.value.abs();
}
for (elem_idx, dl) in m.distributed_loads.iter().enumerate() {
let _ = elem_idx;
let Some((pi, pj)) = member_points(m, dl.element_idx) else {
continue;
};
let (dx, dy) = (pj.x - pi.x, pj.y - pi.y);
let len = (dx * dx + dy * dy).sqrt();
let (c, s) = (dx / len, dy / len);
let (lfx, lfy) = (dl.qx * len, dl.qy * len);
let (gx, gy) = (c * lfx - s * lfy, s * lfx + c * lfy);
let (xm, ym) = (pi.x + 0.5 * dx, pi.y + 0.5 * dy);
applied_fx += gx;
applied_fy += gy;
applied_mz += xm * gy - ym * gx;
applied_f_mag += gx.abs() + gy.abs();
}
for pl in &m.point_loads {
let Some((pi, _)) = member_points(m, pl.element_idx) else {
continue;
};
let el = &m.elements[pl.element_idx];
let pj = m.nodes[el.node_j].point();
let (dx, dy) = (pj.x - pi.x, pj.y - pi.y);
let len = (dx * dx + dy * dy).sqrt();
let (c, s) = (dx / len, dy / len);
let (gx, gy) = (c * pl.fx - s * pl.fy, s * pl.fx + c * pl.fy);
let (xp, yp) = (pi.x + pl.position * dx, pi.y + pl.position * dy);
applied_fx += gx;
applied_fy += gy;
applied_mz += xp * gy - yp * gx + pl.mz;
applied_f_mag += gx.abs() + gy.abs();
applied_m_mag += pl.mz.abs();
}
let reactions = self.beam.reactions();
let mut reaction_fx = 0.0;
let mut reaction_fy = 0.0;
let mut reaction_mz = 0.0;
let mut reaction_f_mag = 0.0;
let mut reaction_m_mag = 0.0;
for (idx, node) in m.nodes.iter().enumerate() {
let p = node.point();
let rx = reactions.get(3 * idx).copied().unwrap_or(0.0);
let ry = reactions.get(3 * idx + 1).copied().unwrap_or(0.0);
let rz = reactions.get(3 * idx + 2).copied().unwrap_or(0.0);
reaction_fx += rx;
reaction_fy += ry;
reaction_mz += p.x * ry - p.y * rx + rz;
reaction_f_mag += rx.abs() + ry.abs();
reaction_m_mag += rz.abs();
}
let l_char = characteristic_length(m);
let f_mag = applied_f_mag + reaction_f_mag;
let m_mag = applied_m_mag + reaction_m_mag;
let cond_rel_floor = EQUILIBRIUM_COND_FACTOR * max_element_slenderness_sq(m) * f64::EPSILON;
let rel = EQUILIBRIUM_REL_TOL.max(cond_rel_floor);
let (f_scale, _m_scale) = equilibrium_scales(f_mag, m_mag, l_char);
EquilibriumReport {
fx_residual: applied_fx + reaction_fx,
fy_residual: applied_fy + reaction_fy,
mz_residual: applied_mz + reaction_mz,
applied_fx,
applied_fy,
applied_mz,
reaction_fx,
reaction_fy,
reaction_mz,
tolerance: rel * f_scale,
f_mag,
m_mag,
l_char,
cond_rel_floor,
}
}
fn check_node(&self, node: NodeHandle) -> Result<(), FemError> {
if node.index() >= self.model.n_nodes() {
return Err(FemError::InvalidNode(format!(
"node handle {} is not valid for this result (max: {})",
node.index(),
self.model.n_nodes().saturating_sub(1)
)));
}
Ok(())
}
fn check_member(&self, member: MemberHandle) -> Result<usize, FemError> {
if member.index() >= self.model.n_members() {
return Err(FemError::InvalidMember(format!(
"member handle {} is not valid for this result (max: {})",
member.index(),
self.model.n_members().saturating_sub(1)
)));
}
Ok(member.index())
}
}
fn member_points(
model: &BeamModel,
member: usize,
) -> Option<(crate::geometry::Point, crate::geometry::Point)> {
let el = model.elements.get(member)?;
Some((
model.nodes[el.node_i].point(),
model.nodes[el.node_j].point(),
))
}
fn characteristic_length(model: &BeamModel) -> f64 {
let mut l_char: f64 = 0.0;
for node in &model.nodes {
let p = node.point();
l_char = l_char.max(p.x.abs()).max(p.y.abs());
}
l_char
}
fn max_element_slenderness_sq(model: &BeamModel) -> f64 {
let mut lambda_sq: f64 = 0.0;
for el in &model.elements {
let p_i = model.nodes[el.node_i].point();
let p_j = model.nodes[el.node_j].point();
let l = el.length(p_i, p_j);
let i = el.section.second_moment;
if i > 0.0 {
lambda_sq = lambda_sq.max(l * l * el.section.area / i);
}
}
lambda_sq
}
#[cfg(test)]
mod reduced_system_single_source_tests {
use super::*;
use crate::fea::SparseMatrix;
fn steel() -> Material {
Material::new(200e9, 0.3, 7850.0, "Steel")
}
fn sec() -> BeamSection {
BeamSection::new(5e-3, 2e-5)
}
fn assert_agrees(f: &FrameModel, label: &str) -> Result<(), FemError> {
let mut beam = BeamSolver::from_model(&f.inner)?;
let from_solver = f.classify(beam.condense());
assert_eq!(
from_solver,
f.diagnostic()?,
"{label}: diagnostic disagrees with the solver's condensed system"
);
Ok(())
}
fn portal(base_1: &[Dof], base_2: &[Dof]) -> Result<FrameModel, FemError> {
let mut f = FrameModel::new();
let b1 = f.add_node(0.0, 0.0)?;
let t1 = f.add_node(0.0, 3.0)?;
let t2 = f.add_node(4.0, 3.0)?;
let b2 = f.add_node(4.0, 0.0)?;
f.add_member(b1, t1, steel(), sec())?;
f.add_member(t1, t2, steel(), sec())?;
f.add_member(b2, t2, steel(), sec())?;
for dof in base_1 {
f.restrain(b1, *dof, 0.0)?;
}
for dof in base_2 {
f.restrain(b2, *dof, 0.0)?;
}
Ok(f)
}
#[test]
fn diagnostic_classifies_the_solver_condensed_system() -> Result<(), FemError> {
let mut free = FrameModel::new();
let a = free.add_node(0.0, 0.0)?;
let b = free.add_node(2.0, 0.0)?;
free.add_member(a, b, steel(), sec())?;
assert_agrees(&free, "free beam")?;
let mut one = FrameModel::new();
let a = one.add_node(0.0, 0.0)?;
let b = one.add_node(2.0, 0.0)?;
one.add_member(a, b, steel(), sec())?;
one.restrain(a, Dof::Ux, 0.0)?;
assert_agrees(&one, "one-DOF-restrained beam")?;
let mut cant = FrameModel::new();
let base = cant.add_node(0.0, 0.0)?;
let tip = cant.add_node(2.0, 0.0)?;
cant.add_member(base, tip, steel(), sec())?;
cant.fix(base)?;
assert_agrees(&cant, "stable cantilever")?;
let fixed = portal(&[Dof::Ux, Dof::Uy, Dof::Rz], &[Dof::Ux, Dof::Uy, Dof::Rz])?;
assert_agrees(&fixed, "portal, both bases fixed")?;
let pinned = portal(&[Dof::Ux, Dof::Uy], &[Dof::Ux, Dof::Uy])?;
assert_agrees(&pinned, "portal, both bases pinned")?;
let roller = portal(&[Dof::Ux, Dof::Uy, Dof::Rz], &[Dof::Uy])?;
assert_agrees(&roller, "portal, fixed base + roller")?;
let mechanism = portal(&[Dof::Ux, Dof::Uy], &[])?;
assert_agrees(&mechanism, "portal, single pin (mechanism)")?;
Ok(())
}
#[test]
fn diagnostic_uses_the_supplied_matrix_not_a_copy() -> Result<(), FemError> {
let mut f = FrameModel::new();
let base = f.add_node(0.0, 0.0)?;
let tip = f.add_node(2.0, 0.0)?;
f.add_member(base, tip, steel(), sec())?;
f.fix(base)?;
let mut beam = BeamSolver::from_model(&f.inner)?;
let real = beam.condense().clone();
let stable = f.classify(&real);
assert_eq!(
stable,
StructuralDiagnostic::Stable,
"control must be stable"
);
let n = real.k_ff().n;
let mut forged_k = SparseMatrix::new(n);
for i in 0..n {
for j in 0..n {
let v = real.k_ff().get(i, j);
if i != 0 && j != 0 && v != 0.0 {
forged_k.add(i, j, v);
}
}
}
forged_k.compress();
let forged = ReducedSystem::new(forged_k, real.free_to_global().to_vec());
let verdict = f.classify(&forged);
assert_ne!(
verdict, stable,
"classify must read the supplied matrix: zeroing a free DOF changed nothing"
);
assert_eq!(f.diagnostic()?, stable);
Ok(())
}
#[test]
fn failed_solve_diagnosis_reads_the_solver_retained_system() -> Result<(), FemError> {
let mut f = FrameModel::new();
let a = f.add_node(0.0, 0.0)?;
let b = f.add_node(2.0, 0.0)?;
f.add_member(a, b, steel(), sec())?;
let expected = StructuralDiagnostic::RigidBodyMode {
n_free: 6,
rank: 3,
rigid_modes: 3,
};
let err = f.solve().expect_err("a free beam must not solve");
match &err {
FemError::SolverError { message, .. } => assert!(
message.contains("structural diagnosis") && message.contains(&expected.to_string()),
"expected the retained-system diagnosis in the error, got {message:?}"
),
other => panic!("expected SolverError, got {other:?}"),
}
let mut beam = BeamSolver::from_model(&f.inner)?;
assert!(
beam.solve_configured().is_err(),
"the identical solve must also fail"
);
let retained = beam
.reduced_system()
.expect("a failed solve still retains the condensed system it factorised");
assert_eq!(
f.classify(retained),
expected,
"the diagnosis must come from the solver's retained K_ff"
);
Ok(())
}
#[test]
fn diagnosis_only_annotates_mechanism_errors() {
use crate::fea::solver::SolverError;
let err = || FemError::from(SolverError::SingularMatrix("singular matrix".to_string()));
let untouched = err().to_string();
assert_eq!(
with_structural_diagnosis(err(), None).to_string(),
untouched
);
assert_eq!(
with_structural_diagnosis(err(), Some(StructuralDiagnostic::Stable)).to_string(),
untouched
);
let mechanism = StructuralDiagnostic::Mechanism { n_free: 4, rank: 3 };
let annotated = with_structural_diagnosis(err(), Some(mechanism));
assert!(
matches!(annotated, FemError::SolverError { .. }),
"the error variant must be preserved"
);
assert_eq!(
annotated.to_string(),
format!("{untouched}; structural diagnosis: {mechanism}")
);
}
#[test]
fn fully_restrained_model_is_stable_and_does_not_panic() -> Result<(), FemError> {
let mut f = FrameModel::new();
let a = f.add_node(0.0, 0.0)?;
let b = f.add_node(2.0, 0.0)?;
f.add_member(a, b, steel(), sec())?;
f.fix(a)?;
f.fix(b)?;
let mut beam = BeamSolver::from_model(&f.inner)?;
let reduced = beam.condense();
assert_eq!(reduced.k_ff().n, 0, "every DOF is restrained");
assert!(reduced.free_to_global().is_empty());
assert_eq!(f.classify(reduced), StructuralDiagnostic::Stable);
assert_eq!(f.diagnostic()?, StructuralDiagnostic::Stable);
let result = f.solve()?;
assert_eq!(result.displacement(a, Dof::Ux)?, 0.0);
assert_eq!(result.displacement(b, Dof::Rz)?, 0.0);
Ok(())
}
#[test]
fn condense_is_idempotent_and_retained() -> Result<(), FemError> {
let mut f = FrameModel::new();
let base = f.add_node(0.0, 0.0)?;
let tip = f.add_node(2.0, 0.0)?;
f.add_member(base, tip, steel(), sec())?;
f.fix(base)?;
let mut beam = BeamSolver::from_model(&f.inner)?;
assert!(beam.reduced_system().is_none(), "nothing condensed yet");
let first = beam.condense() as *const ReducedSystem;
let second = beam.condense() as *const ReducedSystem;
assert_eq!(
first, second,
"repeated condense() must return the retained system, not rebuild it"
);
beam.solve_configured()?;
let after_k = beam
.reduced_system()
.expect("retained after a successful solve")
.k_ff()
.clone();
let after_ptr = beam.reduced_system().unwrap() as *const ReducedSystem;
assert_eq!(after_k.n, 3, "cantilever tip has 3 free DOFs");
assert_eq!(
beam.condense() as *const ReducedSystem,
after_ptr,
"condense() after a solve still returns the retained system"
);
beam.set_solver(SolverSelection::Auto);
let again = beam.condense();
assert_eq!(again.k_ff().n, after_k.n);
for i in 0..after_k.n {
for j in 0..after_k.n {
assert_eq!(
again.k_ff().get(i, j),
after_k.get(i, j),
"K_ff entry ({i},{j}) changed without a model change"
);
}
}
Ok(())
}
}
#[cfg(test)]
mod equilibrium_tolerance_tests {
use super::*;
fn report(
fx_residual: f64,
fy_residual: f64,
mz_residual: f64,
f_mag: f64,
m_mag: f64,
l_char: f64,
) -> EquilibriumReport {
let (f_scale, _) = equilibrium_scales(f_mag, m_mag, l_char);
EquilibriumReport {
fx_residual,
fy_residual,
mz_residual,
applied_fx: 0.0,
applied_fy: 0.0,
applied_mz: 0.0,
reaction_fx: 0.0,
reaction_fy: 0.0,
reaction_mz: 0.0,
tolerance: EQUILIBRIUM_REL_TOL * f_scale,
f_mag,
m_mag,
l_char,
cond_rel_floor: 0.0,
}
}
#[test]
fn force_and_moment_scales_are_unit_invariant() {
let (f_si, m_si) = equilibrium_scales(2.0e6, 0.0, 5.0e2);
assert_eq!(f_si, 2.0e6);
assert_eq!(m_si, 1.0e9);
let (f_kmm, m_kmm) = equilibrium_scales(2.0e3, 0.0, 5.0e5);
assert_eq!(f_kmm, 2.0e3);
assert_eq!(m_kmm, m_si);
}
#[test]
fn moment_scale_is_non_degenerate_with_zero_applied_moment() {
let (_, m_scale) = equilibrium_scales(2.0e6, 0.0, 5.0e2);
assert_eq!(m_scale, 2.0e6 * 5.0e2);
assert!(m_scale > 0.0);
}
#[test]
fn scales_vanish_only_when_nothing_is_present() {
assert_eq!(equilibrium_scales(0.0, 0.0, 5.0e2), (0.0, 0.0));
assert_eq!(equilibrium_scales(0.0, 0.0, 0.0), (0.0, 0.0));
}
#[test]
fn unloaded_report_is_balanced_only_with_exact_zero_residual() {
assert!(report(0.0, 0.0, 0.0, 0.0, 0.0, 5.0e2).is_balanced());
assert!(!report(0.0, 0.0, f64::MIN_POSITIVE, 0.0, 0.0, 5.0e2).is_balanced());
assert!(!report(f64::MIN_POSITIVE, 0.0, 0.0, 0.0, 0.0, 5.0e2).is_balanced());
}
#[test]
fn corrupted_reaction_is_still_rejected() {
let (f_scale, m_scale) = equilibrium_scales(1.0e6, 0.0, 5.0e2);
assert!(
report(
1e-15 * f_scale,
1e-15 * f_scale,
1e-15 * m_scale,
1.0e6,
0.0,
5.0e2
)
.is_balanced()
);
assert!(
!report(
1e-3 * f_scale,
1e-3 * f_scale,
1e-3 * m_scale,
1.0e6,
0.0,
5.0e2
)
.is_balanced()
);
}
fn report_with_cond(
fx_residual: f64,
fy_residual: f64,
mz_residual: f64,
f_mag: f64,
m_mag: f64,
l_char: f64,
cond_rel_floor: f64,
) -> EquilibriumReport {
let (f_scale, _) = equilibrium_scales(f_mag, m_mag, l_char);
let rel = EQUILIBRIUM_REL_TOL.max(cond_rel_floor);
EquilibriumReport {
fx_residual,
fy_residual,
mz_residual,
applied_fx: 0.0,
applied_fy: 0.0,
applied_mz: 0.0,
reaction_fx: 0.0,
reaction_fy: 0.0,
reaction_mz: 0.0,
tolerance: rel * f_scale,
f_mag,
m_mag,
l_char,
cond_rel_floor,
}
}
#[test]
fn conditioning_floor_accepts_roundoff_rejects_genuine_imbalance() {
let lambda_sq = 2.5e14;
let cond_floor = EQUILIBRIUM_COND_FACTOR * lambda_sq * f64::EPSILON;
assert!(
cond_floor > EQUILIBRIUM_REL_TOL,
"this test needs a floor above the base tolerance"
);
let (f_scale, m_scale) = equilibrium_scales(1.0e12, 0.0, 5.0e5);
assert!(
report_with_cond(
0.1 * cond_floor * f_scale,
0.1 * cond_floor * f_scale,
0.1 * cond_floor * m_scale,
1.0e12,
0.0,
5.0e5,
cond_floor
)
.is_balanced(),
"round-off below the conditioning floor must be accepted"
);
assert!(
!report_with_cond(
10.0 * cond_floor * f_scale,
10.0 * cond_floor * f_scale,
10.0 * cond_floor * m_scale,
1.0e12,
0.0,
5.0e5,
cond_floor
)
.is_balanced(),
"imbalance above the conditioning floor must be rejected"
);
}
#[test]
fn conditioning_floor_is_dimensionless_and_unit_invariant() {
let l_si = 1.0e6_f64;
let a_si = 5.0e-3_f64;
let i_si = 2.0e-5_f64;
let lambda_sq_si = l_si * l_si * a_si / i_si;
let l_kmm = 1.0e9_f64; let a_kmm = 5.0e3_f64; let i_kmm = 2.0e7_f64; let lambda_sq_kmm = l_kmm * l_kmm * a_kmm / i_kmm;
let avg = 0.5 * (lambda_sq_si + lambda_sq_kmm);
assert!(
(lambda_sq_si - lambda_sq_kmm).abs() <= 10.0 * f64::EPSILON * avg,
"λ² must be unit-invariant (SI={}, kN/mm={})",
lambda_sq_si,
lambda_sq_kmm
);
}
}