PyCBA 1.0.1 — a complete continuous-beam toolkit

🎉 PyCBA 1.0.1 — a complete continuous‑beam toolkit

PyCBA reaches 1.0 — and rather than just the delta since 0.9, these notes set out the whole capability, because the library has grown enormously through a rapid run of releases since 0.6.

PyCBA is a focused, dependable 1‑D continuous‑beam engine for the design, assessment and teaching of buildings and bridges: matrix‑stiffness accurate, light on dependencies (just numpy / scipy / matplotlib), and deliberately not a general 2‑D/3‑D FE tool. At 1.0 it spans linear and nonlinear statics, moving‑load bridge assessment, free‑vibration dynamics, prestress, and a rich, publication‑ready visualisation layer.

---

🧱 Modelling & analysis

• Continuous beams by the matrix (direct) stiffness method, any number of spans / members.
• Supports: pin, roller, encastré, guided, vertical spring and rotational spring — via the low‑level restraint vector or the friendly supports=["pin", "roller", …] API.
• Prescribed displacements / support settlements (D=).
• Internal moment releases (hinges) per member.
• Pre‑solve stability / mechanism detection.
• Full reaction recovery — vertical, moment and spring forces — reported and plotted.

🧩 Element library

• Euler–Bernoulli prismatic elements (the exact default).
• Timoshenko shear‑deformable elements (opt‑in via GAv).
• Non‑prismatic (variable‑EI) members — SectionEI from const / linear / pwl / poly segments, integrated exactly.
• Beam on a Winkler (elastic) foundation (kf) — a statically‑condensed super‑element, validated against Hetényi.

🏋️ Loads

• UDL, point, partial‑UDL, trapezoidal (linearly varying) and moment loads.
• Imposed‑curvature (initial‑strain) loads for creep, shrinkage and thermal effects.
• Load cases & combinations, patterned UDLs, and envelope/superposition utilities.

🌉 Bridges & moving loads

• Vehicle traversal with influence lines and envelopes (Mmax/Mmin/Vmax/Vmin), with traverse‑range control.
• Coincident load effects (e.g. the shear coexisting with peak moment) and envelope arithmetic (sum, augment).
• Code load models — road & rail, from six nations. VehicleLibrary grouped by region (AU / US / EU / UK / CA / CN): AASHTO HL‑93, Eurocode LM1 / LM71, BS 5400 / CS 454 HB, CSA CL‑625, China JTG, AREA Cooper E, AS 5100 M1600/S1600/A160/W80/300LA, and the historical NAASRA T44 / MS18.
• Moving lane UDL with clearance zones, and shear points / critical shear (dv) for code assessment.

💥 Nonlinear & dynamics

• Elasto‑plastic (plastic‑hinge) analysis to collapse — static and moving load — with hinge tracking, mechanism detection, and a plot_collapse() mechanism diagram.
• Free‑vibration (modal) analysis — natural frequencies, periods and mode shapes (validated to < 0.1 % against the classical cases).

🔗 Prestress

• A post‑tensioning preprocessor that converts tendon profiles to equivalent loads.

📊 Visualisation

• Beam & load schematics in matplotlib and publication‑quality TikZ / stanli (.tex → PDF).
• Result diagrams — bending moment / shear / deflection (shaded, sagging‑positive), individual or combined, with a reactions panel; plus reaction, coincident‑effects, mode‑shape, collapse‑mechanism and vehicle plots.
• Interactive Plotly backend — hover any section to read M, V and deflection together.
• Display unit systems — relabel for SI / US / N·mm without touching the analysis.

⚡ Results & ergonomics

• Point queries at(x); exports to_dataframe() / to_csv().
• Consistent member terminology; the friendly supports= API; clear, actionable errors.

✅ Quality

Validated against closed‑form solutions throughout (Hetényi, classical modal frequencies, plastic‑collapse virtual work, …), with 370+ tests and a dozen worked‑example tutorials.

---

⚠️ Breaking changes (1.0 clean‑ups)

Both keep deprecated aliases, so most existing code is unaffected:

• i_span → i_member on the load‑add methods — positional calls (ba.add_udl(1, 10)) are unchanged; only the i_span= keyword is renamed. no_spans / add_span retained as aliases.
• VehicleLibrary accessors move under region namespaces — VehicleLibrary.AU.get_m1600(6.25) (and the new AU.get_300la(…)).

📄 Licence — now AGPL‑3.0

As of 1.0, PyCBA is licensed under the GNU Affero General Public License v3.0 (previously Apache 2.0). You remain free to use PyCBA for any purpose, including commercial and professional work — but software that incorporates it, whether distributed or offered over a network (SaaS), must in turn be released under the AGPL. This keeps PyCBA open while preventing proprietary appropriation.

📦 Install / upgrade

pip install --upgrade pycba
pip install "pycba[plotly]"   # optional interactive plots

Python 3.9+. Core dependencies remain just numpy, scipy and matplotlib.

---

Full changelog: https://github.com/ccaprani/pycba/blob/main/CHANGELOG.md · compare: v0.6.0...v1.0.1
Docs & tutorials: https://ccaprani.github.io/pycba/

Thank you to everyone who has used, taught with, and contributed to PyCBA on the road to 1.0. 🚀

v0.9.0

What’s Changed

• Format Python code with psf/black push (#155) @github-actions[bot]
• bump version to v0.9.0 (#156) @ccaprani
• Post-tensioning preprocessor + plotting and docs overhaul (#154) @ccaprani
• docs: tutorial coverage for MemberType + reaction extremes (#152 follow-up) (#153) @ccaprani
• MemberType enum + reaction-envelope extremes (#152) @ccaprani
• Smoother LoadCase / Combination / Envelopes ergonomics (#151) @ccaprani
• Expand the Theory documentation with references (#150) @ccaprani
• Detect mechanisms with a stability check before solving (#149) @ccaprani
• Display unit systems for plot labels (#148) @ccaprani
• Plotting ergonomics + vehicle-on-bridge schematic & animation (#147) @ccaprani
• Add beam & loading schematic rendering (matplotlib + TikZ/stanli) (#146) @ccaprani
• Add patterned UDL load combinations (#145) @ccaprani
• Add LoadCases collection workflow (#143) @ccaprani
• Format Python code with psf/black push (#141) @github-actions[bot]
• Bump codecov/codecov-action from 4.5.0 to 7.0.0 (#138) @dependabot[bot]
• Bump peter-evans/create-pull-request from 6.1.0 to 8.1.1 (#135) @dependabot[bot]
• Bump release-drafter/release-drafter from 6 to 7 (#132) @dependabot[bot]

Full Changelog: v0.8.0...v0.9.0

v0.8.0

What’s Changed

• Nonlinear (elasto-plastic) beam analysis (NonlinearBeamAnalysis) — #140
• Non-prismatic (variable-EI) elements (SectionEI) — #139
• Imposed-curvature (initial-strain) loads (add_ic, load type 6) — #139
• plus Markdown (MyST) documentation migration

Verification

• Full suite: 117 passed (incl. the new test_rejects_nonprismatic_member).
• Docs build warning-free; the prismatic-only note renders correctly in the nonlinear tutorial.

v0.7.0

v0.7.0

Features

Trapezoidal (linearly varying) distributed load (#101)

New load type 5 supports linearly varying distributed loads. Full-span form [span, 5, w1, w2] applies intensity w1 at the left end varying to w2 at the right. Partial form [span, 5, w1, w2, a, c] applies the load starting at position a over cover length c. A convenience method BeamAnalysis.add_trap() is also provided.

Coincident load effects on envelopes (#122)

When computing envelopes from a moving vehicle analysis, the co-existing value of the other effect (V or M) at the truck position that caused each envelope extreme is now tracked. New Envelopes attributes: Vco_Mmax, Vco_Mmin, Mco_Vmax, Mco_Vmin. The critical_values() output now includes "Vco" and "Mco" keys. Coincident values are preserved through augment() and zero_like().

Envelope addition (#92)

New Envelopes.sum() method for element-wise addition of compatible envelopes, enabling superposition of load effects from different sources (e.g. patterned UDL + moving vehicle envelopes).

Vehicle traverse range control (#53)

New pos_start and pos_end parameters on BridgeAnalysis.run_vehicle() restrict the vehicle traverse to a specified range. Useful for transverse deck analyses where the vehicle is confined to specific lanes.

Bug Fixes

Influence line IndexError (#89)

Fixed InfluenceLines.get_il() raising IndexError when the point of interest does not fall exactly on the result grid. Root cause was overly tight floating-point tolerance and zero-valued padding indices at span boundaries.

What’s Changed

• Format Python code with psf/black push (#129) @github-actions[bot]
• Add coincident load effects to Envelopes (#128) @ccaprani
• Add trapezoidal (linearly varying) distributed load type (#127) @ccaprani
• Add pos_start/pos_end to BridgeAnalysis.run_vehicle() (#126) @ccaprani
• Add Envelopes.sum() for element-wise envelope addition (#125) @ccaprani
• Fix InfluenceLines.get_il() IndexError for arbitrary poi values (#124) @ccaprani

v0.6.0

v0.6.0 — Release Notes

New Features

• Prescribed displacements: Support for imposing known displacements at any DOF, enabling modelling of support settlements. Specify via the D argument to BeamAnalysis.
• Spring support reactions: Spring forces are now reported in beam_results.Rs (upward positive, i.e. -k_s × u).

Bug Fixes

• Load superposition: Fixed MemberResults.__add__ which was incorrectly accumulating shear (V) instead of rotation (R) when superimposing load cases.
• Spring stiffness double-counting: Fixed a bug where spring stiffness was being added to the global stiffness matrix twice, giving incorrect results for spring-supported beams.
• Spring reaction sign: Spring forces in beam_results.Rs are now reported with correct sign (upward positive).

Improvements

• Theory documentation: Expanded theory.ipynb to cover global stiffness matrix assembly, spring supports, boundary condition enforcement, prescribed displacements, and reaction recovery.
• Type definitions: Shared types (LoadType, LoadMatrix, LoadCNL, MemberResults) consolidated into types.py; explicit API exports replace wildcard imports.
• CI: Dropped Python 3.8 support; added Python 3.12 and 3.13 to the test matrix. Minimum supported version is now Python 3.9.
• Docs build: Replaced the unmaintained ammaraskar/sphinx-action with a native build step, fixing the GitHub Pages deployment.

Full Changelog: v0.5.2...v0.6.0

v0.5.2

What's Changed

• Added some theory docs by @ccaprani in #83
• Minor fix for plot envelopes by @RoccoRaimo in #90
• Upgrade scipy to cumulative_trapezoidal by @ccaprani in #100

New Contributors

• @RoccoRaimo made their first contribution in #90

Full Changelog: v0.5.1...v0.5.2

v0.5.1

What's Changed

• Added some theory docs by @ccaprani in #83
• Fix deflections for etype 3 and 4 by @ccaprani in #80
• Format Python code with psf/black push by @github-actions in #78

v0.5

What’s Changed

• Deflection shape fixes for all element types (#77) @ccaprani
• corrected released end forces for etype=3 (Pinned-Fixed) (#75) @tpanagiotakos
• Format Python code with psf/black push (#74) @github-actions
• Bump codecov/codecov-action from 4.1.0 to 4.1.1 (#76) @dependabot

v0.4.2

What’s Changed

• Fix for returning IL of vertical support near the POI (#73) @ccaprani

v0.4.1

What’s Changed

• CS454 Additions (#68) @ccaprani
• Added and example to Envelopes notebook (#55) @AlexGriffiths526
• Add example to Envelopes (#57) @ccaprani
• Format Python code with psf/black push (#52) @github-actions