Setting up workflow input files

A lume-ace3p run is a user-composed workflow: — an ordered list of modules (cubit, omega3p/s3p, acdtool, track3p_source, particles, geant4, …) that are validated into a runnable DAG by their artifact dependencies. The chain is not a fixed pipeline: you list only the modules you want (an Omega3P sweep is cubit → omega3p → acdtool; an S3P sweep is cubit → s3p), and each module carries its own input-file references. This page covers the external input files those modules consume; see YAML configuration reference for the module list itself. Typical ACE3P input files need only minimal adjustment for use with lume-ace3p — the main consideration is making sure variable and file names are consistent throughout each input file.

Cubit journal files

Cubit journal files can be very complex; only the parts that directly interface with lume-ace3p are described here. The important aspects are:

  • variable name references

  • mesh export commands

Variable names and values should generally be near the beginning of a Cubit journal file. lume-ace3p will read and adjust these values based on input parameters. For example, a Cubit journal might contain APREPRO lines like:

#{my_variable_1 = 90}
#{my_variable_2 = 123}
#{my_variable_3 = 0.5}

lume-ace3p will overwrite the numeric quantities following the = signs in those lines.

Important

The variable names in the Cubit journal file must exactly match those used in the lume-ace3p Python script input dictionary.

Since ACE3P can use acdtool to convert Genesis (.gen) meshes into NetCDF (.ncdf), the export command in the Cubit journal should use the Genesis option, e.g.:

export Genesis "my_mesh_file.gen" block all overwrite

This exports the generated mesh into a .gen file. The mesh conversion is a sub-step inside the cubit module — after meshing, the module calls acdtool to convert the .gen file to a .ncdf file of the same name (my_mesh_file.ncdf here). It is not a separate workflow entry; toggle it with meshconvert: false on the cubit module entry when the journal already exports a .ncdf mesh (or you otherwise want to skip conversion). To skip Cubit meshing entirely, drop the cubit module and provide the mesh with a mesh source module instead — see YAML configuration reference.

For more information on Cubit journal files, see the official Cubit documentation.

ACE3P input files

Providing an ACE3P input file is optional — users may instead include all ACE3P parameters within the lume-ace3p YAML file (see Parameter sweeping). ACE3P input files share a common structure across all ACE3P modules (Omega3P, T3P, S3P, …). The general format is based on key-value containers with colon (:) separators and nested curly braces. The most common container is the ModelInfo section. For example, an Omega3P input file may contain:

ModelInfo : {
  File: ./my_mesh_file.ncdf

  BoundaryCondition : {
    Magnetic: 1, 2
    Exterior: 6
  }

  SurfaceMaterial : {
    ReferenceNumber: 6
    Sigma: 5.8e7
  }
}

The boundary condition and surface material numbers correspond to the sideset flags defined in the Cubit journal.

Important

The mesh filename in File: must match the name used in the Cubit journal export command (with the .ncdf extension, since the .gen extension is converted automatically).

ACE3P sections allow same-named siblings (e.g. two Port: blocks distinguished by ReferenceNumber, multiple SurfaceMaterial: blocks). lume-ace3p parses ACE3P inputs into an ordered tree of name/child pairs, so duplicates are preserved end-to-end; matching overrides from the ace3p: sub-block of input_parameters are merged positionally back into the file.

Both brace placements are accepted — on the key’s line (ModelInfo : {, the usual Omega3P/S3P style) or on its own line below it, which is how the T3P tutorial examples are written:

ModelInfo:
{
  File: ./my_mesh_file.ncdf
}

Important

Some ACE3P keys contain spaces — T3P’s Number of sigmas, Curved Surfaces and Start contour, for instance. The parser preserves them verbatim, and the solver strips whitespace from keys internally (t3p.out echoes the parsed input, where it appears as Numberofsigmas). An override key in the ace3p: block must therefore be spelled exactly as it appears in your input file, spaces included:

input_parameters :
  ace3p :
    'LoadingInfo' :
      'Bunch' :
        'Number of sigmas' : 6

When you provide an ACE3P input file via the solver module’s input: key and the ace3p: overrides do not change or sweep any value inside it, the file is copied to each working directory verbatim — no parse / rewrite round-trip occurs. Parsing only happens when overrides are present, or when no input: file is provided and the entire input must be assembled from the YAML.

For more information on configuring ACE3P input files, see the ACE3P tutorials.

acdtool postprocess files

An acdtool postprocess script is used to parse ACE3P code outputs for quantities such as field monitors, impedance calculations, etc. The general input structure is based on sections whose contents are contained within curly braces. Section contents are key-value pairs separated by = signs. acdtool reads in a .rfpost file and writes results into a rfpost.out file. lume-ace3p parses that output into a Python dictionary which can be used for printing output parameters or for optimization.

Important

Make sure the appropriate sections (e.g. [RoverQ]) are included with the appropriate ionoff flag set to 1 for postprocessing.

A .rfpost file is only one of acdtool’s three input dialects, and postprocess rf only one of its nineteen commands. For the full command surface, all 24 .rfpost blocks with the shape and destination of each one’s output, and the input semantics that are not guessable from the tutorial files (the >1e6 domain-bound sentinels, gradient = -1, modeID2 = -1), see acdtool reference.

For more information on configuring acdtool input files, see the ACE3P tutorials.