TorsoCAE Documentation

What is TorsoCAE?

TorsoCAE is an AI-driven, browser-based CAD pre-processor and multi-physics simulation platform. Import geometry or a mesh, prepare the model, solve structural, thermal, CFD, CHT, FSI, or contact problems, and inspect the results in one workspace.

Choose DOLFINx + Torso, MFEM + Torso, Kratos, the native Torso shell solver, or supported PINN workflows. Linear systems can also use TorsoHPC remote solvers when additional compute capacity is available.

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. Model-building and solve actions share the same state contract; post-display state is saved with the project, while collaboration remains live session state rather than a solver journal action.

Three Workflows

Build the same model interactively, from a reproducible Python journal, or by asking Sesame.

Model state is kept consistent across interactive use, journal playback, project restore, and Sesame actions.

Assets & Projects

The Assets tab keeps account-owned files in four groups: CAD, meshes, TorsoCAE projects, and journals. Upload and open CAD in one action, import Nastran or CGNS meshes, load a .tcae project, or play a journal. Search, thumbnails, download, and delete controls are available in the same panel.

A .tcae project stores the model setup, geometry and mesh references, conditions, solver/model settings, reports, scene workspaces, annotations, and optionally solver results. When results are included, every available transient, nonlinear, or modal frame is stored so the frame slider remains usable after restoration.

Press Ctrl+S to open the TorsoCAE save dialog instead of the browser's page-save dialog. Select Include results when the project must be post-processable without rerunning the solve.

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 use the coordinates shown in the viewport.

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. Conditions already assigned to the body remain associated with it after an in-place transform.

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.

Imported Nastran and CGNS files, inline journal meshes, and generated mesh-first models appear in Components like CAD-derived meshes. Apply boundary conditions directly to their surface tags and volume conditions directly to their listed volume or mesh domain; CAD is not required.

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).
• Split Boundary by Size / Bends — divide an aggregated imported boundary into selectable tags while keeping the largest piece on the original tag.

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

Volume-condition fields adapt to the selected model. They may be assigned to CAD/CSG solids or directly to imported, inline, and generated mesh domains. 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 freestream density ρ, pressure, γ, and velocity components.

User Material Definitions

The Python API can define portable material functions from constants, tables, equations, or a journal-local Python function sampled over a declared range. These functions can be composed into nonlinear-elastic, hyperelastic, plasticity, viscoelastic, or custom material-law definitions and passed as law=... to solid(name).material(...). The definition is retained by journal replay and project save/load.

from pytorsocae import MaterialFunction, MaterialLaw

curve = MaterialFunction.from_callable(
    lambda strain: 250e6 + 700e6 * strain**0.25,
    input="equivalent_plastic_strain",
    output="flow_stress",
    domain=(0.0, 0.30),
)

law = MaterialLaw.plasticity(
    elasticity={"type": "isotropic", "E": 210e9, "nu": 0.3},
    yield_surface={"type": "j2"},
    flow_rule={"type": "associated"},
    hardening=curve,
)
session.solid("Specimen").material(E=210e9, nu=0.3, law=law)

For true conjugate heat transfer on DOLFINx or MFEM, density and dynamic viscosity may be temperature-dependent material functions. Assign the functions directly to the fluid volume as rho=... and mu=.... Their only input must be named temperature; values are evaluated locally on each MPI rank and the property update is included in CHT convergence.

rho_T = MaterialFunction.expression(
    "rho0 * (1 - beta * (temperature - T0))",
    inputs="temperature", output="rho",
    parameters={"rho0": 998.2, "beta": 2.1e-4, "T0": 293.15},
)
mu_T = MaterialFunction.table(
    input="temperature", output="mu",
    points=[[293.15, 1.002e-3], [333.15, 0.467e-3]],
)
session.solid("Fluid").material(
    physics="laminar_flow", rho=rho_T, mu=mu_T, cp=4182.0, k=0.6,
)

Temperature-dependent properties require a model that solves temperature; isothermal flow rejects them. The achieved relative property residual is reported as cht_material_property_residual. Its default tolerance is the larger of the CHT coupling tolerance and 1e-4; advanced journals may set material_property_tolerance and max_material_iterations (default 12) under model_options.conjugate_heat_transfer. Python functions are evaluated only while constructing a sampled material definition and are not called during finite-element integration. Full custom stress/state material laws still require a matching native constitutive evaluator. TorsoCAE reports unsupported combinations rather than substituting a built-in law.

Initial Conditions

Initial conditions define fields at the start of a fresh transient solve. Select one volume, open Conditions → Initial, and enter constants or expressions. Expressions may use x, y, z, geometry bounds, comparisons, where, pi, and the standard math functions listed above. Vector fields accept one expression per component.

Compressible DGFV exposes density, pressure, and velocity; structural transient models expose displacement, velocity, and acceleration; incompressible flow exposes velocity and pressure; DGFV VOF adds phase fraction; and DGFV RANS adds its turbulence variables. Initial conditions are saved with the project and are separate from restart checkpoints. A model only shows fields that its selected formulation consumes.

Physics, Backends & Solve

Pick a physics model, a submodel, and a numerics backend, then click Compute. While a local solve is active, the same button becomes Pause; it suspends the existing serial or MPI process in memory and changes to Resume. Suspension releases CPU execution without rebuilding the model, but retains memory and allocated solver resources. Stop Compute terminates the solve. File-backed checkpoint restart remains a separate operation for supported transient models.

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, elastoplastic-j2, elastoplastic-chaboche, and contact_mechanics (see Contact Mechanics). The native torso backend provides linear MITC4+ shell analysis. Structural transient solvers share Newmark, HHT-alpha, and generalized-alpha integration. Outputs include displacement, von Mises stress, principal stresses, reactions, and model-specific history fields.
• 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_epsilon, rans_k_omega_sst, volume_of_fluid, conjugate_heat_transfer, compressible_flow, and fluid_structure_interaction. See CFD and FSI.

Numerics backend

The backend list automatically narrows to implementations available for the selected formulation, physics, and submodel:

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, or schur for mixed velocity/pressure systems). device selects CPU or an available CUDA-enabled GPU for supported repeated assembly work; unavailable GPU requests report an error rather than silently changing device.

Explicit compressible DGFV advances the conservative state directly with SSPRK3 and CFL subcycling, so linear-solver and preconditioner selections do not apply to that formulation.

Cases & combinations

Use Single Analysis for the base setup or Cases & Combinations to define named load cases and weighted combinations. Base materials and supports remain active; case-specific pressure, traction, displacement, temperature, heat-flux, convection, inlet, and outlet conditions are added only to that case. Select any number of cases and combinations, then run them as one batch.

dead = session.analysis_case("dead", name="Dead load")
dead.surface(12, scope_id="mesh_0").bc("traction", values=[0, -5000, 0])
session.load_combination("operating", {"dead": 1.0, "pressure": 1.0})
results = session.compute_analysis(cases=["dead"], combinations=["operating"])

Modal analysis

submodel="modal_analysis" solves Kx = λMx and displays each requested mode as a result frame. The default eigen_solver="feast" uses oneMKL FEAST through TorsoHPC and requires an interval, supplied as eigen_interval_max/emax or a modal cutoff max_frequency_hz. FEAST modal analysis currently runs as a single-process request.

Flexible multibody dynamics

submodel="flexible_multibody_dynamics" connects flexible bodies through frames, surface attachments, and lower-pair joints. Configure the model with set_flexible_multibody(...). Fixed, spherical, revolute, prismatic, cylindrical, planar, and screw joints are supported, and results include flexible deformation, stress, motion frames, and 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.

Topology Optimization

Structural topology optimization is available from Python journals for one DOLFINx linear-elastic mesh. The study minimizes compliance subject to a volume-fraction limit and supports SIMP, optional Helmholtz filtering, Heaviside projection continuation, passive solid/void cell IDs, multiple load cases, and serial or MPI execution.

study = session.optimization_study(
    mesh_id="mesh_0",
    volume_fraction=0.4,
    initial_volume_fraction=0.5,
    penalty=3.0,
    filter_radius=0.01,
    projection_continuation={20: 2.0, 40: 4.0},
    optimizer="mma",
)
result = session.optimize(
    study, max_iterations=150, design_tolerance=1e-3,
    checkpoint_interval=5, checkpoint_path="beam_topology_checkpoint",
)
session.plot_result("Retained Material", result=result,
                    field_view_threshold=0.5)

optimizer="mma" is the general distributed constrained optimizer. optimizer="oc" remains available for the single volume-constraint reference workflow and accepts move_limit. Exact checkpoint resume is currently OC-only; MMA checkpoints preserve the design and history, but resume_from is rejected because its moving-asymptote history is not yet serialized.

Results include displacement and structural stresses plus design density, cell material fraction, filtered density, relative stiffness, and the retained-material preview. The preview thresholds the original mesh; it is not a remeshed manufacturing geometry or a second verification solve.

Thermal Topology and Custom Study Terms

For steady conduction, select thermal/thermal_only on DOLFINx, assign conductivity and thermal boundary conditions, then choose objectives and constraints from the supported responses. The design redistributes conducting material within the selected mesh. This workflow supports serial and MPI execution.

study = session.optimization_study(
    design={"type": "density", "mesh_id": "mesh_0", "initial_fraction": 0.3,
            "minimum_property": 0.001, "filter_radius": 0.02},
    objectives=[{"id": "temperature", "response": "mean_temperature"}],
    constraints=[{"id": "material", "response": "volume_fraction",
                  "sense": "le", "limit": 0.4, "scale": 0.4}],
    optimizer="mma",
)
result = session.optimize(study, max_iterations=200)
session.plot_result("Temperature", result=result, filename="temperature.png")
session.save_project("thermal_topology.tcae", include_results=True)

Available thermal responses are mean_temperature, ks_max_temperature, thermal_compliance, boundary_heat_flow, and volume_fraction. Use weight for objective weighting, sense="le" for an upper limit, sense="ge" for a lower limit, and positive scale to normalize a constraint. Negative objective weights maximize a response. The generic syntax also supports structural compliance and volume fraction for the base load case.

Temperature and volume-fraction responses accept region="all", a unique volume name, or region={"volume_tags": [1, 2]}. Heat flow uses region={"surface_tags": [1, 2]} and is positive outward in watts. Thermal compliance measures the natural thermal load weighted by temperature; it is zero for purely prescribed temperatures with no natural load.

ks_max_temperature is a smooth approximation controlled by parameters={"coefficient": 0.1}, in inverse kelvin. It can underestimate the actual maximum; always check the final peak temperature when assessing a temperature limit. minimum_property is the conductivity floor relative to the material's conductivity. Low-density regions remain poor conductors and do not model coolant flow.

The current thermal scope is one mesh, one steady load state, and constant material properties. Results include Temperature, Heat Flux, Relative Conductivity, and material-density views. External MMA design snapshots cannot yet resume the optimizer exactly. Transient thermal, fluid-channel, CHT, and shape optimization are not available in this release.

CFD

Set physics="cfd" with one of the CFD submodels. Incompressible flow runs on DOLFINx or MFEM where implemented. rans_k_omega_sst supports FEM and DGFV, rans_k_epsilon uses DGFV, and compressible_flow supports MFEM DG or shared DGFV on DOLFINx and MFEM.

• Incompressible laminar — transient incompressible Navier-Stokes on DOLFINx or MFEM. Select FEM for the mixed velocity/pressure discretization or DGFV for the conservative staggered pressure/face-flux discretization. Assign mu/rho on the fluid volume and inlet_velocity/outlet_pressure/wall/symmetry boundaries.
• Volume of Fluid (VOF) — immiscible two-phase DGFV with bounded conservative cell-volume transport, phase-dependent density and viscosity, and gravity. Define both phases and the initial fraction under Immiscible Phases. Active velocity coupling refreshes pressure and velocity at each phase-CFL interval for accuracy; frozen coupling reuses the outer-step flow field during phase subcycling for lower cost. Post exposes Volume Fraction and Density alongside Velocity and Pressure. Surface tension is not yet available.
• RANS k-epsilon and k-omega SST — select DGFV with formulation="dgfv" for either two-equation model on DOLFINx or MFEM. Assign mu/rho on the fluid volume, then set inlet intensity plus an optional turbulence length scale or viscosity ratio. Wall-function and wall-resolved treatments are available. DGFV turbulence transport currently requires dg_order=0.
• FEM k-omega SST — omit formulation="dgfv" to use the established FEM SST implementation. Model options include sst_variant="sst_2003m" or "sstm". DOLFINx also provides steady pseudo-transient convergence controls; pseudo-time is numerical continuation rather than physical time.
• DGFV formulation — for laminar_flow, dg_order=0 gives the finite-volume limit; higher orders add DG accuracy on the same pressure/face-flux formulation. Compressible Euler and DGFV RANS currently require dg_order=0. DGFV controls such as dg_order, dg_cfl, dg_penalty, and dg_relaxation belong in set_model_options(...), not solver options.
• RANS outputs — k-epsilon exposes Turbulent Kinetic Energy, Turbulence Dissipation Rate, and Eddy Viscosity. SST exposes Turbulent Kinetic Energy, Specific Dissipation Rate, and Eddy Viscosity. All are normal Post scalar fields.
• Conjugate heat transfer (CHT) — couples the laminar-flow solve with a scalar thermal solve across a shared fluid/solid interface.
• Compressible flow — ideal-gas inviscid Euler. Select DGFV with formulation="dgfv" on DOLFINx or MFEM, or FEM on MFEM. Assign rho, pressure, gamma, and freestream velocity on the fluid volume. DGFV accepts freestream farfield, numeric inlet_velocity, characteristic outlet_pressure, and inviscid wall/symmetry boundaries; unspecified exterior tags default to farfield. It uses HLLC with positivity-safe HLL fallback, SSPRK3, and automatic CFL subcycling. The validated DGFV scope is dg_order=0; Post includes Velocity, Pressure, Density, Mach Number, and Total Energy Density.
• Overset rotating-mesh flow — an interface type, not a submodel: one stationary background mesh, one rigidly rotating component mesh, and one overset interface between their fringe surfaces, on top of whichever CFD submodel you select. laminar_flow and rans_k_omega_sst are supported on both dolfinx and mfem, with either rotation mode; both backends wrap each body in the same shared k-ω SST closure. Prescribed rotation uses angular speed; torque-driven rotation integrates the computed hydrodynamic moment. Both modes are resumable — the rotor pose, and for torque-driven its angle and rate, are checkpointed with the flow state. Time integration is the theta family (time_theta=1.0 backward Euler, 0.5 Crank-Nicolson on dolfinx; mfem is backward Euler only), plus time_scheme="bossak" on the laminar path only — SST is theta-only because k/ω have no Bossak form. Overset is not an FSI mesh-motion option.

Overset journal setup

session.set_physics("cfd", "laminar_flow", backend="dolfinx")  # or "rans_k_omega_sst"
session.create_interface(
    type="overset",
    surfaces=[
        {"scope_id": "background", "surface_tags": [9]},
        {"scope_id": "rotor", "surface_tags": [1]},
    ],
    rotation={
        "axis_point": [0, 0, 0],
        "axis_direction": [0, 0, 1],
        "mode": "prescribed",
        "component_scope_id": "rotor",
        "omega": 20.0,
    },
)
session.set_solver_options(time_scheme="theta", num_steps=100, dt=1e-3, n_cores=4)
result = session.compute(mesh_ids=["background", "rotor"])

Compressible DGFV journal setup

session.set_physics("cfd", "compressible_flow", backend="dolfinx")
session.solid("Fluid").material(
    rho=1.225, pressure=101325.0, gamma=1.4,
    velocity_x=170.0, velocity_y=0.0, velocity_z=0.0,
)
session.solid("Fluid").initial_condition(
    "density", "where(x <= 0.5, 1.0, 0.125)"
)
session.solid("Fluid").initial_condition(
    "pressure", "where(x <= 0.5, 100000.0, 10000.0)"
)
session.surfaceGroup("Farfield", scope_id="flow_mesh").bc("farfield")
session.surfaceGroup("Outlet", scope_id="flow_mesh").bc(
    "outlet_pressure", values=[101325.0],
)
session.surfaceGroup("Body", scope_id="flow_mesh").bc("wall")
session.set_model_options(dg_order=0, dg_cfl=0.4)
session.set_solver_options(
    formulation="dgfv", num_steps=250, dt=2e-4, n_cores=4,
)
result = session.compute(mesh_ids=["flow_mesh"])

Conjugate Heat Transfer

True CHT solves fluid motion and fluid energy together with heat conduction in a separate solid domain. Start with one fluid mesh and one solid mesh, assign laminar_flow and thermal_only to the respective volumes, then select the two shared boundaries and create a Partitioned Exchange under Interface Condition.

• Fluid volume: assign rho, mu, conductivity k, and heat capacity cp under laminar_flow.
• Solid volume: assign conductivity k under thermal_only.
• Fluid boundaries: assign inlet velocity, outlet pressure, and wall conditions in the CFD channel.
• Thermal boundaries: assign temperatures, heat fluxes, convection, or insulation in the thermal channel.
• Choose Fluid temperature / solid heat flux for the standard solve order, or Solid temperature / fluid heat flux when the solid-side temperature drives the fluid energy solve.
• The default Conservative FE Projection preserves interface heat balance through an adjoint load map. Nearest Neighbor is available for locally matched interfaces.

Set the accelerator and maximum coupling iterations under Partitioned Coupling in Compute. DOLFINx + Torso, MFEM + Torso, and Kratos support CHT. Current scope is one fluid mesh, one solid mesh, and one logical thermal interface.

Fluid-Structure Interaction

Set physics="cfd", submodel="fluid_structure_interaction", and choose DOLFINx + Torso or MFEM + Torso. Both support serial and MPI runs. FSI uses one fluid mesh and one structural mesh with ALE mesh motion, iterative interface coupling, conservative surface transfer, and adaptive substepping.

• Assign laminar_flow to the fluid mesh and the selected structural submodel, normally geometric_nonlinear, to the structural mesh.
• Select the matching fluid and structural boundaries and create a Partitioned Exchange. Choose its field mapper there; the required traction and motion directions are shown before creation.
• Accelerator and maximum coupling iterations live under Partitioned Coupling. FSI-only mesh motion, predictor, substepping, and constituent controls remain model options, never general linear-solver options.
• 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", and choose MFEM or Kratos. MFEM uses its native Tribol contact path; Kratos uses an Augmented Lagrangian Method (ALM) mortar 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, or torsohpc-blaze.

• torsohpc-pardiso, torsohpc-amgcl, and torsohpc-blaze all support serial and distributed MPI solves.
• torsohpc-blaze is BiCGSTAB with symmetric diagonal scaling and takes no preconditioner.
• For AMGCL, choose none, jacobi, ilu, or gamg/amg according to the problem. Explicit choices are respected and unsupported combinations report an error.
• Modal eigen_solver="feast" uses the interval-based oneMKL FEAST service; provide an eigenvalue interval or maximum frequency.

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_physics("structural", "linear_elastic")
session.set_solver_options(
    formulation="pinns",
    pinn_provider="physicsnemo",
    pinn_epochs=5000,
    pinn_learning_rate=1e-4,
    pinn_collocation_points=10000
)
result = session.compute(mesh_ids=["mesh_0"])

Journal Scripting

Geometry, mesh, condition, material, model, solver, and compute actions are recorded as Python. Pure post-display state is saved with the project, while collaboration remains live session state rather than a solver journal command.

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 and pick a file. The browser clears the current setup, then re-runs each action while geometry, meshes, conditions, and results update in real time.

The script

from pytorsocae import TorsoCAESession

session = TorsoCAESession()
session.upload("part.step")
session.edit("merge-smooth", {"angle_deg": 30})
session.mesh(mesh_id="mesh_0", algo_id="hxt", size_factor=1.0, dim=3)
session.set_physics("structural", "linear_elastic", backend="dolfinx")
session.solid("Body_1").material(E=210e9, nu=0.3)
session.surface(3, scope_id="mesh_0").bc("fixed")
session.surface(7, scope_id="mesh_0").bc("traction", values=[0, 0, -1000])
session.set_solver_options(formulation="fem", n_cores=4)
result = session.compute(mesh_ids=["mesh_0"])

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)

Current Python API

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

Post & Reports

Geometry/Post displays result fields on the model. Select displacement, stress, temperature, heat flux, velocity, pressure, turbulence, phase-fraction, or other fields emitted by the active result. Transient, nonlinear, VOF, and modal results use the frame slider; modal frames correspond to mode shapes. Mesh edges remain available as an overlay when enabled in Settings.

For a structural topology study, Volume Fraction colors the original design domain. Select Retained Material to preview source mesh cells above the adjustable material-fraction cutoff (initially 0.5), including faces exposed where lower-density cells are hidden. Design Density, Filtered Density, Relative Stiffness, Displacement, and stress fields remain separate plots. The retained-cell view is not a remeshed or independently verified part.

Choose a legend style appropriate to the field: Linear Rainbow preserves the traditional engineering contour display; Perceptual gives a uniform sequential scale; Diverging centers signed values at zero; Logarithmic resolves positive values spanning several orders of magnitude; and Symmetric Log handles signed multi-decade ranges. Contours independently switch the selected style from continuous colors to discrete bands. The same mapping is used by surfaces, sections, iso-surfaces, vector magnitudes, streamlines, tracers, and the visible legend.

Use smoothing, deformation scaling, contours, section cuts, iso-surfaces, streamlines, or animated tracer particles as appropriate to the field. Add scene tabs to keep several field or section views available at once. Text overlays accept live @ commands such as @time, @step, and @nelem; typing @ opens a filtered command list, @\n inserts a line break, and @@ prints a literal @. Scope mesh counts by stable ID or visible name, for example @nelem{"Mesh 1"}.

Reports creates statistics, reaction/contact forces, line profiles, line integrals, and surface integrals. Field Data (.csv) exports one field or every available field with coordinates from a selected surface or the active cross-section. Select a surface in the model tree or viewport, or activate and position the cross-section first. Vector selections include magnitude and X/Y/Z components; raw computational values are exported without visual smoothing. Add report scenes to compare several plots without replacing the current one. Reports and their scenes are saved with the project.

Expressions

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.

profile = session.report(
    "line_profile",
    expression="sin(pi*x/10)*von_mises",
    line_start=[0, 0, 0],
    line_end=[10, 0, 0],
    n_points=101,
)
session.plot_result(
    "Von Mises Stress",
    result=result,
    filename="von_mises.png",
    smooth=True,
)
session.export_field_data(
    ["Displacement", "Von Mises Stress"],
    result=result,
    surface_tag=3,
    scope_id="body_1",
    output_dir=".",
    filename="surface_3.csv",
)

plot_result(...) writes the exterior result by default. Add normal=[nx,ny,nz] and constant for a cut-plane plot. export_field_data(...) uses the same display field names shown in Post; omit fields to export all available fields. If no filename is supplied, the defaults are default.png and default.csv respectively, and a relative path may be included.

Collaboration

Open the handshake control in the title bar to share the project currently in the workspace. Sharing does not require a running solver. Invite another signed-in user with their public Torso ID and assign a recognizable alias.

• The admin authorizes or removes participants and may pass or reclaim control.
• Participants can request control, follow the current controller's viewport, or explore independently.
• Shared running simulations remain available through Connect to Simulation.
• Collaboration controls are live session actions and are not recorded in journals.

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 FEM, DGFV, and PINNs solutions. Sesame can drive them too ("predict at load 1.1e6").

Sesame

Sesame lives in the right-side chat panel. It sees the active model setup and can carry out the same preparation, solver, reporting, and collaboration actions available in the workspace.

What it can do

Representative actions include:

Ask Sesame for parameter names, valid ranges, backend availability, current fields, frames, residuals, assets, reports, or the current setup before changing it. For example: "show the available FSI options", "set this mesh as the CHT solid", "plot von Mises along the centerline", or "run the operating combination". Sesame reports a solve as started when it is submitted and only reports a report or UI action as complete after the workspace confirms it.

Vision

Sesame always has the current model state, including selections, bodies, surfaces, meshes and refinements, conditions, materials, interfaces, physics and solver options, available result fields, frame or mode position, report scenes, residuals, and account assets. The viewport image itself is only sent when you check Vision in the chat panel. Vision captures the active Geometry/Post view or Reports plot; enable it when Sesame needs to inspect what is displayed.

What it doesn't do

Browser file pickers and security-sensitive account actions require you to interact with the browser. For a CAD file already in Assets, ask Sesame to open it by path rather than upload it again.

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)

Removes the selected CSG body from the current model.

Keyboard & Mouse