# 2D Structural Analysis Verification Plan

Status: In progress
Owner: Optimal Beam
Applies to: `/2d-structural-analysis/`
Initial verification date: 2026-07-25

## 1. Purpose

This plan defines the evidence required to release the 2D structural analysis
application with a defensible level of numerical and workflow confidence.

The objective is not to claim that the software is "bug-free." The objective is
to demonstrate, for a clearly stated domain of use, that:

1. the production solver agrees with independently established results;
2. equilibrium, transformations, releases, and linearity properties hold;
3. invalid or unstable models fail safely and clearly;
4. the browser workflow preserves the model and reports the solver result
   faithfully; and
5. the public verification material is generated from the same evidence used by
   the release tests.

## 2. Terminology and claim boundary

- **Code verification** asks whether the mathematical formulation has been
  implemented and solved correctly.
- **Calculation verification** asks whether a specific model was built, solved,
  and interpreted correctly.
- **Validation** compares a model with physical behaviour or an accepted
  representation of physical behaviour.

The launch evidence will be described as **solver verification**. The site must
not imply certification, code compliance, design approval, or experimental
validation unless that work has actually been completed and documented.

Recommended public wording:

> This release passed the documented benchmark suite within the stated
> tolerances for first-order, linear-elastic 2D frame and truss analysis.
> Verification does not constitute design certification or replace independent
> professional review.

## 3. Verified domain

### Included

- Two-dimensional static analysis
- Three degrees of freedom per node: global X, global Y, and rotation
- Axial and Euler-Bernoulli flexural stiffness
- First-order, small-displacement, linear-elastic response
- Continuous, one-end-released, and pin-ended members
- Nodal forces and nodal moments
- Member point loads
- Full, partial, uniform, and linearly varying distributed loads
- Local- and global-direction member loads
- Fixed, pinned, roller, and custom nodal restraints
- Per-member material and section properties
- Structural self-weight
- Linear load cases and user-defined combinations
- Plane frames, pin-jointed trusses, and mixed models

### Excluded

- P-Delta and other second-order effects
- Geometric or material nonlinearity
- Tension-only or compression-only members
- Shear deformation
- Support settlement and imposed strain
- Thermal loading
- Buckling, modal, response-spectrum, and time-history analysis
- Section resistance, connection capacity, and code-based member design

Any future feature that changes this domain must add verification cases before
release.

## 4. Risk priorities

Verification work is ordered by the consequence and likelihood of an incorrect
result.

| Priority | Risk | Required evidence |
| --- | --- | --- |
| P0 | Element stiffness, units, reactions, and displacements | Closed-form axial and beam cases |
| P0 | Local/global coordinate transformation on inclined members | Rotated member cases with global loads |
| P0 | End-release condensation and response recovery | Fixed-pinned and pin-ended cases |
| P0 | Force, shear, moment, displacement, and reported extrema | Full response checks at known critical locations |
| P0 | Stability and equilibrium diagnostics | Mechanisms, invalid models, and residual limits |
| P1 | Truss force recovery | Hand-solvable and independently solved trusses |
| P1 | Indeterminate frame response | Independent frame-solver comparisons |
| P1 | Mixed frame and pin-ended behaviour | Independently solved braced frames |
| P1 | Load cases, combinations, and self-weight | Superposition and hand-calculated totals |
| P1 | Metric/imperial equivalence | Same physical model in both working systems |
| P1 | Browser-to-solver integrity | Real browser end-to-end workflows |
| P2 | Large-model robustness and uncommon edit sequences | Randomized, performance, and exploratory checks |

## 5. Benchmark case matrix

The target release suite contains 25 permanent benchmark models.

### Beams and axial members

1. `OB-V-BAR-001` — horizontal axial bar with an end force
2. `OB-V-BEAM-001` — cantilever with a transverse tip force
3. `OB-V-BEAM-002` — cantilever with an applied tip moment
4. `OB-V-BEAM-003` — simply supported beam with a full UDL
5. `OB-V-BEAM-004` — fixed-pinned beam with a full UDL
6. `OB-V-BEAM-005` — simply supported beam with a triangular load
7. `OB-V-BEAM-006` — simply supported beam with an off-centre point load
8. `OB-V-BEAM-007` — simply supported beam with a partial UDL
9. `OB-V-BEAM-008` — fixed-fixed beam with a full UDL
10. `OB-V-BEAM-009` — cantilever with a full UDL
11. `OB-V-XFORM-001` — inclined member with a global point load

### Trusses

12. `OB-V-TRUSS-001` — symmetric triangular truss
13. `OB-V-TRUSS-002` — asymmetric triangular truss
14. `OB-V-TRUSS-003` — triangular truss with a horizontal joint load
15. `OB-V-TRUSS-004` — four-panel Pratt truss
16. `OB-V-TRUSS-005` — four-panel Warren truss with a zero-force check

### Frames

17. `OB-V-FRAME-001` — symmetric portal under beam gravity load
18. `OB-V-FRAME-002` — portal under lateral joint load
19. `OB-V-FRAME-003` — asymmetric portal with combined loading
20. `OB-V-FRAME-004` — gable frame with global vertical roof loading
21. `OB-V-FRAME-005` — two-bay or two-storey elastic frame

### Mixed behaviour and load organization

22. `OB-V-MIXED-001` — braced portal with pin-ended diagonal members
23. `OB-V-MIXED-002` — span-loaded pin-ended member and warning behaviour
24. `OB-V-LOAD-001` — structural self-weight with independently calculated total
25. `OB-V-LOAD-002` — factored combination compared with superposed case results

## 6. Required checks per case

Each case must check every applicable result category, not only a headline
maximum:

- support reactions;
- selected nodal translations and rotations;
- member axial, shear, and moment response;
- end forces and released-end zero moments;
- response at load discontinuities and known critical locations;
- applicable maximum displacement and force values;
- global force and moment equilibrium;
- stiffness-system residual;
- condition estimate and stability classification; and
- expected warnings or errors.

## 7. Reference hierarchy

Expected values must be established independently of the production solver.
They must never be copied from a production run and relabelled as reference
values.

Use the following hierarchy:

1. exact closed-form derivation;
2. hand solution by joints, sections, virtual work, slope-deflection, or direct
   stiffness;
3. a separately maintained calculation spreadsheet;
4. a documented comparison with an independent solver such as OpenSees; and
5. a qualified independent engineering review.

At least one closed-form or hand-solvable case must exercise each fundamental
solver feature. At least five indeterminate or mixed cases must also be compared
with an independent solver.

## 8. Acceptance rules

Every check declares its unit, expected value, absolute tolerance, and relative
tolerance before execution.

For a numerical value, the acceptance limit is:

`absolute tolerance + relative tolerance × |expected value|`

The check passes when:

`|calculated value - expected value| <= acceptance limit`

The following targets apply to well-conditioned benchmark models:

| Check | Target |
| --- | --- |
| Closed-form force, moment, or displacement | Relative difference no greater than `1e-6`, with a case-specific absolute tolerance near zero |
| Independent solver comparison | Relative difference no greater than `1e-4` after matching modelling conventions |
| Expected zero force, moment, or displacement | Case-specific absolute tolerance stated in the displayed engineering unit |
| Relative equilibrium residual | No greater than `1e-10` |
| Released-end moment | No greater than the declared near-zero moment tolerance |
| Metric/imperial equivalence | No greater than `1e-9` in canonical internal units |

### Reported extrema

The solver evaluates response at 61 regular diagram stations, load
discontinuities, and numerically recovered critical stations. Critical stations
include roots governing bending moment, axial force, shear force, and
displacement magnitude within each continuous load interval.

Benchmark cases must verify both the reported extremum and its critical
location where a closed-form location is available. Recovered critical
locations use the same strict result tolerance as other closed-form checks.

No tolerance may be widened merely to make a failing case pass. A tolerance
change requires a written reason and review.

## 9. Invariant and generated checks

In addition to the 25 reference cases, automated checks will verify:

- load scaling;
- load-case superposition;
- metric/imperial equivalence;
- member-connectivity reversal;
- model translation and reflection;
- subdivision at an unloaded intermediate node;
- released-end conditions;
- global and nodal equilibrium;
- finite output values;
- mechanism and disconnected-node detection;
- crossing-member warnings; and
- sensitivity warnings for ill-conditioned systems.

Controlled randomized models may be used for invariants, but randomized output
will not replace cases with independently established answers.

## 10. Browser verification

Real browser tests will cover Chromium, Firefox, and WebKit where practical.
The minimum launch workflows are:

1. create, load, edit, and solve a beam;
2. open and solve every supplied template;
3. invalidate stale results after a model change;
4. switch between metric and imperial display;
5. create load cases and a combination and change the active scenario;
6. apply a custom support and member release;
7. save and reopen a model without numerical drift;
8. generate a PDF matching the current model, units, and scenario;
9. verify guest and paid access boundaries; and
10. present clear errors for invalid and unstable models.

## 11. Evidence record

The benchmark runner will emit a machine-readable record containing:

- suite and schema version;
- case ID, title, family, and verified feature;
- reference method and derivation notes;
- exact production model input;
- declared checks and tolerances;
- calculated values, differences, and status;
- equilibrium and conditioning diagnostics;
- test timestamp;
- runtime version;
- application release or Git commit; and
- production solver file hash.

The future public Verification Centre must read this generated evidence. It must
not maintain a second, manually typed copy of calculated results.

Each flagship public case should provide:

- model diagram;
- input table;
- equations or independent reference;
- expected-versus-calculated table;
- acceptance tolerance;
- downloadable model and evidence;
- current release identifier; and
- assumptions and limitations.

## 12. Release gates

The release is blocked when any of the following is true:

- a required benchmark or invariant check fails;
- an expected value lacks an independent derivation or source;
- a numerical difference is unexplained;
- an unstable model returns ordinary results without a clear warning or error;
- a browser result differs from the direct solver result;
- a saved or exported model does not reproduce the same analyzed scenario;
- the public evidence does not identify the tested release;
- a known limitation is hidden or contradicted by marketing copy; or
- a P0 or P1 defect remains unresolved.

The final release record must include a clean test run, browser matrix, known
limitations, release identifier, generated evidence package, and reviewer
sign-off.

## 13. Collaboration checkpoints

1. **Foundation review:** agree on scope, wording, tolerances, and the 25-case
   matrix.
2. **Analytical review:** review the first beam/bar derivations and any solver
   discrepancies.
3. **Independent comparison review:** agree on the external solver and review
   the frame/truss modelling equivalence.
4. **Workflow review:** walk through the browser and PDF release scenarios.
5. **Public evidence review:** approve the Verification Centre language and case
   presentation.
6. **Launch review:** accept or reject the release against the gates above.

## 14. Methodology references

- [ASME V&V 10 — Standard for Verification and Validation in Computational Solid Mechanics](https://www.asme.org/codes-standards/find-codes-standards/standard-for-verification-and-validation-in-computational-solid-mechanics)
- [NASA-STD-7009B — Standard for Models and Simulations](https://standards.nasa.gov/standard/nasa/nasa-std-7009)
- [OpenSees Examples Manual](https://opensees.berkeley.edu/OpenSees/manuals/ExamplesManual/HTML/indexpage.htm)

These references inform the verification approach. Their inclusion does not
represent certification or a claim of formal compliance.