CPL provides a tasks interface to automate various aspects of the CFD simulation workflow that can be executed by calling caelus tasks (see tasks documentation).
The tasks interface requires a list of tasks provided in a YAML-formatted file
as shown below (
tasks: - clean_case: remove_zero: no remove_mesh: yes - run_command: cmd_name: blockMesh - run_command: cmd_name: pisoSolver - process_logs: log_file: pisoSolver.log plot_residuals: true residuals_plot_file: residuals.pdf residuals_fields: [Ux, Uy]
The file lists a set of actions to be executed sequentially by caelus tasks. The tasks can accept various options that can be used to further customize the workflow. A sample interaction is shown below
$ caelus -v tasks -f caelus_tasks.yaml INFO: Caelus Python Library (CPL) v0.1.0 INFO: Caelus CML version: 7.04 INFO: Loaded tasks from: cavity/caelus_tasks.yaml INFO: Begin executing tasks in cavity INFO: Cleaning case directory: cavity INFO: Executing command: blockMesh INFO: Executing command: pisoSolver INFO: Processing log file: pisoSolver.log INFO: Saved figure: cavity/residuals.pdf INFO: Residual time history saved to residuals.pdf INFO: Successfully executed 4 tasks in cavity INFO: All tasks executed successfully.
For a comprehensive list of task file examples, please consult the
run_tutorial.yaml files in the
tutorials directory of Caelus CML
distribution. In particular, the
tutorials/incompressible/pimpleSolver/les/motorBike case provides an
example of a tasks workflow involving two different case directories.
This section documents the various tasks available currently within CPL and the options that can be used to customize execution of those tasks.
- The task file must be in YAML format, and must contain one entry
tasksthat is a list of tasks to be executed.
- The tasks are executed sequentially in the order provided until an error is encountered or all tasks are executed successfully.
- The tasks must be invoked from within a valid Caelus case directory (see
task_setfor an exception). All filenames in the task file are interpreted relative to the execution directory where the command is invoked.
run_command – Run OpenFOAM or CML executables¶
This task type is used to execute an OpenFOAM or Caelus CML executable (e.g.,
blockMesh or pimpleSolver). CPL will ensure that the
appropriate version of OpenFOAM or CML is selected and the runtime enviornment
is setup properly prior to executing the task. The task must provide one mandatory
run_command.cmd_name that is the name of the OpenFOAM or CML
executable. Several other options are available and are documented below. Example:
- run_command: cmd_name: potentialSolver cmd_args: "-initialiseUBCs -noFunctionObjects" parallel: true
The name of the CML executable. This option is mandatory.
Extra arguments that must be passed to the OpenFOAM or CML executable. It is recommended that arguments be enclosed in a double-quoted string. Default value is an empty string.
The filename where the output of the command is redirected. By default, it is the OpenFOAM or CML executable name with the
.logextension appended to it. The user can change this to any valid filename of their choice using this option.
A Boolean flag indicating whether the executable is to be run in parallel mode. The default value is
parallelis True, then the default options for job scheduler are used from CPL configuration file, but can be overriden with additional options to
The number of MPI ranks for a parallel run.
run_python – Run user python scripts¶
This task will run a python script within the case directory. Like
run_command task, CPL will ensure that the apporpriate OpenFOAM or CML
version as well as python environment is setup correctly prior to invoking the
script. The task must provide one mandatory parameter
that contains the path to the python script to be executed. User can pass
additional options to this task as documented below.
- run_python: script: "../mytestscript.py" script_args: "-v -f option1 arg1 arg2" log_file: "mycustom.log"
Path to the custom python script.
Arguments that must be passed to the python script during invocation. As with
run_commandquote the arguments appropriately to ensure that it is passed correctly to the script.
The filename where the outputs and error messages from the script is redirected.
copy_files – Copy files¶
This task copies files in a platform-agnostic manner.
A unix-style file pattern that is used to match the pattern of files to be copied. The path to the files must be relative to the execution directory, but can exist in other directories as long as the relative paths are provided correctly. If the pattern matches multiple files, then
copy_files.destmust be a directory.
The destination where the files are to be copied.
copy_tree – Recursively copy directories¶
This task takes an existing directory (
src) and copies it to the
destination. Internally, this task uses copytree function to copy the directory, please refer to
Python docs for more details.
If the destination directory already exists, the directory is deleted before copying the contents of the source directory. Currently, this task does not provide a way to copy only non-existent files to the destination. Use with caution.
The source directory that must be recursively copied.
The pathname for the new directory to be created.
A list of Unix-style file patterns used to ignore files present in source directory when copying it to destination. A good example of this is to prevent copying the contents of
polyMeshwhen copying the contents of
constantfrom one case directory to another.
A Boolean flag indicating whether symbolic links are preserved when copying. Linux and Mac OSX only.
clean_case – Clean a case directory¶
Use this task to clean up a case directory after a run. By default, this task
will preserve all YAML and python files found in the case directory as well as
0/ directory. For example,
- clean_case: remove_zero: yes remove_mesh: no preserve: [ "0.org" ]
Boolean flag indicating whether the
0/directory should be removed. The default value is
Boolean flag indicating whether the
constant/polyMeshdirectory should be removed. The default value is
Boolean flag indicating whether time directories from a previous run should be removed. The default value is
Boolean flag indicating whether processor directories from a previous run should be removed. The default value is
A Boolean flag when enabled will set
A shortcut to set
A list of Unix-style file patterns that match files that should be preserved within the case directory.
process_logs – Process solver outputs¶
This task takes one mandatory argument
log_file that contains the outputs from a CFD run. The
time-histories of the residuals are extracted and output to files that can be
loaded by gnuplot, or loaded in python using loadtxt command
or using Pandas library. Users can also plot the residuals by using the
plot_residuals option. For example,
- process_logs: log_file: pimpleSolver.log log_directory: pimpleSolver_logs - process_logs: log_file: simpleSolver.log plot_residuals: yes residuals_plot_file: residuals.pdf residuals_fields: [Ux, Uy, p]
The filename containing the solver residual ouputs. This parameter is mandatory.
The directory where the processed residual time-history outputs are stored. Default:
logswithin the execution directory.
Boolean flag indicating whether a plot of the convergence time-history is generated. Default value is
The file where the plot is saved. Default value is
residuals.png. The user can use an appropriate extension (e.g.,
.jpg) to change the image format of the plot generated.
A list of fields that are plotted. If not provided, all fields available are plotted.
A Boolean flag indicating whether time-history of continuity errors are plotted along with residuals.
task_set – Group tasks¶
task_set groups a sub-set of tasks that can be executed in a different
Download an example.
The path to a valid case directory where the sub-tasks are to be executed. This parameter is mandatory.
A unique name to identify this task group.
The list of sub-tasks. This list can contain any of the tasks that have been documented above.