Analysis
A problem is what happens to a model: its steps, applied in order. Each step has its loads and the results it should keep. One model can have several problems, each solved on its own.
The samples on this page continue from one model, a steel cantilever of twenty beam elements, 2 m long:
from pathlib import Path
from xfea.model import BeamElement, ElasticIsotropic, Model, Node, Part, RectangularSection
model = Model(name="cantilever")steel = ElasticIsotropic(E=210_000, v=0.3, density=7.85e-9) # N, mm, tsection = RectangularSection(w=50, h=100, material=steel)
part = model.add_part(Part(name="beam"))nodes = [part.add_node(Node(xyz=[i * 100.0, 0, 0])) for i in range(21)]beams = [ part.add_element(BeamElement(nodes=[a, b], section=section, orientation=[0, 1, 0])) for a, b in zip(nodes, nodes[1:])]model.add_fix_bc(nodes=[nodes[0]])
output = Path(__file__).resolve().parent / "output"A static step
Section titled “A static step”from xfea.problem import Problem, StaticStepfrom xfea.results import DisplacementFieldResults, ReactionFieldResults
problem = model.add_problem(Problem(name="tip_load"))step = problem.add_step(StaticStep(name="load"))step.add_uniform_forcefield(nodes=[nodes[-1]], z=-1000) # 1 kN down at the tip
disp = DisplacementFieldResults()react = ReactionFieldResults()step.add_field_outputs([disp, react])
problem.analyse_and_extract(path=output)
print(disp.get_result_at(nodes[-1]).z) # -3.04 mmprint(react.get_result_at(nodes[0]).z) # 1000 Nanalyse_and_extract checks the model, has the solver’s input written, runs the solver and reads the results. Ask
for the results before solving: a field that was not requested is not there to read.
By hand the tip moves P L³ / (3 E I) = 3.05 mm. The solver’s twenty beam elements are slightly stiffer than the formula’s beam: the two differ by 0.3 %.
What a solve leaves
Section titled “What a solve leaves”output/├── model.pkl the model, with its problems (to reopen the results later)├── model.json a short summary of the model└── tip_load/ ├── tip_load.<ext> the solver's input file ├── tip_load-results.db the results database (SQLite) ├── run.json, run.jsonl the run record ├── report.html one page: results, convergence, model, warnings └── ... the solver's own filesOptions of a run
Section titled “Options of a run”| Argument | What it does |
|---|---|
path |
The folder for the model’s runs. Each problem gets a folder of its own inside it. |
verbose=True |
Print the solver’s output when it ends (it is always in solver.log). |
cpus=4 |
Solver threads for this run. Without it, settings.SOLVER_THREADS (default 1). |
erase_data=True |
Empty the problem’s folder first, if xfea made it. |
save_model=False |
Do not write model.pkl. |
Nonlinear static steps
Section titled “Nonlinear static steps”A static step is solved in one increment unless something makes it nonlinear: large displacements (nlgeom=True),
contact, one-sided members or springs, a plastic material. The step’s own arguments set how the load is applied:
large = model.add_problem(Problem(name="large_displacements"))push = large.add_step(StaticStep(name="push", nlgeom=True, initial_inc_size=0.1, max_increments=50))push.add_uniform_forcefield(nodes=[nodes[-1]], z=-20_000)
deflection = DisplacementFieldResults()push.add_field_outputs([deflection])large.analyse_and_extract(path=output)
print(deflection.frames_in_step()) # one frame per incrementprint(deflection.get_result_at(nodes[-1]).z) # at the end of the stepprint(deflection.get_result_at(nodes[-1], frame=1).z) # after the first increment| Argument | What it is |
|---|---|
nlgeom |
Solve with geometric nonlinearity: large displacements and rotations. |
initial_inc_size |
The first increment, in step time. Default 1.0: the whole load at once. |
min_inc_size, max_inc_size |
The smallest and the largest increment. The step fails if the solver must cut below the smallest. |
max_increments |
The most increments the solver may take. Default 100. |
time |
The step’s length in step time. Default 1: a load factor here, not seconds. |
Cutbacks that repeat at the same increment point to the model, not the numbers: a mechanism, a missing support.
Natural frequencies
Section titled “Natural frequencies”ModalAnalysis gives the natural frequencies and the mode shapes. The materials need a density.
from xfea.problem import ModalAnalysis
vibration = model.add_problem(Problem(name="vibration"))modal = vibration.add_step(ModalAnalysis(modes=3))vibration.analyse_and_extract(path=output)
for number, frequency in enumerate(modal.frequencies, start=1): print(f"mode {number}: {frequency:.2f} Hz")
shape = modal.mode_shape(1)print(shape.get_result_at(nodes[-1]).vector) # read like a displacement field; its scale is arbitraryThe frequencies are in Hz when time is in seconds, as it is with N, mm and tonnes.
Buckling
Section titled “Buckling”BucklingAnalysis follows a static step that carries the loads. Each mode’s factor is the multiple of those loads at
which the structure buckles.
from xfea.problem import BucklingAnalysis
stability = model.add_problem(Problem(name="stability"))preload = stability.add_step(StaticStep(name="preload"))preload.add_uniform_forcefield(nodes=[nodes[-1]], x=-1000) # 1 kN of compressionpreload.add_field_outputs([DisplacementFieldResults()])
buckling = stability.add_step(BucklingAnalysis(modes=2))stability.analyse_and_extract(path=output)
print(buckling.mode_factor(1)) # times 1 kN: the first critical loadOther steps
Section titled “Other steps”HeatTransferStep: temperatures in the model from prescribed temperatures and exchanges, transient or steady.DynamicStep: loads that vary in time, with the model’s inertia.
Both are in the API reference.
Following a run
Section titled “Following a run”xfea status output -fin a terminal prints how the solves underoutputare going, until they end.problem.run_record()["progress"]is the same as a dict: the status, the time, the increments done and cut back.problem.solver_warningsholds what the solver warned about.problem.record_result("tip deflection", -3.04, "mm", note="L/250 = 8 mm")keeps a number that answers the question in the run record and the report.
© 2026 Francesco Ranaudo · Text and pictures CC BY 4.0 · Code Elastic License 2.0 · how to reuse them