TorsoCAE Documentation

What is TorsoCAE?

TorsoCAE is a browser-based CAD pre-processor and multi-physics simulation platform. Upload a STEP / IGES / BREP file, visualise it in 3-D, apply geometry edits, build CSG bodies, generate a mesh, assign boundary conditions, and run a structural, thermal, CFD, FSI, or contact-mechanics solve — all from a single web page, on CPU or GPU.

Solver under the hood: OCCT 7.9.3 for CAD, Gmsh (plus structured/octree mesh-first paths) for meshing, and a choice of three FEM backends — DOLFINx/PETSc, Kratos Multiphysics, or MFEM — behind one shared physics/BC/solver contract. Assembled linear systems can also be routed to the remote TorsoHPC compute service instead of solving locally.

Three ways to drive it: point-and-click in the browser, replay a recorded Python journal, or ask Sesame, the built-in AI CAE expert. All three paths produce identical state.

Three Workflows

Every state-changing action has three independent entry points. They all hit the same registries and produce the same end-state.

The Manual UI is the reference path. Journal codegen and AI tools are derived from it, so anything you can do manually can be replayed or asked for.

CAD Import & Edit

Drop a STEP / IGES / BREP / STL / OBJ / GLB file into the upload zone, or paste a server-relative path into the AI assistant ("import cadex/tumbler.step").

Edit operations

• Heal Geometry — repairs gaps, sliver faces, missing topology. Run this first on imported CAD before any other edit.
• Merge Smooth — dissolves edges between smoothly-curved faces within an angle tolerance.
• Fuse Geometry — fuses selected faces that lie on the same underlying surface (planes, cylinders, cones, spheres, tori).
• Split by Size — cuts faces larger than a threshold with axis-aligned planes; useful before meshing very large flat regions.
• Split at Bends — inserts boundaries wherever adjacent faces exceed the bend angle; recovers feature edges after a healing/merge that was too aggressive.

Edits chain: each edit produces a new STEP that becomes the input to the next edit. The original upload is never modified.

CSG Bodies

Constructive Solid Geometry runs as a separate workflow from file import. Build geometry from primitives + boolean operations, transform individual bodies, then mesh whichever body you care about.

Primitives

cx / cy / cz are viewer-space coords; the OCCT axis remap is handled internally so what you type matches what you see.

Extrude profiles

• Polygon — sides, radius
• I-section — H, B, tw, tf
• NACA airfoil — 4-digit series + chord

All extrudes accept length and draft (degrees, ±45).

Boolean ops

• Union  A ∪ B — merge two bodies
• Cut    A − B — subtract B from A
• Intersect  A ∩ B — keep overlap only

Transforms (in-place edit)

Translate, rotate, mirror, scale (uniform), or stretch (non-uniform) any body. The body's identity is preserved across transforms — see Body Identity.

Body Identity — body_id vs job_id

CSG bodies have two distinct identifiers. Knowing the difference avoids the most common confusion when reading journals or scripting.

Example: a journal that creates a box, translates it, then rotates it looks like this — note the body_0 reference is reused, not a new UUID per line:

session.csg_make_shape("box", {"dx": 10, "dy": 10, "dz": 10}, name="Box", body_id="body_0")
session.csg_transform("body_0", "translate", {"tx": 5, "ty": 0, "tz": 0})
session.csg_transform("body_0", "rotate",    {"ax": 0, "ay": 0, "az": 1, "angle_deg": 45})

Meshing

Pick an algorithm, set a size factor, click Mesh. The body selector determines which CSG body or imported solid is meshed.

Size factor

Multiplier on Gmsh's automatic mesh size. 1.0 = default, 0.5 = roughly twice as fine, 2.0 = roughly twice as coarse. min_size / max_size override absolute bounds (leave blank for auto).

Algorithms

See the algorithm reference for full details. Quick guide:

• Delaunay — default tetrahedral mesher, general purpose.
• HXT — fastest tet mesher (parallel). Use for large parts.
• Frontal — slower than Delaunay but produces higher-quality tets.
• Hex-Dominant — mixed hex / tet (~80% hexes by element count on box-like geometry).
• Hex-Transfinite — pure all-hex structured mesh. Only works on box-like volumes (6 faces, 4 edges each); silently skipped on others.

Element order

Order 1 = linear elements (Tet4, Hex8). Order 2 = quadratic (Tet10, Hex20). Quadratic is more accurate for stress concentrations but ~8× more nodes.

Mesh-first (no CAD required)

Two additional mesh algorithms build a mesh object directly, without a CAD body:

• Structured Hex8 — block-structured all-hex grid over a Cartesian, cylindrical, or spherical domain (bounds + divisions per axis). Only valid for logically block-structured smooth maps — channels, boxes, annular/cylindrical sectors, spherical shells away from the poles.
• Octree Cut — voxelized Cartesian Hex8 mesh from analytic implicit geometry (sphere/box/cylinder + CSG union/intersection/difference) or CAD-tagged geometry. Every leaf cell refines uniformly to max_level; boundary quads are real Hex8 faces tagged by nearest-surface lookup, so this is a conforming, body-fitted mesh usable by normal solvers (structural, thermal, CFD, MFEM) — not a CutFEM/embedded-boundary mesh. Geometry is a voxelized/staircase approximation of the true boundary, not exact BREP conformance.

Both register through the same mesh-payload contract as CAD-derived meshes — they appear in the Components panel, mesh dropdown, and material volume list identically.

Mesh Edits

Once a mesh exists, geometric mesh editing operates on the patch data directly without re-meshing the CAD.

• Translate / Rotate / Mirror — rigid-body transforms of the whole mesh.
• Copy, Mirror-Copy — duplicate the mesh in place; the copy becomes the new active mesh, original is preserved.
• Move Node — drag a single mesh node to a new position.
• Morph — Laplacian or RBF deformation with per-tag boundary conditions (fixed, constant displacement, or per-vertex prescribed).

All coordinates are in viewer space; the mesh editor handles the Gmsh-local conversion.

Boundary Conditions & Materials

Selection

Click a face in the viewport to select it (becomes a surface tag). Shift-click to add multiple. Selected faces show in the BC panel on the right.

Surface groups

Group multiple faces under a single name (Group Surfaces) so a single BC entry covers all of them. Useful when a logical surface was split into multiple faces by a CAD edit. Groups can be renamed or deleted from the tree.

BC types

For geometric nonlinear static, geometric nonlinear dynamics, and flexible multibody dynamics, structural traction and pressure conditions expose Follower Load. A follower traction rotates with the deformed surface while retaining its prescribed magnitude; follower pressure acts on the current normal and current area. Both backends include the corresponding load stiffness in the Newton tangent. Leave the option off for the original dead-load behavior.

Expression-enabled condition values may use x, y, z, t, geometry bounds such as xmin/xmax, radial coordinate r, pi, and sin, cos, tan, exp, log, sqrt, and abs. Components may mix numbers and expressions, for example [0, "-1.5e7*sin(pi*t)", 0]. Use ** for powers. Expression availability follows the selected BC and backend; unrelated material, solver, and geometry parameters remain numeric.

Volume Conditions

Per-solid volume conditions are selected by physics/submodel and are replayed through journals and Sesame. Structural models use Young's modulus E (Pa), Poisson ratio ν, density ρ, optional gravity acceleration gravity_x/y/z (m/s²), and optional explicit body-force density body_force_x/y/z (N/m³). The solver applies ρ * gravity + body_force over the assigned volume; surface loads remain traction or pressure boundary conditions.

Hyperelastic volumes also take Arruda-Boyce λm or Ogden α. Thermal volumes use conductivity k (W/m·K), specific heat cp, and density ρ; thermoelastic adds expansion coefficient α and reference temperature. Incompressible CFD uses viscosity μ (Pa·s) and density ρ. Compressible Euler uses density ρ, pressure, γ, and initial velocity components.

Physics, Backends & Solve

Pick a physics model, a submodel, and a numerics backend, then click Compute. Results stream into the right panel as soon as the solver finishes.

Physics & submodels

• Structural — linear_elastic, modal_analysis, geometric_nonlinear (static total-Lagrangian large deformation), geometric_nonlinear_dynamics (DOLFINx or MFEM Newton transient), flexible_multibody_dynamics (RBE2-backed flexible bodies and lower-pair joints), structural_dynamics (linear transient), hyperelastic-arruda-boyce, hyperelastic-ogden, contact_mechanics (see Contact Mechanics). Structural transient solvers share Newmark, HHT-alpha, and generalized-alpha integration. Outputs: displacement field, von Mises stress, principal stresses (P1 / P2 / P3 with min & max).
• Thermal — thermal_only (steady-state conduction) and thermal_stress (thermoelastic coupling via α and reference temperature). Outputs: temperature field, heat-flux magnitude.
• CFD — stokes, laminar_flow, rans_k_omega_sst, conjugate_heat_transfer, compressible_flow, fluid_structure_interaction. See CFD and FSI.

Numerics backend

Each physics/submodel routes to one of three backend adapters, selected independently of physics:

Solver options

algo selects the linear solver: auto (recommended default), direct, cg, gmres, bicgstab, bcgsl, or a remote torsohpc-* option (see TorsoHPC Remote Solve). precond selects the preconditioner (jacobi, gamg, ilu, schur for mixed velocity/pressure systems). device selects cpu (default) or gpu for the assembler's fixed-sparsity CSR value-refill in Newton/timestep reassembly loops — GPU requires a build with CUDA support and fails clearly rather than silently falling back to CPU if unavailable.

Modal analysis

submodel="modal_analysis" assembles sparse stiffness/mass operators and solves Kx = λMx through the library-neutral eigensolver layer. The default eigen_solver="feast" uses oneMKL FEAST via TorsoHPC; it is MKL-threaded over one complete CSR matrix and requires an interval, supplied as eigen_interval_max/emax or a modal cutoff max_frequency_hz. FEAST is not treated as a distributed PETSc/DCSR eigensolver in TorsoCAE, so MPI modal runs fail clearly instead of silently gathering to one rank.

Flexible multibody dynamics

submodel="flexible_multibody_dynamics" uses the existing finite-rotation RBE2 reduction for flexible-body attachment frames and enforces the joint graph through a PETSc KKT system solved by Torso's shared linear-solver layer. Configure frames, flexible bodies, surface attachments, lower-pair joints, KKT augmentation, and projection with the journal/API set_flexible_multibody(...) helper or the equivalent nested flexible_multibody model option. Fixed, spherical, revolute, prismatic, cylindrical, planar, and screw joints are supported. Converged steps project position, velocity, and acceleration constraints and return named joint reactions.

The current milestone requires every non-ground frame to have one RBE2 surface attachment and all flexible bodies to share one mesh. Rigid primal bodies, universal/sliding joints, and multi-mesh body assembly fail explicitly instead of silently using an approximate model.

Visualisation

Toggle field overlays directly on the meshed body: structural displacement/stress, thermal temperature/heat flux, CFD velocity/pressure, and SST turbulence scalars when available. CFD results can overlay speed-colored streamlines and animated tracer particles; tracers follow the same computed, frame-aligned flow paths and can be shown with or without the streamline tubes. Use the deformation slider to scale displacement visualisation. Download the raw .npz for offline post-processing.

Python journals can call plot_result(field, ...) to write the current exterior result or a crossed-cell section as PNG, SVG, or PDF. Use smooth=True for the same nodal-recovered whole-result plot as the Post UI. Supply normal=[nx,ny,nz] and constant for an unsmoothed section plane; optional controls include filename (default default.png), deform_scale, vector_glyphs, and title. Sesame exposes the same operation through export_result_plot.

Report expressions

Reports evaluate result expressions directly; they are not limited to the Calculator. Available variables depend on the result and are returned with each report. Common names include coordinates x/y/z, structural fields disp_x/y/z, disp_mag, von_mises, p1/p2/p3, thermal temperature, and CFD u_x/u_y/u_z, vel_mag, and pressure. Expressions support arithmetic, comparisons, **, trigonometric and hyperbolic functions, exponentials/logarithms, sqrt, abs, where, clip, minimum/maximum, and constants pi/e. For example: sin(pi*x/10)*von_mises or sqrt(disp_x**2 + disp_y**2 + disp_z**2).

CFD

Set physics="cfd" with one of the CFD submodels. Incompressible flow (stokes, laminar_flow, conjugate_heat_transfer) runs on the DOLFINx or MFEM backend where implemented; rans_k_omega_sst runs on DOLFINx and MFEM; compressible_flow (inviscid Euler) is MFEM-only.

• Laminar flow — incompressible Navier-Stokes, mixed velocity/pressure formulation. Assign mu/rho on the fluid volume, and inlet_velocity/outlet_pressure/wall/symmetry boundaries. Mixed saddle-point systems solve best with a direct solver or bcgsl/gmres with schur preconditioning — not plain CG.
• RANS k-omega SST — transient incompressible turbulent flow on DOLFINx or MFEM. Assign only physical fluid material properties (mu/rho) on the fluid volume. Set turbulence initialization through model options: turbulence_intensity, optional turbulence_length_scale or turbulent_viscosity_ratio, and wall_treatment="wall_function". These are model physics defaults, not solver options and not material fields.
• SST outputs — in addition to velocity and pressure, SST results expose Turbulent Kinetic Energy, Specific Dissipation Rate, and Eddy Viscosity as normal scalar fields for post-processing.
• Conjugate heat transfer (CHT) — couples the laminar-flow solve with a scalar thermal solve across a shared fluid/solid interface.
• Compressible flow — inviscid Euler, MFEM only. Assign rho, pressure, gamma, and initial velocity on the fluid volume; use farfield/inlet_velocity/outlet_pressure state boundaries (no wall/no-slip flux is implemented for this submodel).

Fluid-Structure Interaction

Set physics="cfd", submodel="fluid_structure_interaction", and a backend — dolfinx (serial or MPI) or mfem (serial only). FSI uses one fluid mesh and one structural mesh, partitioned coupling (ALE mesh motion, IQN-ILS or Aitken relaxation, a Newmark interface predictor, conservative surface field transfer, and adaptive substepping), regardless of backend.

• Mark each mesh's role with Set Mesh Role (fluid or structure) before computing.
• Assign matching interface_boundary BCs on both sides with the same interface_id, side=fluid|structure, and bc_physics=cfd|structural.
• Coupling controls (relaxation, mesh motion, predictor, substepping, per-constituent linear solvers) live in a dedicated FSI options panel — never in the general solver options, which only control run execution and time-integration numerics (n_cores, num_steps, dt, Newmark-beta parameters).
• Structural response defaults to geometric_nonlinear (total-Lagrangian Saint Venant-Kirchhoff); use linear only for small-deflection cases.

Contact Mechanics

Set physics="structural", submodel="contact_mechanics", backend="kratos". Uses an Augmented Lagrangian Method (ALM) mortar contact formulation.

• Assign contact_slave and contact_master BCs on the two candidate contact surfaces.
• Contact formulation controls (penalty, search factor, interior-point/CG tolerances, linear solver) live in a dedicated contact options panel, separate from general solver options.
• Friction/tangential-damping coefficients are assigned on the contact boundary condition itself, not in the contact options panel.
• RBE2 is not available under the Kratos backend, so combining RBE2 with contact_mechanics in a single run is not currently supported.

TorsoHPC Remote Solve

Instead of solving locally, route the assembled linear system to the TorsoHPC compute service by picking a torsohpc-* solver algo: torsohpc-pardiso, torsohpc-amgcl, torsohpc-blaze, or torsohpc-lapack.

• For a single-core run, the complete matrix and RHS are sent as one payload.
• For an MPI-parallel run (n_cores > 1), only torsohpc-pardiso and torsohpc-amgcl support distributed solves — each rank sends its own owned-row shard (DCSR); torsohpc-blaze and torsohpc-lapack remain serial-only from TorsoCAE.
• Modal eigen_solver="feast" also uses TorsoHPC, but it is a separate oneMKL FEAST eigensolver path: thread-parallel, interval-based, and currently single complete CSR payload only.
• Connection settings resolve from environment variables, falling back to the TorsoHPC service's own config — no per-run credentials needed in the journal.
• AMGCL preconditioner choice matters: for vector (elasticity) systems, prefer ilu for robustness — the default AMG/Jacobi options can converge poorly on bending-dominated problems since the remote near-nullspace basis is translation-only (no rigid-body rotation modes), unlike local PETSc GAMG.

PINNs Solver

Physics-Informed Neural Networks (PINNs) provide a differentiable approach to simulation. By training a neural network to minimize PDE residuals, PINNs can approximate solutions to partial differential equations efficiently.

Usage

Select PINN (e.g., PhysicsNemo) as the physics backend in the solver panel to enable. Training parameters must be defined:

• Epochs: Training iterations (default 10000)
• Learning Rate: Optimizer step size (default 1e-3)
• Collocation Points: Number of points for PDE residuals evaluation (default 20000)

Example (Python)

session.set_solver_options(
    backend="physicsnemo",
    pinn_epochs=5000,
    pinn_learning_rate=1e-4,
    pinn_collocation_points=10000
)
session.compute(physics="structural", submodel="linear_elastic")

Journal Scripting

Every action you take in the browser is recorded as one line of Python. Save the journal and you have a reproducible script.

Recording

Recording is automatic — the journal panel shows entries as they accumulate. Click Save Journal to write it to journals/journal_<timestamp>.py.

Playback

Click Play Journal, pick a file. The browser clears, then re-runs every action with the UI updating in real time. Playback uses the same registry mutations as Manual UI, so the end-state is identical.

The script

from torsocae_api import TorsoCAESession

session = TorsoCAESession()
session.upload("part.step")
session.edit("merge-smooth", {"angle_deg": 30})
session.mesh(algo_id="hxt", size_factor=1.0, dim=3)
session.surface(3).bc("fixed")
session.surface(7).bc("traction", values=[0, 0, -1000])
session.solid("Body_1").material(E=210e9, nu=0.3)
session.compute()

Pure CSG session:

session.csg_make_shape("box",      {"dx":10, "dy":10, "dz":10}, name="Box",  body_id="body_0")
session.csg_make_shape("cylinder", {"r":3,  "h":12},            name="Hole", body_id="body_1")
session.csg_boolean("cut", "body_0", "body_1", name="Box - Hole", body_id="body_2")
session.csg_transform("body_2", "rotate", {"ax":1,"ay":0,"az":0,"angle_deg":90})
session.mesh(algo_id="delaunay", size_factor=0.5, dim=3)

Journals run anywhere Python and the server's dependencies are installed — they're not tied to the browser.

Sweeps & Surrogates

Sweep a model over parameter ranges with the FEM/CFD solvers, then train a neural surrogate (PhysicsNeMo Transolver) on the collected fields. A trained surrogate predicts full nodal solution fields for new parameter values in milliseconds — instant what-if exploration from a handful of real solves.

Sweep & train

from sweep import ParameterSweep
import surrogate

sweep = ParameterSweep("bracket_v1", params={"load": (2e5, 2e6), "height": (0.6, 1.4)})
for s in sweep.samples(8, method="lhs", seed=42):   # lhs | random | grid
    session = build_and_solve(s)                     # any normal session/compute journal
    sweep.record(s, result, mesh_data=session.mesh_data())
sweep.finalize()

surrogate.run_training("bracket_v1", job_id="train_0",
                       surrogate_epochs=300, surrogate_seed=7)

Instant prediction

pred = surrogate.run_inference("bracket_v1", {"load": 1.1e6, "height": 1.0},
                               job_id="pred_0")
pred["max_displacement"], pred["infer_seconds"]   # npz + viewer viz also produced

Active learning

Instead of a dense grid, let an ensemble pick the most informative next runs:

next_pts = surrogate.run_suggestion("bracket_v1", n=2)["suggestions"]
# solve those, sweep.record(...) each, re-run training
sweep = ParameterSweep.resume("bracket_v1")

Fields are auto-detected from the solver output (displacement, von Mises, temperature, velocity, pressure). Datasets and checkpoints live in data/surrogates/<name>/.

In the app

The Neural Inference tab lists every trained dataset with one slider per swept parameter — drag for an instant prediction. Predictions render in the viewport and are post-processable in the Post tab exactly like FE, FV, and PINNs solutions. Sesame can drive them too ("predict at load 1.1e6").

Sesame

Sesame lives in the right-side chat panel — address it by name. It sees the current UI state (active tab, mesh stats, body list) and can drive the UI by emitting tool calls.

What it can do

Sesame's capabilities are a registry of session tools spanning every stage of a model — the same registry drives journal codegen, so anything Sesame does is identically replayable as a script. Representative examples per category:

Full parameter-level detail (bounds, defaults, which backend/physics combination each tool applies to) lives in Sesame's own tool registry — ask it directly, e.g. "what parameters does set_fsi_options take?".

Body indexing

Sesame refers to bodies by 0-based index in creation order. Body 0 is the first body you created, body 1 the second, etc. The dispatcher resolves the index to the underlying body_id at call time.

Vision

Sesame always has the current model state (active tab, bodies, surfaces, meshes, BCs, volume conditions, physics/model options, solver options, contact/FSI options, and mesh roles) in every turn. The viewport image itself is only sent when you check Vision in the chat panel — enable it for requests where Sesame needs to actually look at the geometry (e.g. "is this centered correctly?").

What it doesn't do

Browser file pickers can't be filled programmatically. For a CAD file already on the server, ask Sesame to search for it and import it by path rather than "upload" it directly.

Mesh Algorithm Reference

For 2-D meshes (dim = 2): delaunay_2d, frontal_2d, automatic_2d, meshadapt, delaunay_quads.

CAD Edit Operation Reference

CSG Operation Reference

Primitives — session.csg_make_shape(type, params, name, body_id)

box      {"dx","dy","dz", "cx","cy","cz"}
sphere   {"r",             "cx","cy","cz"}
cylinder {"r","h",         "cx","cy","cz"}
cone     {"r1","r2","h",   "cx","cy","cz"}
torus    {"r1","r2",       "cx","cy","cz"}

Extrude — session.csg_extrude(pts, length, draft, name, body_id)

pts is a list of [x, y] pairs forming a closed profile (last point auto-connects to first).

Boolean — session.csg_boolean(op, body_a, body_b, name, body_id)

op ∈ {"union", "cut", "intersect"}. body_a / body_b are body_id strings.

Transform — session.csg_transform(body_id, op, params)

translate {"tx","ty","tz"}
rotate    {"ax","ay","az","angle_deg"}
mirror    {"plane": "xy"|"yz"|"xz"}
scale     {"sx","sy","sz"}        # uniform-with-axis scale (gp_Trsf)
stretch   {"sx","sy","sz"}        # non-uniform per-axis (gp_GTrsf)

Delete — session.csg_delete(body_id)

Clears Redis cache entries for the body's current STEP and the body_id mapping.

Keyboard & Mouse