Skip to content

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, t
section = 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"
from xfea.problem import Problem, StaticStep
from 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 mm
print(react.get_result_at(nodes[0]).z) # 1000 N

analyse_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 %.

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 files
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.

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 increment
print(deflection.get_result_at(nodes[-1]).z) # at the end of the step
print(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.

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 arbitrary

The frequencies are in Hz when time is in seconds, as it is with N, mm and tonnes.

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 compression
preload.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 load
  • 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.

  • xfea status output -f in a terminal prints how the solves under output are 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_warnings holds 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