Trusslab user guide: model 3-D frames, trusses and cable nets

Getting started: a first model in two minutes

Open the tool. It starts with a small portal frame (a beam on two fixed columns) so there is something to run straight away.
Press Ctrl+Enter (⌘+Enter on a Mac), or the Run button in the run strip at the bottom. The analysis runs in a background worker; a progress bar and a Cancel button appear for longer runs.
The Results tab opens. Its first block is the sanity panel: equilibrium of loads and reactions, automatically held degrees of freedom and a pivot-ratio hint. Read it before the numbers.
Pick a diagram (N, Vy, Vz, T, My or Mz) in the Results tab to draw it on the members, and use the Deform slider to scale the deflected shape.
Tap or click a member to open the inspector with its six internal-force plots and a station table. Tap a node for its displacements and reaction.
Edit any value in the Ledger tables on the right (Enter or leaving the cell commits it; Escape reverts). Run again. Ctrl+Z undoes any edit.
Save the model file with Ctrl+S. Your work is also autosaved in this browser.

To build a model from scratch: add nodes with N (or + Node) and type their coordinates, select two nodes (Shift adds to the selection) and press M for a member, select support nodes and press S, then add loads with L in the Loads tab. The Examples button opens a gallery of complete models.

The workbench

Model view (centre): a 3-D view drawn with WebGL, or with a 2-D canvas when WebGL is not available (the badge in the top-right corner says which). Members are coloured by kind: frame, truss or cable. Supports are drawn as pyramids (all translations fixed), small plates (partial restraint) and zig-zags (springs). Load arrows show the active load case. Member-load arrows follow the elastic chord after global or local rigid offsets; local load directions use that chord’s axes.
View buttons: Plan (X–Y), X–Z and Y–Z elevations, Iso and Fit. Keys 1–4 select the same views.
Mouse: drag to orbit, right-drag or Shift-drag to pan, wheel to zoom about the cursor, click to select, Shift-click to add to the selection.
Touch: one finger orbits, two fingers pan and pinch to zoom, tap selects. Nothing needs hover.
Keyboard in the view (click it or Tab to it first): arrows orbit, Shift+arrows pan, + and − zoom, F fits.
Ledger (right; a bottom sheet on narrow screens): tabs for Nodes, Members, Sections, Materials, Supports, Loads, Cases & combos and Results. Use Left/Right arrows or Home/End to select a Ledger tab. The row button selects the item in the view; the view selection highlights the row.
Run strip (bottom): analysis kind, the load set to analyse, options (modes, mass, Newton-Raphson steps), the memory estimate, Run/Cancel with progress, diagnostics chips (tap one to select the nodes or members it names), the sanity badge and the headline result.
Inspector: opens over the view for the selected member or node.
Top bar: model name, unit preset, Examples, Open, Save, Export, Undo, Redo, help (?), and links to this Guide and to Verify. A status chip shows whether runs are allowed (see Troubleshooting).

Below 900 px the view takes the full width and the tables open as a bottom sheet with the “Tables & results” button. At phone width the tool is best used to view, run and inspect models; all tables remain available.

Coordinates, local axes and degrees of freedom

Global X, Y, Z are right-handed and Z is up; gravity (self weight) acts along −Z. Each node has six degrees of freedom in the order ux, uy, uz, rx, ry, rz. Rotations are right-hand rotations in radians.

Each member has local axes: x runs from node i to node j. Local y and z come from a reference vector r: y = normalise(r × x), z = x × y. The reference lies in the local x–z plane on the positive z side (it is not the local y axis). With no reference vector, r is global Z, or global X for a (nearly) vertical member. A roll angle α (degrees) then turns y and z about x: y′ = cos α y + sin α z, z′ = −sin α y + cos α z. A reference vector parallel to the member is invalid.

Section properties follow these axes: Iy resists bending in the local x–z plane (deflection along z), Iz bending in the x–y plane. For a formula rectangle, b is along local y and h along local z, so Iy = b h³/12.

Modelling: members, sections, materials and supports

Member kinds

Frame: 3-D beam-column with axial, torsion and bending stiffness. Optional shear areas (Asy, Asz on the section) add shear deformation.
Truss: axial stiffness only. Rotations at a joint that only trusses meet are held automatically and reported in the sanity panel.
Cable: tension only, geometrically nonlinear, solved by Newton-Raphson. Give a pretension (tension at the drawn geometry) or an unstressed length (shorter than the chord means taut). A slack cable carries no force and is reported.
Tension only: a frame or truss member that may carry no compression; it is solved iteratively like a zero-pretension cable.

Releases, offsets and divisions

Releases are six 0/1 digits per end in local u v w rx ry rz order (1 = released). 000011 at an end is a pin about local y and z. Releases are condensed statically; modal mass uses the same displacement transformation before applying offsets. This is a static approximation to released-end dynamics: refine divisions to check convergence. A release set that leaves the member unstable is rejected.
Rigid end offsets run from the node to the elastic end of the member, in global axes unless “Local off.” is ticked. Offsets change the elastic length and its axes. DXF exports node-to-node lines without offsets.
Divisions split a member into equal elements (1–200) so that deflected shapes and buckling or mode shapes curve between the nodes. Internal nodes are created by the engine and do not appear in the Nodes table.

Sections

Type A, Iy, Iz and J yourself (shape “User values”), or choose a formula shape and type its dimensions: solid rectangle (b, h), solid circle (d), circular tube (d, t), rectangular box (b, h, t) or doubly symmetric I (bf, tf, d, tw). The properties are computed from those dimensions. Box torsion uses closed thin-wall theory on the mid-line; the I section has no root fillets and its J excludes warping. Trusslab ships no catalogue of rolled shapes: enter the properties of your own sections.

Materials

E, optional G (otherwise E / (2 (1 + ν))), density ρ for self weight and mass, and optional thermal expansion α. The example material in new models is a set of round illustrative numbers; replace it with your own values.

Supports

Each support row fixes chosen global DOFs (six 0/1 digits: 111111 fixed, 111000 pinned). Optional springs (force/length or moment/radian) replace the fixity of their DOF. Optional settlements prescribe a displacement on fixed DOFs or move the base of a spring. In nonlinear load steps the spring-base contribution ramps with the applied load, reaching the entered settlement at the final step.

Loads, load cases and combinations

Nodal loads: Fx, Fy, Fz, Mx, My, Mz in global axes.
Distributed member loads: force per length at the start (q1) and end (q2, empty for uniform) of a span from a to b, measured from node i along the whole member (empty a/b: the whole member). Components are in global or local axes as chosen.
Point member loads: a force and/or moment at distance “at” from node i, in global or local axes.
Thermal loads: a uniform change ΔT (positive expands the member) and optional gradients across local y and z (temperature per length).
Self weight: the “Self wt ×” multiplier of a case applies ρ A g along −Z on every member (1 = full self weight).
Combinations add cases with your own signed factors, written case:factor, for example DL:1, W:-1. No design-code combinations are built in.

Static and P-Delta runs solve every case and combination separately unless you pick one load set in the run strip. Buckling uses the chosen (or first) load set as the reference load; modal analysis uses it only to pre-stress cables. Cable distributed loads use linear shape functions over the entered loaded interval, preserving force and first moment; divide a cable to resolve its curved loaded shape.

Analyses

Analysis	What it solves	Main results
Static	Linear stiffness method. With cables or tension-only members the solution is Newton-Raphson with load steps.	Displacements, reactions, member diagrams, equilibrium check
P-Delta	Second-order equilibrium including the axial-force (geometric) stiffness.	As static; a warning when the load exceeds a buckling load
Buckling	Linear eigenvalue problem (K + λ Kg) φ = 0 for the reference load set.	Load factors λ and buckling shapes
Modal	Free vibration K φ = ω² M φ with consistent or lumped mass.	Frequencies, periods, shapes, participation and effective mass

After model or analysis edits, a cancellable worker estimates the memory the factorisation, eigen workspace and result tables need and refuses a run above this browser’s budget, with a message that suggests fewer divisions, modes or members. The budget is lower on iPhone and iPad. Editing again cancels an outdated estimate. Before solving, the analysis worker checks the budget again. Long runs show progress; Cancel stops the worker at once.

Mode shapes are scaled to a largest translation of 1. Effective-mass ratios use the total structural mass, including mass at restrained nodes, so cumulative ratios need not reach 1. With prefers-reduced-motion set, mode animation is off by default and, when switched on, steps through a few frames instead of moving smoothly.

Results and sign conventions

Member internal forces are the resultants on the positive local-x cut face of the part from node i to the cut, exerted by the rest of the member:

N: axial force, tension positive, compression negative.
Vy, Vz: shear forces along positive local y and z on that cut face.
T: torque, a right-hand couple about positive local x.
My, Mz: bending moments, right-hand couples about local y and z. Positive My puts the +z fibre in tension; positive Mz puts the −y fibre in tension.
The i and j end values in tables use the same cut-face convention; they are not the node-on-member action vectors (the i end action has the opposite sign).
Reactions are the forces and moments the support exerts on the structure, in global axes.

In the view, Vy diagrams are drawn along local +y, Mz diagrams on the tension side (local −y), and N, T, Vz and My diagrams along local +z (My therefore also on its tension side). Blue is positive and red negative. The deflected shape is magnified by an automatic factor times the Deform slider.

Sanity checks on your model

Equilibrium: the sum of applied loads and reactions, forces and moments about the global origin, per load set. The relative residual must be below 1e-8 (linear) or 1e-5 (nonlinear).
Convergence: for Newton-Raphson runs, the iteration count, final residual and tolerance.
Slack cables: cable members with no tension.
Automatically restrained DOFs: degrees of freedom with no stiffness that the engine held (for example rotations at truss or cable joints), listed by node and DOF. An unexpected entry often means a missing member or support.
Mechanism / small pivot hint: the ratio of the smallest to the largest pivot of the factorisation. It depends on units and scale and is a hint, not a condition number or an acceptance test.
Unit preset: the preset in use and its gravity constant.

Units

Choose a unit preset; inputs and results are in that system and the tool does not convert numbers when you change it (only the labels and the gravity constant change). Time is in seconds.

Preset	Force	Length	Mass	Temperature
kN-m	kN	m	t	°C
N-m	N	m	kg	°C
N-mm	N	mm	t	°C
kip-in	kip	in	kip·s²/in	°F
kip-ft	kip	ft	kip·s²/ft	°F

E and G are force/length², density is mass/length³, A is length², Iy, Iz and J are length⁴, added mass is mass/length, and moments are force × length.

Files, import and export

Model file (.json, format “trusslab-model”, version 1): the whole model in open JSON, with a copyright, terms and professional-use notice. Save with Ctrl+S, open with Ctrl+O. Unsupported versions, nonboolean JSON restraint/release masks and malformed member loads are rejected.
CSV tables: nodes (id,x,y,z,mass), members (id,kind,i,j,material,section,roll,divisions,refx,refy,refz,releaseI,releaseJ,pretension,addedMass,unstressedLength,offsetIx…offsetJz,offsetLocal,tensionOnly,label) and supports (node,fixed,kx…krz,sx…srz). Open a CSV, or use “Paste CSV…” in a table: rows with an existing id replace it, others are added. CSV does not carry materials, loads or combinations.
DXF (ASCII): export writes one LINE per member on layers TRUSSLAB_FRAME, _TRUSS and _CABLE. Import reads LINE and POLYLINE entities as geometry only, merging coincident end points; the layer name sets the member kind. Supports, loads and results are not read from DXF.
Results CSV (Results tab): reactions, member end forces, displacements and modes, each with units.
Pictures: the current view as SVG or PNG, and a print report with sanity checks and result tables (browser print; save as PDF from the print dialog).

Every export carries the line “Made with Trusslab · simulations4all.com” and the professional-use notice. CSV text cells that a spreadsheet might read as formulas are prefixed with an apostrophe. Unicode line and paragraph separators stay inside quoted cells and are collapsed to spaces in comment lines.

Autosave keeps the current model in this browser’s IndexedDB storage. If storage is blocked (some private-browsing modes) small models fall back to local storage; otherwise autosave is off for the tab and the tool says so. Nothing is sent to a server.

Keyboard shortcuts

Key	Action
N	Add a node
M	Add a member between the last two selected nodes
S	Pin the selected nodes
L	Add a nodal load at the selected nodes in the active case
Delete	Delete the selection (with its members, supports and loads)
Ctrl/⌘+Z, Shift+Ctrl/⌘+Z	Undo, redo
Ctrl/⌘+S, Ctrl/⌘+O	Save the model file, open a file
Ctrl/⌘+Enter	Run
1, 2, 3, 4	Plan, X–Z, Y–Z, isometric view
D	Toggle the deformed shape
?	Shortcut help
Esc	Clear the selection or close a dialog

Limitations: what Trusslab does not do

No shell, plate or solid elements: members only.
No design-code member checks, no code load combinations and no code-based section classification.
No catalogue of rolled steel or other standard sections; enter section properties or formula dimensions.
No response-spectrum or time-history analysis; modal results are frequencies and shapes.
No large-displacement (corotational) frame analysis beyond P-Delta; cables are geometrically nonlinear.
No warping torsion, no material nonlinearity, no staged construction.
No proprietary model formats: only its own JSON, CSV tables and ASCII DXF geometry.
Capacity depends on the device: very large models may be refused by the memory pre-check, especially on phones and tablets.

Compared with other tools

Desktop 3-D structural analysis packages typically add shell and plate elements, design-code checks, section catalogues, response-spectrum and time-history analysis, and import of their own model formats. Trusslab covers the member-based core of that work (3-D frames, trusses and cable nets with static, P-Delta, buckling and modal analysis, load cases and combinations) in the browser, with open file formats and a reference suite you can run yourself. Use it for preliminary design and independent checking within the stated limitations.

Troubleshooting

“This tool runs only on simulations4all.com — reconnect to continue”: runs need a short-lived token from simulations4all.com. Offline, the last token keeps working for 24 hours. Editing, opening, saving and this Guide work without it.
Mechanism or many automatically held DOFs: a node or member is not supported against some motion. Check supports, releases (a member released at both ends about the same axis spins freely) and that members meet at shared nodes.
Equilibrium warning: usually a sign of a mechanism or a near-singular model; check the held DOFs and the pivot hint. An unloaded stable model with homogeneous supports has zero equilibrium residual.
A cable net does not converge: increase the Newton-Raphson steps, add pretension, or check that the net is curved (a flat net under transverse load has no initial stiffness).
“No positive buckling load factor”: the reference load puts no member into compression; choose a load set with compression as the base set.
Modal “no mass”: give materials a density, or add nodal or member added mass.
Memory refusal: reduce member divisions, the number of modes, or the model size.
“2-D canvas” badge: WebGL is unavailable or was lost; the fallback draws the same model, more slowly for large models.

How we verify this tool

The solver is checked against closed-form beam, column and vibration theory, section-property integrals, exact file round trips, and models re-solved by a separately written finite-element reference program. The catalogue distinguishes independent derivations from retained same-formula slope-deflection and section checks; those checks also have independent flexibility or energy-integral companion tests. Each case lists what it checks, its reference, citation and applicable tolerance.

The same catalogue drives the automated test suite and the Verify page, where you can run every case in your own browser and print the report. The sanity checks above then test your own model each time it runs.

Professional use and limits

Professional use: Results are for education and preliminary design. They must be checked by a qualified professional and are not a substitute for code-compliant design or licensed engineering judgement. No certification, code compliance or regulatory acceptance is claimed.

Saved model files carry this notice; check it travels with any copy you share.
Verify member forces and displacements independently before using them in a design.

Sources and third-party notices

Trusslab — source and third-party notices

NIST Special Publication 811, Appendix B.8, https://www.nist.gov/pml/special-publication-811/nist-guide-si-appendix-b-conversion-factors/nist-guide-si-appendix-b8 : standard gravity, international inch and international foot exact definitions. Local code derives the preset-unit values; no material/section catalogue or standard load table is reproduced. Credit NIST, retain the non-SRD notice below where its data/work is distributed, and do not imply endorsement. Section properties are computed from user dimensions; validation references are explicit derivations and independently computed numerical values, not copied textbook examples.

three.js is a runtime dependency, MIT, with the complete captured licence below. The ASCII DXF R12 (AC1009) subset is documented in DESIGN.md against the owner-published specification; a format implementation does not license vendor sample files.

NIST non-SRD notice — SP 811 exact unit definitions

This data/work was created by employees of the National Institute of Standards and Technology (NIST), an agency of the Federal Government. Pursuant to title 17 United States Code Section 105, works of NIST employees are not subject to copyright protection in the United States. This data/work may be subject to foreign copyright.

The data/work is provided by NIST as a public service and is expressly provided “AS IS.” NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. NIST does not warrant or make any representations regarding the use of the data or the results thereof, including but not limited to the correctness, accuracy, reliability or usefulness of the data. NIST SHALL NOT BE LIABLE AND YOU HEREBY RELEASE NIST FROM LIABILITY FOR ANY INDIRECT, CONSEQUENTIAL, SPECIAL, OR INCIDENTAL DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, AND THE LIKE), WHETHER ARISING IN TORT, CONTRACT, OR OTHERWISE, ARISING FROM OR RELATING TO THE DATA (OR THE USE OF OR INABILITY TO USE THIS DATA), EVEN IF NIST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

To the extent that NIST may hold copyright in countries other than the United States, you are hereby granted the non-exclusive irrevocable and unconditional right to print, publish, prepare derivative works and distribute the NIST data, in any medium, or authorize others to do so on your behalf, on a royalty-free basis throughout the world.

You may improve, modify, and create derivative works of the data or any portion of the data, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the data and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the data: Data citation recommendations are provided at

https://www.nist.gov/open/license

.

Permission to use this data is contingent upon your acceptance of the terms of this agreement and upon your providing appropriate acknowledgments of NIST’s creation of the data/work.

Direct interface dependencies

These licences apply to the named dependencies, not to original tool code. Actual browser/source distribution must retain applicable bundled/transitive notices; this entry covers the captured direct imports, including owning-batch schema imports.

immer 11.1.4 (MIT)

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: