`caelus` – Common CPL actions¶

New in version 0.0.2.

The caelus command provides various sub-commands that can be used to perform common tasks using the CPL library. Currently the following sub-commands (or actions) are available through the caelus script.

Action	Purpose
`cfg`	Print CPL configuration to stdout or file
`clone`	Clone a case directory
`tasks`	Automatic execution of workflow from a YAML file
`run`	Run a CML executable in the appropriate environment
`runpy`	Run a python script in the appropriate environment
`logs`	Parse a solver log file and extract data for analysis
`clean`	Clean a case directory after execution
`build`	Compile OpenFOAM or CML sources

Note

The script also supports the common options documented in the previous section. Care must be take to include the common options before the subcommand, i.e.,

# Correct usage
caelus -vvv cfg -f caelus.yaml

# The following will generate an error
# caelus cfg -vvv # ERROR

caelus cfg – Print CPL configuration¶

Print out the configuration dictionary currently in use by CPL. This will be a combination of all the options loaded from the configuration files described in configuration section. By default, the command prints the YAML-formatted dictionary to the standard output. The output can be redirected to a file by using the caelus cfg -f option. This is useful for debugging.

$ caelus cfg -h
usage: caelus cfg [-h] [-f CONFIG_FILE] [-b]

Dump CPL configuration

optional arguments:
  -h, --help            show this help message and exit
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        Write to file instead of standard output
  -b, --no-backup       Overwrite existing config without saving a backup

-f output_file, --config-file output_file¶: Save the current CPL configuration to the output_file instead of printing to standard output.

-b, --no-backup¶: By default, when using the caelus cfg -f CPL will create a backup of any existing configuration file before writing a new file. This option overrides the behavior and will not create backups of existing configurations before overwriting the file.

caelus clone – Clone a case directory¶

caelus clone takes two mandatory parameters, the source template case directory, and name of the new case that is created. By default, the new case directory is created in the current working directory and must not already exist. CPL will not attempt to overwrite existing directories during clone.

$ caelus clone -h
usage: caelus clone [-h] [-m] [-z] [-s] [-e EXTRA_PATTERNS] [-d BASE_DIR]
                    template_dir case_name

Clone a case directory into a new folder.

positional arguments:
  template_dir          Valid Caelus case directory to clone.
  case_name             Name of the new case directory.

optional arguments:
  -h, --help            show this help message and exit
  -m, --skip-mesh       skip mesh directory while cloning
  -z, --skip-zero       skip 0 directory while cloning
  -s, --skip-scripts    skip scripts while cloning
  -e EXTRA_PATTERNS, --extra-patterns EXTRA_PATTERNS
                        shell wildcard patterns matching additional files to
                        ignore
  -d BASE_DIR, --base-dir BASE_DIR
                        directory where the new case directory is created

-m, --skip-mesh¶: Do not copy the constant/polyMesh directory when cloning. The default behavior is to copy the mesh along with the case directory.

-z, --skip-zero¶: Do not copy the 0 directory during clone. The default behavior copies time t=0 directory.

-s, --skip-scripts¶: Do not copy any python or YAML scripts during clone.

-e pattern, --extra-patterns pattern¶

A shell-wildcard pattern used to skip additional files that might exist in the source directory that must be skipped while cloning the case directory. This option can be repeated multiple times to provide more than one pattern.

# Skip all bash files and text files in the source directory
caelus clone -e "*.sh" -e "*.txt" old_case_dir new_case_dir

-d basedir, --base-dir basedir¶: By default, the new case directory is created in the current working directory. This option allows the user to modify the behavior and create the new case in a different location. Useful for use within scripts.

caelus tasks – run tasks from a file¶

Read and execute tasks from a YAML-formatted file. Task files could be considered recipes or workflows. By default, it reads caelus_tasks.yaml from the current directory. The behavior can be modified to read other file names and locations.

$ caelus tasks -h
usage: caelus tasks [-h] [-f FILE]

Run pre-defined tasks within a case directory read from a YAML-formatted file.

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  file containing tasks to execute (caelus_tasks.yaml)

-f task_file, --file task_file¶: Execute the task file named task_file instead of caelus_tasks.yaml in current working directory

caelus run – run an executable in the appropriate environment¶

Run a single application. The application name is the one mandatory argument. Additional command arguments can be specified. The behavior can be modified to enble parallel execution of the application. By default, the application runs from the current directory. This behavior can be modified to specify the case directory.

Note

When passing cmd_args, -- is required between run and cmd_name so the cmd_args are parsed correctly. E.g. caelus run -- renumberMesh "-overwrite". This ensures that the arguments meant for the CML executable are not parsed as arguments to the caelus executable during the run.

$ caelus run -h
usage: caelus run [-h] [-p] [-l LOG_FILE] [-d CASE_DIR] [-m MACHINEFILE]
                  cmd_name [cmd_args [cmd_args ...]]

Run an executable in the correct environment

positional arguments:
  cmd_name              name of the executable
  cmd_args              additional arguments passed to command

optional arguments:
  -h, --help            show this help message and exit
  -p, --parallel        run in parallel
  -l LOG_FILE, --log-file LOG_FILE
                        filename to redirect command output
  -d CASE_DIR, --case-dir CASE_DIR
                        path to the case directory
  -m MACHINEFILE, --machinefile MACHINEFILE
                        machine file for distributed runs (local_mpi only)

-p, --parallel¶: Run the executable in parallel

-m, --machinefile¶: File containing nodes used for a distributed MPI run. This option is ignored if job_scheduler is not local_mpi. This option has no effect if the parallel option is not used.

-l log_file, --log-file log_file¶: By default, a log file named <application>.log is created. This option allows the user to modify the behavior and create a differently named log file.

-d casedir, --case-dir casedir¶: By default, executables run from the current working directory. This option allows the user to modify the behavior and specify the path to the case directory.

caelus runpy – Run a custom python script¶

Runs a user-provided python script in the case directory. CPL ensures that the correct version of OpenFOAM or CML and python environment are setup prior to the invocation of the python script. Like caelus run, it is recommended that the arguments meant for the user script be separated from :program: caelus runpy arguments with --.

$ caelus runpy -h
usage: caelus runpy [-h] [-l LOG_FILE] [-d CASE_DIR]
                    script [script_args [script_args ...]]

Run a custom python script with OpenFOAM or CML and CPL environment

positional arguments:
  script                path to the python script
  script_args           additional arguments passed to command

optional arguments:
  -h, --help            show this help message and exit
  -l LOG_FILE, --log-file LOG_FILE
                        filename to redirect command output
  -d CASE_DIR, --case-dir CASE_DIR
                        path to the case directory

-l log_file, --log-file log_file¶: By default, a log file named <application>.log is created. This option allows the user to modify the behavior and create a differently named log file.

-d casedir, --case-dir casedir¶: By default, executables run from the current working directory. This option allows the user to modify the behavior and specify the path to the case directory.

caelus logs – process a solver log file from a run¶

Process a single solver log. The log file name is the one mandatory argument. Additional command arguments can be specified. By default, the log file is found in the current directory and the output is written to logs directory. The behavior can be modified to specify the case directory and output directory.

$ caelus logs -h
usage: caelus logs [-h] [-l LOGS_DIR] [-d CASE_DIR] [-p] [-f PLOT_FILE] [-w]
               [-i INCLUDE_FIELDS | -e EXCLUDE_FIELDS]
               log_file

Process logfiles for an OpenFOAM or Caelus run

positional arguments:
log_file               log file (e.g., simpleSolver.log)

optional arguments:
-h, --help             show this help message and exit
-l LOGS_DIR, --logs-dir LOGS_DIR
                       directory where logs are output (default: logs)
-d CASE_DIR, --case-dir CASE_DIR
                       path to the case directory
-p, --plot-residuals   generate residual time-history plots
-f PLOT_FILE, --plot-file PLOT_FILE
                       file where plot is saved
-w, --watch            Monitor residuals during a run
-i INCLUDE_FIELDS, --include-fields INCLUDE_FIELDS
                       plot residuals for given fields
-e EXCLUDE_FIELDS, --exclude-fields EXCLUDE_FIELDS

-l logs_dir, --logs-dir logs_dir¶: By default, the log files are output to logs. This option allows the user to modify the behavior and create a differently named log file output directory.

-d, case_dir, --case-dir case_dir¶: By default, the log file is found in the current working directory. This option allows the user to specify the path to the case directory where the log file exists.

-p, --plot-residuals¶: This option allows the user to plot and save the residuals to an image file.

-f plot_file, --plot-file plot_file¶: By default, plots are saved to residuals.png in the current working directory. This option allows the user to modify the behavior and specify a differently named plot file.

-w, --watch¶: This option allows the user to dynamically monitor residuals for a log file from an ongoing run. To exit before the completion of the run, hit Ctrl+C.

-i include_fields, --include-fields include_fields¶

By default, all field equation residuals are plotted. This option can be used to only include specific fields in residual plot. Multiple fields can be provided to this option. For example,

# Plot pressure and momentum residuals from simpleSolver case log
caelus logs -p -i "p Ux Uy Uz" simpleSolver.log

-e exclude_fields, --exclude-patterns exclude fields¶

By default, all field equation residuals are plotted. This option can be used to exclude specific fields in residual plot. Multiple fields be provided to this option. For example,

# Exclude TKE and omega residuals from simpleSolver case log
caelus logs -p -e "k epsilon" simpleSolver.log

caelus clean – clean a case directory¶

Cleans files generated by a run. By default, this function will always preserve system, constant, and 0 directories as well as any YAML or python files. The behavior can be modified to presevere additional files and directories.

$ caelus clean -h
usage: caelus clean [-h] [-d CASE_DIR] [-m] [-z] [-t] [-P] [-p PRESERVE]

Clean a case directory

optional arguments:
  -h, --help            show this help message and exit
  -d CASE_DIR, --case-dir CASE_DIR
                        path to the case directory
  -m, --clean-mesh      remove polyMesh directory (default: no)
  -z, --clean-zero      remove 0 directory (default: no)
  -t, --clean-time-dirs
                        remove time directories (default: no)
  -P, --clean-processors
                        clean processor directories (default: no)
  -p PRESERVE, --preserve PRESERVE
                        shell wildcard patterns of extra files to preserve

-d, case_dir, --case-dir case_dir¶: By default, the case directory is the current working directory. This option allows the user to specify the path to the case directory.

-m, --clean-mesh¶: By default, the polyMesh directory is not removed. This option allows the user to modify the behavior and remove the polyMesh directory.

-z, --clean-zero¶: By default, the 0 files are not cleaned. This option allows the user to modify the behavior and remove the 0 directory.

-t, --clean-time-dirs¶: Remove time directories from the case directory. Note, this only removes the reconstructed time directories and not the decomposed directores that exist within processor* directories.

-P, --clean-processors¶: Remove decomposed processor* directories from the case directory.

-p preserve_pattern, --preserve preserve_pattern¶: A shell-wildcard patterns of files or directories that will not be cleaned.

caelus build – Compile OpenFOAM or CML sources¶

caelus build is a wrapper that can be used to build executables for OpenFOAM or CML project and user directories. The command can be executed from any directory when building project or user directories. For CML, It determines the actual paths to the project and user directories based on the user configuration files, and the SCons configuration within those projects. For OpenFOAM, it assumes an Allwmake script exists in the target source directory. For either package, the user can override the default project and user directories by specifying the :option: –cml-version <cpl –cml-version> flag when invoking this command.

Warning

When using CPL with Python 3.x versions, you will need a recent version of CML to invoke caelus build. This is because the SCons versions shipped with CML versions v8.04 and older can only run on Python 2.x.

$ caelus build -h
usage: caelus build [-h] [-l LOG_FILE] [-c] [-j JOBS]
                    [-a | -p | -u | -d SOURCE_DIR]
                    [scons_args [scons_args ...]]

Compile OpenFOAM or Caelus CML

positional arguments:
  scons_args            additional arguments passed to SCons

optional arguments:
  -h, --help            show this help message and exit
  -l LOG_FILE, --log-file LOG_FILE
                       filename to redirect build output
  -c, --clean           clean CML build
  -j JOBS, --jobs JOBS  number of parallel jobs
  -a, --all             Build both project and user directories (default: no)
  -p, --project         Build Caelus CML project (default: no)
  -u, --user            Build user project (default: no)
  -d SOURCE_DIR, --source-dir SOURCE_DIR
                        Build sources in path (default: CWD)

The positional arguments are passed directly to SCons providing user with full control over how the SCons build must be handled. It is recommended that the user separate the optional arguments to caelus build command from the arguments that must be passed to SCons using double dashes (--).

-d, --source-dir¶: Build sources in the current working directory. This is the default option. If the user is in the top-level directory containing the SConstruct file, then it builds the entire project. If the user is in a sub-directory containing a SConscript file, then it just builds the libraries and executables defined in that directory and sub-directories. An example would be to recompile just the turbulence model libraries during development phase.

-p, --project¶: Build the sources in project directory only.

-u, --user¶: Build the sources in user directory only.

-a, --all¶: Build both the project and the user directories. The command will abort compilation if the compilation of the project files fail and will not attempt to build the sources in user directory.

-j, --jobs¶: The number of concurrent compilation jobs that must be launched with SCons. The default value is determined by the number of CPU cores available on the user’s system.

-c, --clean¶: Instead of recompiling the sources, execute the clean command through SCons.

caelus – Common CPL actions¶