`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
`env`	Generate an environment file for sourcing within bash or csh shell
`clone`	Clone a case directory
`tasks`	Automatic execution of workflow from a YAML file
`run`	Run a CML executable in the appropriate environment
`logs`	Parse a solver log file and extract data for analysis
`clean`	Clean a case directory after execution

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 env – write shell environment file¶

Write a shell environment file to be sourced/called by the platform specific shell. This will be a combination of all the options loaded from the configuration files described in configuration section. The output can be redirected to a directory by using the caelus env -d option. This is useful for legacy workflows.

$ caelus env -h
usage: caelus env [-h] [-d WRITE_DIR]

Write environment variables that can be sourced into the SHELL environment

optional arguments:
  -h, --help            show this help message and exit
  -d WRITE_DIR, --write-dir WRITE_DIR
                        Path where the environment files are written

-d write_dir, --write_dir write_dir¶: Save the environment file to the write_dir instead of the current working directory

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 a Caelus executable in the appropriate environment¶

Run a single Caelus 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"

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

Run a Caelus executable in the correct environment

positional arguments:
  cmd_name              name of the Caelus 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

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

-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 Caelus solver log file from a run¶

Process a single Caelus 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 a 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 a currently run.

-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 Caelus 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] [-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
    -z, --clean-zero   remove 0 directory
    -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.

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

caelus – Common CPL actions¶