> ## Documentation Index
> Fetch the complete documentation index at: https://docs.davinci-app.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulation View

## Description

A Davinci Simulation is a **compiled Solution Space**. You set it up once (mesh the
geometry and apply a parametric boundary-condition program), compile it once (a
certified reduced-order model with adversarial full-order gates), and from then on
every parameter combination answers instantly — live 3-D fields, sliders on every
declared parameter, quantities of interest, and a reduction-error certificate on
every answer. A full-order verification solve is available at any point of the
parameter box.

The compiled route covers steady **thermal** conduction (with convection, flux,
radiation and temperature-dependent conductivity), linear **structural** statics
(fixtures, forces, pressures, body accelerations, springs, preloaded contacts,
multi-body assemblies) and their **thermo-elastic** coupling as Class A physics; the
Class B fragments (modal, harmonic, random vibration, shock, acoustic, rotor tone
sweep, transient thermal, transient structural, laminar flow) and the optics stack (optical surfaces and
trains) are gate-validated against full-order references and offered by default, as
are system simulations (see "System simulations"); geometry axes ride behind an admin
flag (see "Advanced capabilities").

The Simulation View has two modes: **Simulation Setup** and **Simulation Result**
(the Solution Space explorer).

## Simulation Setup View

![](https://mintcdn.com/celedonsolutions/jCTk0BjpdyYUEAx3/images/workspace_simulation_setup.png?fit=max\&auto=format\&n=jCTk0BjpdyYUEAx3\&q=85\&s=02480cdff14d370a9f78e3b2c6810a5f)

### What a setup is

A simulation references one geometry (a CAD Language part, an assembly, an imported
STEP, or a circuit board) and carries a Python **BC program**:

```python theme={null}
def boundary_conditions(mesh, select, param):
    alloy = material("Aluminum 6061-T6")
    F = param("F_load", default=500.0, range=(0.0, 2000.0), unit="N",
              doc="downward load on the top face")
    return [
        fix(select.plane("-z")),
        force(select.plane("+z"), total=[0.0, 0.0, -F]),
        solid(alloy),
        qoi("max_displacement", kind="max_displacement"),
        qoi("max_von_mises", kind="max_von_mises"),
    ]
```

Everything the solver consumes is a *returned descriptor*: boundary conditions
(`fix`, `force`, `pressure`, `bearing`, `acceleration`, `temperature`, `flux`,
`convection`, `radiation`, `inflow`/`outflow`/`noslip`), constitutive and coupling
declarations (`solid(material(...))`, `fluid(...)`, `thermo_elastic(...)`),
analysis fragments (`modal`, `harmonic`, `random_vibration`, `shock`, `acoustic`,
`tone_sweep`, `transient`, `transient_structural`, `optical_surface`/`optical_train`,
`geometry`) and quantities of interest (`qoi(...)`). A `param(...)` with a range becomes
a live slider axis only when a returned descriptor consumes it. Every nonzero
dimensional value carries a unit through `quantity(value, "unit")`; units are audited
against the project's unit definitions.

**Time histories.** A `profile=` (`step_profile()`, `ramp(...)`, `pulse_profile(...)`,
`sine_profile(...)`) shapes a load in time. On `flux()`/`convection()` it rides a returned
`transient(t_end=..., dt=..., T0=...)`, a heat-up or cool-down history. On
`force()`/`pressure()` it rides a returned `transient_structural(t_end=...)`: the response
to suddenly applied, ramped, pulsed or oscillating loads, as the static response to the
loads at each instant plus a modal correction (mode-acceleration Newmark on the modal
basis, which the setup adds). A load without a profile acts as a step from t = 0. Omit
`dt` and the compile takes a twentieth of the first mode's period at the stiffest point
of the parameter box; an explicit `dt` that resolves less is refused with the one that
would, and a history is at most 20,000 steps. Omit `n_modes` too: a sudden load excites
modes far above the first, and the compile computes 60 and keeps the fewest that leave
at most 6% of the loads' static deflection to the modes it drops. With too few modes the
history misses those modes' ringing, and the full-order gate below refuses it. `peak_dynamic_displacement` (the largest
surface |u| anywhere in the history) and `dynamic_displacement_at_time(time=...)` are its
QoIs; the static kinds still read the steady solve under the full loads, so an undamped
step's peak reads about twice `max_displacement`. The compile gates the history against a
full-order Newmark integration on the same step (5%).

```python theme={null}
force(select.plane("+x"), total=[0.0, 0.0, -F], profile=step_profile()),
transient_structural(t_end=quantity(20, "ms"), damping=0.02),
qoi("peak", kind="peak_dynamic_displacement"),
qoi("at 5 ms", kind="dynamic_displacement_at_time", time=quantity(5, "ms")),
```

### Setup controls

**Geometry**: pick the object to simulate. Assemblies export as one multi-body STEP
(bodies become `part_1..part_N`; touching bodies bond).

**Target nodes**: the mesh auto-sizer target (clamped to the server maximum).

**Set Up**: meshes the geometry and runs the BC program. The 3-D view paints the
mesh with every selection the program made (clamps, loads, temperatures, optical
faces), and the panel lists the realized physics, fragments, parameter axes, QoIs,
material sources and unit conversions. A program the compiler refuses is reported
with the offending line and a fix recipe; refusals are capability claims in the
negative (the compiler will not silently ignore an input it does not consume).

**Compile**: builds the certified Solution Space. Progress streams into the
diagnostics panel; when it lands the status chip turns **LIVE**.

**Staleness**: the object tracks what its setup consumed (geometry source, project
materials, unit definitions, the program, mesh settings). When any of those change,
a **SETUP STALE** or **LIVE STALE** chip appears with the reason, and a compile of a
changed program or geometry is refused until you set up again.

### Advanced capabilities

Four admin feature flags decide what the setup offers an author: Class B fragments
(dynamics, transient thermal and structural, flow, acoustics), optics (optical surfaces and trains) and
system simulations (see "System simulations") are on by default — every capability they
offer has an analytic anchor on a converged mesh, a passing authoring brief, kernel
parity and an explorer panel; a deployment may still switch them off. Geometry axes
(uniform scale, stretch and CAD parameter families) stay off until the family route's
mesh convergence is measured. The flags gate authoring reach — a program that already
declares a gated fragment, or defines `system()`, still sets up, compiles and runs.

## Simulation Result View

![](https://mintcdn.com/celedonsolutions/jCTk0BjpdyYUEAx3/images/workspace_simulation_result.png?fit=max\&auto=format\&n=jCTk0BjpdyYUEAx3\&q=85\&s=84e00488ac6d547e2f1fd56c51cc579f)

The explorer runs the same online solver as the server: every slider drag re-solves
the reduced system in well under a millisecond and repaints the surface.

### Parameters and fields

**Sliders**: one per certified axis (log axes, vector components and CAD morph axes
included). Axis playback sweeps a slider in bounce or wrap mode. CAD morph axes stay
two-way synchronized with the CAD parameter panel.

**Field selector**: temperature, displacement magnitude and signed components,
von Mises stress, harmonic displacement and stress amplitude, RMS displacement and
stress, shock peak displacement, transient temperature, the displacement of a structural
history at the scrubbed time, flow speed and pressure —
whatever the compiled physics provides. Deformation exaggeration is a true ×
control; the undeformed reference can be shown alongside.

**Sections**: x/y/z clip planes with true interior contours where the bundle
carries volume recovery; solid / transparent / wireframe rendering; frozen colour
ranges for comparisons.

**Contribution**: on coupled thermo-elastic studies, view the combined field or the
mechanical-only / thermal-expansion-only share.

### Fragment panels

Dynamics studies add a drive-point FRF plot with a frequency slider and an animated
operating-deflection shape, a shock response spectrum, and a rotor-tone waterfall;
transient studies add a time scrubber with playback (thermal: the peak temperature
against time; structural: the peak surface displacement against time, the time of the
peak and its multiple of the static deflection, with the displacement at the scrubbed
time painted and warped on one colour bar for the whole history); optics studies add
wavefront, PSF/MTF, Zernike and coronagraph panels.

### Key results and trust

**Key results** lists every declared QoI at the current point. The certificate chip
reports the Class A error bound at the point (or the family's surrogate-certified
bound, or the held-out gate result for Class B fragments); a point outside the
certified envelope is flagged amber.

The certificate answers "did the reduced model reproduce Davinci's full-order model on
this mesh?" It does not establish constitutive correctness or that the boundary
conditions represent reality — treat it as reduction evidence, not validation.

**Mesh convergence** is a separate claim and is measured separately. A compile meshes
the part with quadratic tetrahedra, adapts the mesh to the declared QoIs (adjoint-based
error indicators, two or three remesh loops within the node budget, at least two
elements through every wall the budget allows; the size field is smoothed and graded,
mirrored across the part's own symmetry planes and kept within about a 3:1 range, so an
adapted mesh reads as a mesh and not as patches) and then re-solves every measurable QoI
on a mesh with twice the nodes. What that acceptance check found is stated in the
"What these numbers rest on" panel, in each QoI export row and in `QuerySimulation`'s
output:

* *converged* — the QoI moved less than the tolerance (2%) against the finer mesh;
  the remaining discretisation error is estimated by Richardson extrapolation.
* *mesh-dependent* — a peak stress on a rigid `fix()` is a singularity of the model and
  grows without bound under refinement. It is served with its measured drift, never as
  converged; support the part on a compliant `bearing()` or `spring()` for a peak that
  converges.
* *not measured* — optics, optical-surface and flow QoIs have no bare-mesh evaluator
  yet; their reduction certificate still holds, their discretisation error is not
  measured. Assemblies, geometry axes and flow studies keep a uniform mesh (the record
  says why).

A QoI that has not converged at the node budget is not served at all: the compile refuses
with `does not converge under mesh refinement` and the recipe (raise **Target nodes**, or
narrow what the QoI reads).

**Design space** (LHS sampling with backend or WebGPU evaluation) plots QoIs across the
box; hover a sample to jump the live view to it. With advanced workflows enabled the
panel also shows sensitivity jets, a certified tolerance Monte Carlo, verify-at-point
(a full-order solve compared field by field) and the compile gate record.

## System simulations

A simulation whose program defines `system(cad, param)` instead of
`boundary_conditions(...)` is a **system simulation**: it runs the dynamics of a whole
system over time under declared scenarios: the **multibody** motion of a linked
assembly (or of bodies the program builds), the physical **networks** that power, load
and cool it, and the **controls** that command it, all solved together. It reports
signals, poses, joint reactions, actuator efforts, currents, temperatures, events and
QoIs, and its **linear analysis** gives modes, frequency responses and loop margins. It
is the same simulation object; nothing is meshed. Flexible bodies and thermal blocks
reduced from a field simulation, and FMU co-simulation, are not yet available to
programs.

```python theme={null}
def system(cad, param):
    sc = mbs.from_cad(cad)
    gear, oleo = sc.joint("gear_swing"), sc.joint("oleo_extend")
    aluminium, steel = quantity(2700, "kg/m^3"), quantity(7850, "kg/m^3")
    return [
        sc,
        mbs.body(sc.body("door_left"), density=aluminium),
        mbs.body(sc.body("door_right"), density=aluminium),
        mbs.body(sc.body("main_strut"), density=steel),
        mbs.body(sc.body("bogie"), density=steel),
        mbs.drive_from_motion(sc.motion("main_gear_deploy"), durations=[quantity(2, "s")] * 3),
        scenario("deploy", duration=quantity(6, "s"), analysis="inverse_dynamics",
                 environment=[env.gravity()], output_dt=quantity(10, "ms")),
        qoi("peak trunnion torque", kind="max_abs", signal=gear.effort),
        qoi("peak oleo force", kind="max_abs", signal=oleo.effort),
        qoi("deployed trunnion load", kind="final", signal=gear.reaction.force_magnitude),
    ]
```

**Bodies and joints.** `mbs.from_cad(cad)` reads the linked assembly: one body per
instance with mass properties measured from its materials, its joints and couplings, and
its motion studies. A moving part without a material is refused (`missing_inertia`, with
the parts named) until the program gives it a mass, either explicitly
(`mass=`, `inertia=`) or with `density=`, which fills the part's measured solid. Without
an assembly the program builds its own bodies (`mbs.body(name, mass=, inertia=,
position=)`), frames on them and joints between them (`revolute`, `prismatic`,
`cylindrical`, `ball`, `rigid`, `generic`).

**Loads and motion.** Springs, dampers, bushings, forces, torques, joint efforts and
actuators load the bodies. `mbs.drive(joint, value)` prescribes a joint over time, and
`mbs.drive_from_motion` runs one of the assembly's motion studies, each stage rest to rest.

**Networks.** Motors, inverters, batteries, gears, wheels, heat capacities, convection,
pipes, pumps and hydraulic cylinders are components with ports in their domain
(electrical, magnetic, rotational, translational, thermal, thermal-fluid, hydraulic).
`connect(...)` joins ports: across a node the potentials (voltage, angle, temperature,
pressure) are equal and the flows (current, torque, heat, volume flow) balance.
`mbs.flange(joint)` puts a joint into a network, so a motor and gearbox drive a body of
the assembly. A component the library lacks is written with `component(...)` from its
own equations. Every network needs its reference (a ground, a fixed flange or an
inertia, an ambient, a reservoir); one without is refused before it runs, naming what
could anchor it. Losses can heat the model: a motor or inverter with `thermal=True`
carries a heat port to wire into the cooling.

**Controls.** PID loops (with saturation and anti-windup), filters, transfer functions
and state-space blocks run with the plant; sampled blocks on a `ctrl.clock` model a
digital controller with a zero-order hold; state machines switch modes on conditions,
and `ctrl.behavior` runs one of the project's own state machines as a sampled block (the
simulation goes stale when it is edited).

**Contact.** Compliant joint stops and latches (`mbs.stop`, `mbs.latch`), Stribeck and
LuGre joint friction (`mbs.friction`), contact between convex shapes on the bodies
(`mbs.sphere`, `mbs.capsule`, `mbs.box`, `mbs.hull`, or `mbs.convex_decomposition` of a
part's collision mesh, with `mbs.contact` naming the pair and its law) and Fiala or Magic
Formula tires (`mbs.tire`) on roads from `env.road` make up **contact\_dynamics**. A latch
engages at its angle and then holds the joint like a stiff spring; engagements and stops
appear in the run's events, and their efforts are signals a QoI can read.

**Scenarios.** `transient` integrates the equations of motion; `inverse_dynamics` follows
a fully prescribed motion and reports the efforts and reactions it takes; `equilibrium`
finds the static pose; `linearize` and `frequency_response` linearize the system about
its initial state, an equilibrium or an instant of a transient and report its modes
(`natural_frequency`, `damping_ratio`, `eigenvalue`), frequency responses, and a
loop's `gain_margin`, `phase_margin` and `bandwidth` at a `ctrl.loop_break`. Scenarios can chain (`after=`), step a parameter mid-run
(`faults=`), and react to events (`when(...)`). A scenario with an `active=` list keeps
only the force elements, efforts and events it names; joint stops and friction can be
named there too, and a stop left out of the list does not act in that scenario. QoIs read any signal: joint
coordinates, rates and efforts, reaction forces and moments, body positions and
velocities, and expressions of them, through kinds such as `max_abs`, `final`, `rms`,
`integral`, `time_when` and `settling_time`.

**Reactions.** A joint's `reaction` is its constraint load on its source (moving) body,
at the source frame, with components along the target frame's axes (the joint axis
first). When joints over-constrain the bodies (a planar loop of revolutes, for example)
equilibrium fixes only some reaction components. The setup lists the joints and
components it leaves indeterminate, and a QoI that reads one is refused
(`redundant_reactions`) rather than reporting an arbitrary split: read a determinate
component (a pin's in-plane force), or make the joint set compatible.

**Trust.** Compile runs every scenario at its default parameters, then re-runs it at a
tenth of its tolerance and half its step. A QoI is served with certificate B only when
its scenario completed, the QoI moved less than 1% on the re-run, the constraints held
(drift below 1e-6 relative) and the energy audit closed (residual below 1e-4 of the
peak energy flow; a larger residual flags the QoI). The certificate is numerical
evidence about the run, not validation of the model.

**System explorer.** The result view plays a run back in 3-D on the linked assembly (or
on a schematic of the bodies when there is none), with the QoIs, signal plots against
time with event ticks, the run's credibility record and the event list. Every panel
follows the playback time, and clicking a QoI or an event moves playback to that instant.
Sliders on the declared parameters pick another point: **Run** requests a run of the
scenario there, and **Verify** a run under the compile's gates, whose QoIs carry
certificates.

**Studies.** The explorer's Studies section runs one scenario at many points of a box of
the declared parameters: a sweep (full factorial), a Latin hypercube, a Sobol sequence,
Monte Carlo, Saltelli sensitivity indices, or an optimization of one QoI (SLSQP, using the
engine's gradients where a run has them). Each point is an ungated run, so a study's
statistics, indices and optimum carry credibility class C. A study also fits a surrogate of
each QoI that tests, requirement margins and trade criteria read between runs through
`[simulation](scenario=..., p=...).qoi`. A surrogate whose leave-one-out error is over 5%
of the QoI's range over the study is too coarse to answer: the point reads as unavailable
until a run or a denser study covers it, and the study lists each surrogate's error.
Opening a study plots one QoI over its runs: a curve along the parameter of a
one-parameter study, a scatter against a chosen parameter when there are several (the
others move between points too), and the QoI by evaluation for an optimization. A study
run on an earlier setup of the system is marked so: its numbers describe that setup, and
its surrogates no longer answer between runs. A trade sweep whose criteria read system
QoIs that no run or study answers offers **Run the missing studies**, which runs a Latin
hypercube over the box the sweep needs and sweeps again.

### Stress along a system's runs (motion\_loads)

A field simulation of one moving body's part reads that body's loads from a system
simulation with `motion_loads(source=<the system simulation's id>, body=<the body>)`.
Every joint and force element acting on the body is one of its attachments, and every
attachment wrench and spin product becomes a unit load case on the free body, held by
inertia relief. The stress at any instant of a run is the exact superposition of the case
stresses, so the program returns no supports and no other loads, only the part's
material:

```python theme={null}
def boundary_conditions(mesh, select, param):
    return [
        solid(material("Steel 4340 (Q&T)")),
        motion_loads(source="<system simulation id>", body="main_strut",
                     regions={"gear_swing": select.plane("+x") | select.plane("-x")},
                     distribution={"oleo_extend": "rbe3"}),
        qoi("peak stress", kind="max_von_mises", over="time"),
        qoi("worst instant", kind="critical_instant", count=3),
        qoi("deploy damage", kind="miner_damage", blocks={"deploy": 20000}),
    ]
```

**Where the loads enter.** Each attachment enters through its CAD interface on the part;
an attachment with no matching face (a sketch anchor, or a force element at a point) is
refused until `regions=` names the faces that carry it. A wrench spreads as an RBE3 spider
(force uniform per unit area, moment through the region's polar inertia); a pin in a bore
may use `distribution="bearing"`, cosine contact pressure resolved onto angle bins with
the resultant exact.

**Load histories.** `max_von_mises` with `over="time"` is the peak over the runs' samples,
`critical_instant` the time of the worst one (its record lists the largest peaks), and
**fatigue\_history**'s `miner_damage` the Miner damage of a duty cycle,
`blocks={scenario: repeats}`: rainflow (ASTM E1049) of each node's signed von Mises,
Goodman against the ultimate strength and the material's Basquin S-N curve. A material
without S-N constants is refused for damage. The runs are the source's latest compile run
of each scenario.

**Load history panel.** The result view adds a scenario and time scrubber with playback
(the *Von Mises at t* field), the envelope over the runs, the critical instants (click one
to jump there), the surface peak against time, and with a damage QoI the damage field and
the rainflow exceedance curve of the worst node.

**Trust.** The compile asserts the superposition against a full-order solve at random
channel weights (1e-6) and that the relieved cases leave no load on the solver's support,
and refuses a part whose FE mass differs from the system body's by more than 0.5% (centre
of mass 1% of the radius of gyration, inertia 2%). Each run is checked for quasi-static
validity: when the load spectrum's 99% energy frequency passes a third of the part's first
free-free mode the answer is flagged, because the dynamic response then needs a flexible
body. An attachment whose reactions the system leaves indeterminate is refused: the recipe
is a compatible joint set, a bushing for the joint's compliance, or a flexible body. When
the source's attachments change, the field simulation's setup goes stale.

## Agent tools

`SetupSimulation`, `CompileSimulation`, `QuerySimulation`, `OptimizeSimulation`,
`VerifySimulation` and `CaptureSimulationView` drive the same objects; the agent's
numbers come from the same point evaluator the explorer uses, so what it reports is
what you see.

On a system simulation, `SetupSimulation` with `requestedPhysics` naming any of
`multibody`, `network`, `controls`, `linear_analysis` and `contact_dynamics` has the system
program written from the request and the linked assembly, and sets it up.
`CompileSimulation` runs and gates every scenario, `QuerySimulation` answers from the
runs (or makes a new, ungated one), `VerifySimulation` re-runs a scenario at a parameter
point under the compile's gates, and `CaptureSimulationView` shows the assembly posed at
an instant of a run, with its signals plotted.

`VerifySimulation` compares every QoI it can value on the full-order model — steady
thermal and structural kinds, the dynamics kinds (a full-order modal build of the
same mesh), transient thermal kinds (the full-order march), transient structural kinds
(the mesh's own modes and full-order static solutions), flow kinds (the full-order
steady solve) and the optical wavefront / line-of-sight kinds (a dense retrace) —
against the Solution Space, and restates the compile's mesh-convergence record.
`CaptureSimulationView` paints mesh fields; on an optics study `field: "wavefront"`
renders the train's own panel (wavefront map, PSF, MTF) instead. A transient frame
reports the declared QoIs and, separately, the static kinds re-read on the state at
the captured time, so one name never carries two numbers. `field: "transient_displacement"`
paints a structural history at `timeS` (by default the instant it peaks) and states that
instant's peak beside the history's.

## Code objects

A Python code object reads a LIVE study through the same point evaluator, over the
runtime's `database` bridge:

```python theme={null}
from davinci import simulation

study = simulation("Beam study")
info = await study.describe()                       # axes, QoIs, certificates, mesh status
pt = await study.query(F=3.0)                        # one point, live
pts = await study.query([{"F": f} for f in (1, 2, 3, 4)])   # many points, one round trip
table = await study.sample(n=1024, seed=7)           # the Design space sample, as a table
```

Each answer carries the certificate class of every QoI and what the mesh-convergence
check measured about it; a stale study answers with a warning that names the reason,
and a study that is not LIVE refuses with its state. Samples run on the same
multi-core backend the result view's Design space sample uses. The API is read-only.

A system simulation answers from its runs:

```python theme={null}
swing = simulation("Swing test")
pt = await swing.query(L=1.5, scenario="swing")            # QoIs of the run at that point
sig = await swing.signals(["arm.q"], scenario="swing", t1=2.0)
sig["arm.q"].t, sig["arm.q"].values                        # SI units
```

A query never starts a run: a point no run has reached raises with the points that have
runs.

Re-running `SetupSimulation` on a compiled object demotes it to the setup state: the
Solution Space on record answers the previous program and is not served until the
next compile. Edits that arrive *under* a live object — geometry, materials, units,
the program itself — are the staleness path: the object is still served, with a
warning that names the reason and the object that moved (the geometry, the material,
the behavior or the source system simulation, by name).

**Refresh.** A stale simulation shows **Refresh** beside its stale chip in the setup
view and the system explorer. One click sets it up again, compiles it and, for a system
simulation, re-runs the points requested of the previous compile (the most recent
twelve, each scenario, point and kind once), since a compile replaces the runs with its
own. A point the new setup no longer accepts, such as one outside a changed parameter
range, is skipped and said in the status line rather than forced. The agent's stale
warnings name the same causes and the same steps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.