Execution Workflow¶

This page describes what happens after a frontend script calls exasim(...) and how to control compilation, runtime mode, CPU/GPU/MPI execution, exports, and restart-like workflows.

`exasim(...)` Pipeline¶

sequenceDiagram
  participant U as User script
  participant F as Frontend
  participant C as Codegen/CMake
  participant B as C++ backend
  participant O as Outputs
  U->>F: exasim(pde, mesh)
  F->>F: preprocessing(pde, mesh)
  F->>C: generate/reuse model code
  C->>C: cmakecompile(pde)
  F->>B: runcode(pde, numpde)
  B->>O: write dataout, residuals, VTK, QoI
  F->>O: fetchsolution / fetchresidual

The frontends keep runtime data under pde.datapath and generated build artifacts under pde.builddir / pde.buildpath. This avoids mixing generated C++ build products with user-visible datain and dataout files.

See Preprocessing for the detailed conversion from pde, mesh, and pdemodel into app.bin, master.bin, mesh*.bin, and sol*.bin.

Build And Cache Behavior¶

The generated model is compiled into a dynamic library or executable through CMake. Unchanged generated models can be reused through the frontend build area and per-user cache.

pde.datapath = pwd();
pde.builddir = fullfile(pwd(), ".exasim");
pde.buildpath = pde.builddir;

If you change only runtime data such as physicsparam, Exasim should avoid unnecessary recompilation when the generated model code is unchanged.

CPU, GPU, And MPI¶

pde.platform selects CPU or GPU-oriented execution in frontend configuration. The installed Exasim package and generated CMake project determine the concrete backend libraries.

pde.platform = "gpu"
pde.mpiprocs = 4

MPI runs use pde.mpiprocs and the launcher discovered by CMake or specified in pde.mpirun. Rank-local input/output paths are generated automatically.

Execution Modes¶

pde.executionmode controls how runcode(...) launches the generated executable.

Value	Launch behavior	Typical use
`0`	Solve mode. This is the default and preserves the historical command line.	Run a simulation and write solution output.
`1`	Postprocess mode. The frontend launches the executable with the `postprocess` subcommand.	Recompute visualization/QoI/output from existing `datain` and `dataout`.

Example:

pde["executionmode"] = 1
runstr = runcode(pde, 1)

Postprocess mode assumes compatible datain and saved solution files already exist. See Postprocessing.

Parameter Sweeps¶

Frontend sweeps run cases sequentially by default. Each row of physicsparamsweep is one concrete physicsparam vector.

pde.physicsparamsweep = [
    1.4 0.72 1000.0
    1.4 0.72 2000.0
];
pde.physicsparamwarmstart = 1;
[sol, pde, mesh, master, dmd] = exasim(pde, mesh);

Outputs are placed in deterministic case directories such as dataout/paramcase_0001/. The standalone app generated by exportapp can read the same sweep input and run the sweep without MATLAB, Python, or Julia.

`exportapp`¶

exportapp packages generated model code, input data, a CMake project, and the standalone app entry point for use outside the interactive frontend.

MATLABPythonJulia

exportapp(pde, "exported_naca_sweep");

from exasim import exportapp
exportapp(pde, "exported_naca_sweep")

Exasim.exportapp(pde, "exported_naca_sweep")

Use exportapp when moving a generated app to an HPC system or when you want a frontend-free standalone executable.

`exporttext2code`¶

exporttext2code packages the higher-level Text2Code inputs for an application. Use it when you want to regenerate the application later with the text2code executable instead of shipping generated kernels and a ready-to-build C++ app.

The exported directory contains:

File	Purpose
`pdemodel.txt`	Text2Code PDE model definition generated from the frontend model callbacks.
`pdeapp.txt`	Application, solver, mesh, output, and runtime configuration.
`grid.bin`	Mesh coordinates and connectivity.
`xdg.bin`	Optional geometry variables when `mesh.dgnodes` is present.
`udg.bin`	Optional initial solution when `mesh.udg` is present.
`vdg.bin`	Optional external variables when `mesh.vdg` is present. Backend code also refers to these variables as `odg`.
`wdg.bin`	Optional auxiliary ODE/ADE variables when `mesh.wdg` is present.

Unlike exportapp, this workflow does not export kernels/, main.cpp, or CMakeLists.txt. The receiving machine runs Text2Code to regenerate those files.

MATLABPythonJulia

exporttext2code(pde, mesh, "text2code_package");

from exasim import exporttext2code
exporttext2code(pde, mesh, "text2code_package")

Exasim.exporttext2code(pde, mesh, "text2code_package")

Regenerate the application from the exported package with:

cd text2code_package
export EXASIM_PREFIX=/path/to/exasim-prefix
/path/to/exasim-prefix/bin/text2code pdeapp.txt --out-dir generated

The exporter writes relative file names in pdeapp.txt, so the package can be copied to another machine. Set EXASIM_PREFIX when the package is outside an Exasim source checkout so Text2Code can locate installed runtime data and model headers. MATLAB can serialize boundary-expression function handles through the existing frontend conversion helper. Python and Julia exports require boundary, curved-boundary, and periodic expressions to already be strings, because arbitrary host-language callback functions cannot be represented safely in pdeapp.txt.

A minimal Python example is available at examples/Poisson/poisson2d/pdeapp_exporttext2code.py. It exports a Poisson application with grid.bin, xdg.bin, udg.bin, vdg.bin, wdg.bin, and a two-case physicsparam sweep.

Restart And Postprocess-Oriented Runs¶

Restart behavior is controlled by saved solution files, time offsets, and runtime options such as timestepOffset. Parameter-sweep warm starts reuse the previous converged case as the next initial state; they do not imply a full mesh or model rebuild when only physicsparam changes.

Execution Workflow¶

exasim(...) Pipeline¶