solver, model: imperfections from buckling modes in nonlinear steps

NonlinearStatic.imperfection {step, mode, scale}: the buckling step's mode, scaled to a largest
component of `scale`, is added to the node coordinates before the step is solved, with a warning
naming it; Abaqus and LS-DYNA decks refuse it by name. A clamped–free column with its first mode
as imperfection under half its buckling load amplifies it by 1/(1 − α) within 2.8 %.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01UhhZMBTviDQxZvwnyP89fo

crates/solver/src/nonlinear.rs

@@ -98,7 +98,7 @@ use fieldcraft_fem::finite::{Kinematics, Temperature};
 use fieldcraft_fem::plane::Theory;
 use fieldcraft_fem::quadrature::Rule;
 use fieldcraft_fem::{DofKind, DofSet, ElementType, PointStress, face, von_mises};
-use fieldcraft_model::{BoundaryCondition, Extent, Hardening, Load, Model, NonlinearStatic, Plastic, Procedure, SectionKind, Step};
+use fieldcraft_model::{BoundaryCondition, Extent, Hardening, Imperfection, Load, Model, NonlinearStatic, Plastic, Procedure, SectionKind, Step};
 use fieldcraft_parallel as parallel;
 use serde::Serialize;
 
@@ -837,14 +837,50 @@ fn followers(model: &Model, resolved: &fieldcraft_model::Resolved, mesh: &Mesh,
 /// Solve a nonlinear static step: the step named `step`, or the model's only nonlinear static
 /// step.
 pub fn solve_nonlinear(model: &Model, step: Option<&str>, limits: &Limits) -> Result<StaticResult> {
-    let resolved = model.resolve()?;
-    let step = model.select_step(step, |p| matches!(p, Procedure::NonlinearStatic(_)), "nonlinear static")?;
-    let Procedure::NonlinearStatic(settings) = &step.procedure else {
+    let chosen = model.select_step(step, |p| matches!(p, Procedure::NonlinearStatic(_)), "nonlinear static")?;
+    let Procedure::NonlinearStatic(settings) = &chosen.procedure else {
         return Err(Error::Internal("nonlinear static step".into()));
     };
     settings.validate()?;
+    let Some(imperfection) = &settings.imperfection else { return solve_on(model, chosen.name.as_str(), limits, Vec::new()) };
+    let (perturbed, note) = imperfect(model, imperfection, limits)?;
+    solve_on(&perturbed, chosen.name.as_str(), limits, vec![note])
+}
+
+/// The model with a buckling mode, scaled to a largest component of `scale`, added to its node
+/// coordinates (the buckling step solved first), and a note saying so.
+fn imperfect(model: &Model, imperfection: &Imperfection, limits: &Limits) -> Result<(Model, String)> {
+    let Imperfection { step, mode, scale } = imperfection;
+    if !matches!(model.step(step).map(|s| &s.procedure), Some(Procedure::Buckle { .. })) {
+        return Err(Error::Invalid(format!("the imperfection names step `{step}`, which is not a buckling step")));
+    }
+    let buckled = crate::buckle::solve_buckle(model, Some(step), limits)?;
+    let shape =
+        usize::try_from(*mode).ok().and_then(|m| m.checked_sub(1)).and_then(|m| buckled.modes.get(m)).ok_or_else(|| {
+            Error::Invalid(format!("the imperfection takes mode {mode} of step `{step}`, which found {} modes", buckled.modes.len()))
+        })?;
+    let mut out = model.clone();
+    for (label, u) in buckled.nodes.iter().zip(&shape.shape) {
+        let node = model.node(*label).ok_or_else(|| Error::Internal(format!("node {label}")))?;
+        let xyz: [f64; 3] = std::array::from_fn(|k| node.xyz[k] + scale * u[k]);
+        out.set_node(*label, xyz)?;
+    }
+    let note = format!(
+        "solved on an imperfect geometry: mode {mode} of buckling step `{step}` (load factor {:.6e}) scaled to {scale} added to the node coordinates",
+        shape.eigenvalue
+    );
+    Ok((out, note))
+}
+
+fn solve_on(model: &Model, step: &str, limits: &Limits, notes: Vec<String>) -> Result<StaticResult> {
+    let resolved = model.resolve()?;
+    let step = model.step(step).ok_or_else(|| Error::Internal("nonlinear static step".into()))?;
+    let Procedure::NonlinearStatic(settings) = &step.procedure else {
+        return Err(Error::Internal("nonlinear static step".into()));
+    };
     let mesh = Mesh::new(model, &resolved, limits.max_dofs)?;
-    let mut warnings: Vec<String> = resolved.warnings.iter().map(ToString::to_string).chain(mesh.warnings.iter().cloned()).collect();
+    let mut warnings: Vec<String> =
+        notes.into_iter().chain(resolved.warnings.iter().map(ToString::to_string)).chain(mesh.warnings.iter().cloned()).collect();
     check_supported(model, &mesh, step, settings, &mut warnings)?;
     let (graph, order) = pattern(&mesh);
     ignored_dashpots(&mesh, &mut warnings);

crates/solver/tests/buckle.rs

@@ -91,3 +91,37 @@ fn buckling_steps_refuse_what_they_cannot_do() {
     assert!(Procedure::Buckle { modes: 0, shift: None }.validate().is_err());
     assert!(Procedure::Buckle { modes: 1, shift: Some(f64::NAN) }.validate().is_err());
 }
+
+/// A clamped–free column given its first buckling mode as an imperfection δ₀ at the top, under a
+/// dead end force of half its buckling load: the top's lateral deflection grows to
+/// δ₀ / (1 − P/P_cr) = 2 δ₀ (Timoshenko & Gere 1961, §1.12, for the mode-shaped imperfection).
+#[test]
+fn an_imperfection_from_the_buckling_mode() {
+    let mut g = column(L / 2.0, 10, None);
+    g.fixed("base", |x| near(x[2], 0.0));
+    let critical = solve_buckle(&g.model, Some("Step"), &Limits::default()).unwrap().modes[0].eigenvalue * B * B;
+    let delta0 = 0.01;
+    g.node_set("tip", |x| near(x[2], 1.0));
+    g.model
+        .add_load("push", Load::Force { target: Target::Set("tip".into()), vector: [0.0, 0.0, -0.5 * critical], distribution: Distribution::Total })
+        .unwrap();
+    let settings = NonlinearStatic { imperfection: Some(Imperfection { step: "Step".into(), mode: 1, scale: delta0 }), ..NonlinearStatic::default() };
+    let mut nl = Step::new("Push", Procedure::NonlinearStatic(settings));
+    nl.boundary_conditions.insert("base".into());
+    nl.loads.insert("push".into());
+    g.model.add_step(nl, None).unwrap();
+    let r = fieldcraft_solver::solve_nonlinear(&g.model, Some("Push"), &Limits::default()).unwrap();
+    assert!(r.warnings.iter().any(|w| w.contains("imperfect geometry")), "{:?}", r.warnings);
+    let lateral = r.displacement.iter().map(|u| u[0].hypot(u[1])).fold(0.0, f64::max);
+    // The deflection added to δ₀: δ₀ α/(1 − α) = δ₀ at α = ½.
+    eprintln!("imperfection {delta0}: added top deflection {lateral:.6e}");
+    assert!((lateral / delta0 - 1.0).abs() < 0.05, "{lateral}");
+    // A mode the buckling step does not have, or a step that does not buckle.
+    let mut bad = g.model.clone();
+    let mut s = bad.step("Push").unwrap().clone();
+    if let Procedure::NonlinearStatic(n) = &mut s.procedure {
+        n.imperfection = Some(Imperfection { step: "Step".into(), mode: 9, scale: delta0 });
+    }
+    bad.replace_step(s).unwrap();
+    assert!(fieldcraft_solver::solve_nonlinear(&bad, Some("Push"), &Limits::default()).is_err());
+}