Running a Case

The Run case button in the Problemtype sidebar generates the Kratos input files and starts the solver. Every run is tracked in a Kratos Runs view in the Explorer.

What the view shows

One row per run, newest first:

running · 1m 12s · step 34	live, with the latest step written to vtk_output/
finished · 2m 14s	exited cleanly
failed · 0m 04s · exit 1	exited non-zero — expand the row for the code, or open the log
cancelled	you stopped it
detached	running, but not tracked — see below
orphaned	it was live when the window closed, and no exit code was recorded

Expand a row for the case folder, the output summary, the log, and the exit code when there is one. Hovering shows the exact command, the process id and the last line the solver printed.

Row and view actions

Right-click a run for what that run offers; the view's own title bar holds what acts on every run at once.

• Show Log opens the run's captured output — the Output channel for a tracked run, or the <stem>.kratosrun.log file a detached or adopted run teed to. When neither exists it says so instead of opening an empty view.
• Open Results previews the run's vtk_output/ as a timeline. For a run that did not finish cleanly it opens the last complete step rather than the newest one, since the final file may be truncated.
• Pack Results Into One File… packs the per-step result files into a single time-series container; see Time-series Playback.
• Export Convergence History… and Plot Convergence History, Export Monitors… and Plot Monitors are covered under Convergence and Monitors below.
• Reveal Case Folder selects the case's input document (ProjectParameters.json, or the problemtype's own primary document) in the Explorer.
• Remove From List drops a finished, failed, cancelled or orphaned run from the view. It removes the record, never the files: results, logs and sidecars stay on disk. A live run cannot be removed — stop it first.
• Stop All Runs (title bar) stops every live run after a modal confirmation; results already written are kept. Clear Finished Runs (title bar) removes every non-live record at once. Refresh Runs (title bar) re-reads the run store.

What's New

After the extension updates, a What's New screen summarizes the changelog entries newer than the version you last saw — the same CHANGELOG.md at the repository root, rendered without scripts. A fresh install shows nothing (there is no older version to be newer than); a downgrade or a missing changelog just advances the marker. Reopen it any time with Kratos MDPA: Show What's New, and turn the automatic popup off with the kratos.showWhatsNew setting.

Stopping

Stop asks the solver to finish its current step and finalize, so it can close the file it is writing. Anything already written to vtk_output/ is kept — nothing is deleted.

The request is a small file next to the mesh (<stem>.kratosstop) that the generated MainKratos.py checks between solution steps. It needs no console and no signals, so it works the same on Windows, Linux and macOS. If the solver has not stopped after 10 seconds — for example because a single step takes longer — the extension escalates: it interrupts the process on Linux and macOS, and terminates it on Windows. A run stopped this way can leave a half-written final file, and the confirmation dialog says so.

Because an interrupted solver can leave a half-written final file, Open results for a run that did not finish cleanly opens the last complete step rather than the newest one.

Cases generated by an older version

The stop file only works with a MainKratos.py generated by this version or later. For an older case, Stop skips straight to the signal: an interrupt on Linux and macOS, and an immediate terminate on Windows. Generate the case again to get the cooperative stop.

Tracked or interactive

By default the solver runs as a child process and its output goes to an Output channel. That is what makes a real exit code, live progress and a working Stop possible — and it means a wrong kratos.pythonPath is reported as a failed run naming the problem, rather than a "command not found" scrolling past.

Set kratos.run.launchMode to terminal if you need an interactive shell (a password prompt, a conda activate in your rc file). The run still appears in the view, but marked detached: a terminal cannot tell the extension when the solver exits, so its status is not tracked and no exit code is claimed.

Closing the window

Runs outlive the preview that started them, but not the window. By default, closing or reloading stops them (kratos.run.stopOnWindowClose) — a solver left behind would otherwise keep running with nothing able to report on it.

Turn that off and runs are detached instead, surviving the window. When the extension next starts it re-reads what it left behind and reports it honestly:

• the process is gone and no exit code was recorded → orphaned
• the process id is still alive → detached, "may still be running"

It never says running. Process ids get reused, so a live id is not proof that it is still your solver, and the viewer does not claim a liveness it cannot verify.

Two cases in one folder

The generated ProjectParameters.json, MainKratos.py and vtk_output/ live next to the mesh with fixed names, so two meshes in the same folder genuinely share them. Running a second case in a folder where one is already live warns you and names the other mesh; re-running the same case while it is live offers to stop the existing run first, since generating has just rewritten the files it was reading.

Isolated run workspaces

Set kratos.run.isolate to true to give every run a directory of its own instead. The mesh and the case state are copied into <case folder>/<runs folder>/<stem>-<run id>/ (the runs folder defaults to runs; change it with kratos.run.runsFolder), the case files are generated there, and the solver writes vtk_output/ there. Nothing in the case folder is touched, so two runs — of the same case, or of different cases in one folder — never share inputs or outputs, and they can run at the same time.

Each workspace keeps the evidence that makes a run comparable after a reload:

• kkss-preparation-v1.json — the problemtype, the source mesh revision, the settings and their revision, the effective ProjectParameters.json, the driver script, the CAD export identity when the mesh came with a handoff, and the run identity (the run id; case_run also records the study id and the run it was cloned from).
• .kkss-execution.json — the execution receipt: the owning request, the artifact revisions frozen when the run ended, and the state.
• <stem>.kratosrun.json — the latest-run sidecar, which now also names the workspace and the source mesh, so a reloaded window resolves the run through its own directory rather than by matching a file name.

The row in the Kratos Runs view is labelled Run workspace instead of Case folder, and its tooltip names the case mesh it belongs to. case_status, plot_runs and plot_run_bind read the same receipt; case_compare compares two such runs (see the MCP guide), and Compare With Another Run… on a finished run's context menu opens the same comparison as a Markdown report.

Quantity Across Runs… on a finished, failed or cancelled run reads one saved monitor from every terminal isolated run of the same case and opens a Markdown table: one row per run, the recorded case settings that differ between the runs as columns, and the monitor's value at the last evaluated frame of each. A run that is not finished, has no receipt or wrote no frame shows — instead of a value, with its reason listed below the table; it is never read as 0. The monitor's unit is only the label you gave it. Afterwards you can plot the quantity against a numeric case parameter in the Plots workspace. MCP case_run_quantity returns the same table.

A run started in the extension and one started through MCP case_run { isolate: true } use the same layout and the same receipt contract. case_run derives <case folder>/runs/<stem>-<requestId> from the request identity (the MCP tool has no workspace setting, so it always uses the default runs folder), and a retry with the same requestId finds its own workspace and never dispatches a second solver.

CAD handoff

When a mesh was exported from CAD-Preview, the export leaves <mesh>.handoff.json beside it. Preflight reads it and adds findings to the same card: a Part the case assigns to that resolved to no group (handoff-part-unresolved), boundary surfaces in no Part group (handoff-coverage), an entity in two Part groups (handoff-overlap), a non-unit export scale factor (handoff-units), and — after a remesh — a manifest whose node/element counts or output hash no longer match the mesh (handoff-stale). A file that is not a v1 handoff is one warning (handoff-unreadable) and nothing more. The manifest is never rewritten, and nothing is inferred from a file name: the mesh is compared by the output it records and its recorded SHA-256.

Generating a case from such a mesh records the export's identity in kkss-preparation-v1.json (handoff: {source, sourceRevision, replay} — names and content hashes only, never a path), so the chain CAD document → exported mesh → case mesh stays checkable after the project moves.

Progress

Progress is the latest step in vtk_output/, not a parse of the solver's log. The generated MainKratos.py prints nothing of its own — every line comes from Kratos' own logger in a format this extension does not control, and it is flushed on a timer, so a progress bar built on it would stall and then jump. The output directory is the honest signal, and it works the same for a tracked run, a terminal run, and a run adopted after a reload.

Convergence

The built-in problemtypes generate a MainKratos.py that appends one record per solve step to kkss-convergence-v2.jsonl beside the case, and a closing record when the solver finalizes. The Kratos Runs view reads it and adds a Convergence row under the run — last step, residual norm, convergence ratio and a verdict — and Export Convergence History… on the run's context menu saves the whole table as CSV.

The verdict is deliberately conservative, because it is read by people deciding whether to trust a result:

• converged — the run completed (the closing record exists) and every step that evaluated a criterion met it.
• not-converged — at least one step did not meet its criterion.
• solver-error — the solve hook raised. That is an unknown outcome; it does not show the iteration diverged numerically.
• incomplete — no closing record: the run is still going, was cancelled, was killed or lost. However good the last residual looks, no completion is claimed.
• unavailable — nothing readable, or the run completed without evaluating a criterion (a linear strategy).

A residual the solver did not publish is blank in the CSV and null in MCP, never 0, and the residual has no unit: the norm depends on the criterion (the file's residualDefinition says how). A step counter that goes backwards starts a new segment, reported as a restart. The history plot and saved monitor definitions are still to come.

Monitors

A monitor is a named quantity you want to follow across the saved frames of a run: the pressure at one node, or the mean pressure or the flux over a SubModelPart. Monitors live in <stem>.kratosmonitors.json beside the mesh, so each case keeps its own and switching the active case never redirects one.

{
  "version": 1,
  "monitors": [
    { "id": "p4", "name": "Pressure at node 4", "source": { "type": "history", "kind": "Nodal", "entityId": 4, "variable": "PRESSURE" } },
    { "id": "out", "name": "Outlet flux", "stride": 2, "unit": "m^3/s", "source": { "type": "region", "kind": "Nodal", "variable": "VELOCITY", "operation": "flux", "submodelpart": "Outlet" } },
    { "id": "probe", "name": "Pressure at the throat", "source": { "type": "point", "variable": "PRESSURE", "coordinates": [0.5, 0.1, 0] } }
  ]
}

A history monitor follows one entity; a point monitor interpolates a Nodal field at fixed coordinates, so it still means the same place after a remesh. Save one from the viewer with the Monitor button beside a field in the Inspect panel (it is offered when the open result has a time series, and asks which case when more than one is next to it), or add and remove them with the case_monitors MCP tool or by editing the file. A run's context menu in Kratos Runs shows how many are saved and offers Export Monitors… (a CSV) and Plot Monitors (the scientific-plots workspace, frame index on the x axis).

What to expect, because a monitor is easy to over-read:

• It is evaluated from the saved result frames, using the same extraction as the plots, so its sampling is the solver's output cadence. stride thins that after the fact (every Nth frame, the first and last always kept); it never interpolates between frames.
• It is not a live monitor. Values appear when the solver has written the frames, and when the latest run did not finish its newest frame is left out because it may be truncated.
• It reads the case's current outputs and does not prove they belong to a particular run: the run id shown is only a label from the latest-run record. To evaluate one isolated run, pass its binding from plot_run_bind and the bound result file to case_monitors evaluate: the receipt and the file revisions are then verified before and after the scan, and a changed run fails instead of being read.
• A field, entity, SubModelPart or frame that cannot be read is a gap (blank in the CSV, null in MCP), never 0, with a diagnostic saying which. A unit is shown only when the result file declares one or you supply a label, and it is never converted.

Converting results to other formats

The solver always writes VTK into vtk_output/. To get another format, type the extensions into Output ▸ also export as in the Problemtype section (for example .xdmf, .exo), or use Convert Results to Other Formats… on a run in Kratos Runs, which asks when nothing is saved. A run that finishes is converted automatically to the saved formats; a stopped or failed run is not, and nothing changes the run's status.

.xdmf and .pvd pack the whole series into one file (an XDMF needs the same mesh at every step, and falls back to one file per step with a warning when it changes). Every other format gets one file per step. Files go to converted/ beside the case (set another folder in the case file's output.exportFolder); the folder may not be inside the solver output. A format that cannot be written is reported as skipped with its reason and never stops the others. The same action is in the Command Palette as Convert Results to Other Formats…, the last conversion is recorded in the run's sidecar, and the headless equivalent is case_export_results (case_status reports the last conversion).

Headless

Agents drive the same runs through three MCP tools, which meet the editor on the filesystem: they read and write the same <stem>.kratosrun.json beside the mesh, so a run started on either side is visible from both.

• case_run generates the case files and starts the solver.
• case_status reports where it has got to, with a one-line convergence summary when the case has a monitor file.
• case_convergence returns the convergence history (see below).
• case_monitors saves and evaluates post-run monitors (see Monitors).
• case_stop stops it.

The server never owns a run, and that shapes how case_run behaves. Its stdout is the protocol channel and it exits with its client, so the solver is always started detached, with its output appended to <stem>.kratosrun.log — it outlives the server by construction, and Show output in the Kratos Runs view opens that same file.

waitSeconds (default 10) is how long the call blocks for the solver to finish. A short case comes back with its exit code. A real one does not, and that is not an error: the call returns running with the pid and the log path, the solve carries on, and you poll case_status. The budget is small on purpose — the only thing that can time a call out is the client's own request timeout, a number the server cannot see, so it hands off early rather than gambling on it.

One asymmetry worth knowing, because it looks like a bug and is not: the same live run reads running from case_run and detached from case_status. case_run holds the process handle and saw it start; case_status has only a pid, and pids are reused, so it will not claim more than it can verify.

Once the server exits, nothing is left to record how a detached run ended — so case_status reports it orphaned rather than inventing an exit code. The results in vtk_output/ are of course still there.

Preparation and structural convergence evidence

Case generation writes kkss-preparation-v1.json beside the solver inputs. It records effective parameters, case settings, source/solver mesh hashes, generated input hashes, generator script identity and generation warnings. Paths are file names relative to the report; undeclared units stay explicitly undeclared. Unknown report versions are not overwritten.

Structural scripts write kkss-convergence-v2.jsonl from the AnalysisStage solve hook verified against Kratos 10.4.3. Each record carries step/time, the actual solve outcome, final nonlinear iteration, solver criterion, and ProcessInfo RESIDUAL_NORM/CONVERGENCE_RATIO when published. The norm is criterion-dependent and has no inferred unit. Exceptions are unknown outcomes, not proof of numerical divergence. Successful finalization appends an end record; interrupted streams have no completion claim. Older v1 consumers must upgrade before reading v2.