FERS: structural analysis in Python
FERS: structural finite-element analysis (3D frames, trusses, plates, Eurocode 3
checks) for engineers and AI agents. This is its Python SDK and the fers
command. The solver is a compiled engine that runs on your machine, with no
account and no network call: free for non-commercial use up to 100 members.
This SDK is open source (BSD-3-Clause) at
github.com/Jeroen124/FERS_core; the
engine's licence is under Licence.
It computes linear and second-order (P-Delta) static analysis, natural
frequencies, elastic buckling load factors (α_cr), response-spectrum seismic
analysis, and EN 1993-1-1 steel member checks, flexural and lateral-torsional
buckling included. A model is JSON in and JSON out, written from Python, by the
fers command, or by an AI agent through the
FERS MCP server, the Claude Code plugin or the
agent skill.
The sag is 41.3 mm of bending (5wL⁴/384EI) plus 0.4 mm of shear deformation,
which the engine includes. The beam fails: the ULS moment of 60.75 kNm exceeds
its bending resistance of 51.9 kNm, and with nothing restraining its compression
flange, lateral-torsional buckling takes the utilization to 2.85.
- Agents and scripts:
fers solve, fers check and fers validate take a
model JSON file, print one line (or --json) and say in their exit code
whether the numbers can be used; see From the terminal and from coding
agents. fers skill --install .
gives a coding agent the FERS skill, and MCP clients can use the
FERS MCP server. In Claude Code, both come as one
plugin: /plugin install fers --marketplace Jeroen124/FERS_core.
- Extras: plots (
pip install "FERS[plot]"), section properties meshed from
your own dimensions ("FERS[sections]") and DXF import ("FERS[dxf]");
"FERS[all]" installs everything 0.1.x did. Catalogue sections (IPE200,
HEB300, UB 457x191x67, W14X30, ...) need no extra.
- Licence: the SDK is BSD-3-Clause; the engine it installs is free for
non-commercial use (Licence).
Solving a model
Building a model by hand, create the FERS object first, then its nodes,
members and loads. Creating a FERS restarts the id counters, so a node made
before it would share an id with one made after it, and the solver refuses
node ids that do not run from 1 without gaps.
Reading results
run_analysis() puts the results on model.resultsbundle. Load cases and load
combinations are keyed by name. Within each, nodes and members are keyed by
their id as a string, because results round-trip through JSON.
start_node_forces, end_node_forces, maximums and minimums are in the
global frame; the local_* forces, section_forces and internal_force_series
are in the member's own axes, with mz the strong-axis moment. Read a frame's
moments from the local ones: outside the XY plane the global mz is not the
bending moment, and in a frame in the YZ plane it reads 0.
Since 0.1.98, member_results and displacement_nodes are read-only tables
rather than dicts of objects. That is what keeps a large result small in
memory. They read like dicts: [], get, in, len, .items(), and
iteration in the solver's order. Each lookup builds a fresh object, and nothing
in it can be changed:
section_forces, internal_force_series and member_displacements come back
as tuples. To test for a table, use isinstance(x, collections.abc.Mapping),
not dict. reaction_nodes and plate_results are plain dicts, as before.
Saving and loading
FERS.from_json reads any file the solver or the SDK wrote, one entry at a
time. A typical result needs less memory than its file to load, and at most
about twice the file's size; before 0.1.98 it needed 15 to 20 times. For a
large model, let the solver write the file itself. The result then never
passes through Python as one string:
fers_core/examples/809_Reading_Results.py runs all of this end to end.
Saving a loaded model writes back everything the solver reads, with the same
ids. That includes what the file defines but nothing uses yet, such as a section
an editor keeps in its library. Nodes, members and the rest created after
loading get ids the loaded model does not use, so saving never lets a new object
replace a loaded one.
Only the results you read (engine 0.2.68)
AnalysisOptions(result_filter=[...]) keeps or drops whole result blocks.
result_requests goes further. Each ResultRequest names a block and narrows
it to chosen members or nodes, load combinations, components and one member
end:
The values load into the same member_results, displacement_nodes and
reaction_nodes, so code that reads them keeps working. Anything that was not
requested reads as None, not zero. A check that reads a value nobody asked
for therefore fails instead of passing on a zero.
members takes the unity checks' selectors: classification(...),
members([...]), member_sets([...]) and all_members(). Several selectors
form a union.nodes takes nodes([...]), or nodes_of(*selectors) for the end nodes of
the selected members.- Load combinations are matched on their
limit_state, as unity checks match
them, or by load_combination_ids. To select by limit state, set
limit_state on each LoadCombination; the solver does not read situation.
- A request with neither
limit_state nor load_combination_ids also covers
the load cases.
end="start" or end="end" keeps one end of the end-force and
end-displacement blocks.- The solver refuses a request it cannot meet, before it starts. That includes
section_forces, internal_force_series, a component the block does not
have, a limit state no combination carries, and result_filter set as well.
The values themselves are on model.resultsbundle.selections, one entry per
request and group of result sets. Each entry's values is a read-only numpy
array shaped (result_sets, ids, fields, components), with each axis listed
beside it:
save_to_json writes the selections back as the solver wrote them, so a saved
result reloads unchanged. fers_core/examples/810_Result_Requests.py runs this
end to end.
Scissor hinges: a continuous beam that turns on what it crosses (engine 0.2.68)
A rail running over beams and resting on each one is continuous along its
length, but free to turn on every beam. A MemberHinge releases one member end,
so releasing both rail ends at a beam splits the rail into two spans. Put the
rail's members in a member set of their own and give the set a
ScissorHinge instead. No link member or extra node is needed:
- Where it applies: at every node where a member of the set meets a member
outside the set, or a plate. There the set's members stay joined to each
other and move relative to the node along and about the released axes.
Nothing is released where the set meets only itself or a support. So the
continuous beam's members belong in a set of their own; a set holding every
member meets nothing, and the solver refuses it.
- Only some of those nodes:
MemberSet(scissor_hinge_nodes=[...]) lists
where the hinge applies, for a beam that turns on some of the members it
meets and is joined to the rest.
- Each value works as a
MemberHinge release does: None holds it, 0.0
frees it, and a positive value is a spring between the set and the node, in
force per length for a translation (translational_release_x/_y/_z) and
moment per radian for a rotation (rotational_release_x/_y/_z).
- The axes are global unless the hinge names its own:
ScissorHinge(..., axes=ReleaseAxes.user(x=..., y=...)) takes the first axis
along x, the second along y made perpendicular to it, and the third as
their cross product, as a rack turned in plan needs.
- Supports and nodal loads at a released node act on the node, meaning the
members outside the set. A node's reported displacement is theirs. The set's
own motion there is in its members'
local_displacement_start_node and
local_displacement_end_node.
- Two hinged sets crossing with nothing else are each released from the
node, so every axis either one releases is free between them.
- A set of one member gives a release about the hinge's axes at that
member's ends.
- Second order: as with member hinges, a model with scissor hinges takes the
corotational correction only when
NonlinearMethod.COROTATIONAL is named.
A rail that may also slide over its posts frees that translation. Here it slides
over the first post only, so the second takes its share of the pull:
A model that uses scissor hinges is written with schema_version 3, so a solver
older than 0.2.68 refuses it instead of solving every connection as rigid.
Without them, a model is written exactly as before.
fers_core/examples/054_Scissor_Hinge_Rail_On_Beam.py compares the rigid
connection, member hinges, the scissor hinge and a spring, and
fers_core/examples/055_Scissor_Hinge_Sliding_Rail_And_Release_Axes.py slides
the rail, limits the hinge to one post, and turns the rack in plan.
Member hinges in global or user axes (engine 0.2.68)
A MemberHinge releases its rotations about its member's own axes. A beam at an
angle in plan, pinned about the girder it hangs from, needs a pin about the
girder's axis instead, which in the beam's own axes mixes its bending with its
torsion. rotation_axes names the axes the rotational releases, their stiffness
curves and their moment–rotation diagrams use:
ReleaseAxes.LOCAL (the default) keeps the member's axes; ReleaseAxes.user(x, y)
names a frame as above. A curve on such a hinge reads the end moment about the
same axes; the member's results stay in its local axes. Translational releases
stay member-local. A model whose member hinges release in other axes is written
with schema_version 3 as well. Release axes are fixed in space, so a
corotational solve does not turn them with the structure.
A member's self-weight
The solver works out each member's self-weight, density·area·g, and puts it in
the load case that self_weight_load_case_id names. A load combination carries
the self-weight only if it includes that case, so give it your permanent-load
case: create_load_case("G", self_weight=True) creates G and sets both options.
The ULS reactions are 1.5 × 30 kN plus 1.35 × the beam's 2.49 kN. With
enable_self_weight set and no self_weight_load_case_id, the solver puts the
self-weight in a load case of its own, "Self-weight", which combinations built
from your load cases do not include. run_analysis refuses such a model when it
has combinations, rather than solve every one of them without self-weight, and
the solver warns with self_weight_not_in_combinations on each combination. A
model without combinations solves, and its "Self-weight" case is a result of its
own, as below.
The solver also works out each member's mass for modal and seismic analysis from
the section. A member that carries more, such as cladding or a services run, can
override both:
The solver applies 1500 N/m in place of the section's 184 N/m, and takes
1500 / 9.81 kg/m as the member's mass. weight_override is in the model's
force/length units. Member.weight is a different thing: the member's mass as
the SDK computes it, density·area·length, which is never sent to the solver.
Seismic analysis
add_seismic_analysis asks the solver for a modal response-spectrum analysis
(the default), the lateral-force method, or both. The spectrum helpers build
EN 1998-1 design spectra. Accelerations are in m/s² and periods in seconds,
whatever the model's units; nodal masses are in kg.
mass_sources=[(load_case, psi)] turns gravity load cases into seismic mass
(ψE = 1.0 for permanent loads). direct_spectrum takes S, T_B, T_C and T_D
directly for a national annex, and custom_spectrum a table of periods and
accelerations. The results are plain dicts in resultsbundle.seismic, one
entry per method. fers_core/examples/151_Seismic_Response_Spectrum.py runs a
portal frame through both methods.
Unity-check reports
The solver can embed one HTML report of every unity check in the result:
render_unity_reports = True also fills each checked member's
rendered_report from its check's report_template, and adds those narratives
to the HTML report. Both are off by default, which keeps the result small.
Premium solves and timeouts
Without an API key the solver runs at Free-tier limits (100 members) and makes
no network call at all. The free tier is for non-commercial use; commercial
use needs a Pro key at any model size. Passing api_key raises those limits, to
10,000 members with a Pro key and 1,000,000 with an Enterprise one (granted by
agreement):
A key means each solve first verifies the licence with ferscloud.com, so that
handshake is bounded. If the licence server does not answer within
license_timeout seconds (default 30) the call raises FersTimeoutError
before the solve starts — so retrying is always safe:
Keeping those two arms apart is the point: retrying a RuntimeError fails
identically, while collapsing both into except Exception turns a retryable
blip into a lost result. See fers_core/examples/203_Premium_Batch_Solve.py
for the full unattended-batch pattern.
FersTimeoutError subclasses the built-in TimeoutError, so a plain
except TimeoutError catches it too.
Set FERS_LICENSE_TIMEOUT (seconds) to change the default without editing any
call sites. It must be a real environment variable — .env files are not read
by the engine.
license_timeout bounds the licence handshake, not the solve. A solve is
native code with no cancellation point, so no in-process timeout can interrupt
it. For a hard ceiling on total wall time per model, run each solve in a
killable subprocess — that also reclaims its memory.
Requires engine fers_calculations >= 0.2.53.
From the terminal and from coding agents
pip install FERS puts a fers command on the path: a thin layer over the
objects above and the engine, for shells, scripts, CI jobs and coding agents.
Every large output goes to a file; stdout carries one line per command, or a
JSON object with --json.
fers solve sends the file to the engine as it is, and reads the results back
only for its summary line: load cases, combinations, recorded failures,
non-converged result sets and messages. A model that writes hundreds of
megabytes costs this process nothing.
The exit code says whether to use the numbers:
A check that meets several of these exits with the first of 4, 6, 5. With
--json, solve and check add a verdict and its reasons. After "DO NOT
USE these results" comes the reason: the solver's first error, or the error a
load case or combination recorded when it failed outright. fers check names
what governs each check, governing member 4 (Column, HEA300) in "ULS 1" (combination 2), and --json carries the same as governing_entity_label and
governing_combination_name.
FERS_API_KEY supplies the key for Premium limits when --api-key is not
given; without a key the engine runs at Free-tier limits and makes no network
call, as above. --solve-token (or FERS_SOLVE_TOKEN) takes a short-lived
Premium token from FERS Cloud instead, which the engine checks offline: Premium
limits on a machine that cannot reach ferscloud.com. In Python it is
run_analysis(solve_token=...).
For an agent, the skill is the working loop on one page: which route to take
(MCP tools, a shell or code sandbox, or a file for FERS Studio), validate,
solve, check, and the conventions that change answers, with runnable models in
reference/api.md. It ships in the package (fers_core/skills/fers/); fers skill --install . copies it to .claude/skills/fers/, where Claude Code looks,
fers skill --zip fers-skill.zip packs it for upload to Claude.ai, and fers skill --path names SKILL.md for any other agent. MCP clients can
run the same engine as a local MCP server instead (npx -y @ferscloud/fers-mcp,
which solves on the user's machine); clients that cannot start a program use the
hosted server at https://ferscloud.com/api/mcp, which returns a browser-solve
link. Setup for each client: https://ferscloud.com/mcp.
fers_core/examples/811_Command_Line_Workflow.py runs the loop end to end.
Licence
This package, FERS, is open source under the BSD 3-Clause License (LICENSE).
The solver engine it installs, fers_calculations, is licensed separately. From
0.2.70 it is under the PolyForm Strict License 1.0.0: free for any non-commercial
purpose, such as study, teaching, research and hobby projects. Commercial use
needs a paid FERS Cloud plan, which includes the
commercial licence.
