Caelus Python Library (CPL)¶
- Version:
v5.0.0
- Date:
Aug 17, 2025
Caelus Python Library is a companion package for interacting with OpenFOAM and its derivative Caelus CML open-source CFD packages. The library provides utilities for pre and post-processing, as well as automating various aspects of the CFD simulation workflow. Written in Python, it provides a consistent user-interface across the three major operating systems Linux, Windows, and Mac OS X ensuring that the scripts written in one platform can be quickly copied and used on other platforms.
Like CML, CPL is also an open-source library released under the Apache License Version 2.0 license. See Apache License Version 2.0 for more details on use and distribution.
This documentation is split into two parts: a user and a developer manual. New users should start with the user manual that provides an overview of the features and capabilities currently available in CPL, the installation process and examples of usage. The developer manual documents the application programming interface (API) and is useful for users and developers looking to write their own python scripts to extend functionality or add features to the library. See Introduction for more details.
User Manual¶
- Introduction
- Installing Caelus Python Library (CPL)
- Configuring Caelus Python Library
- Command-line Applications
- Common CLI options
- Available command-line applications
caelus– Common CPL actions- caelus cfg – Print CPL configuration
- caelus clone – Clone a case directory
- caelus tasks – run tasks from a file
- caelus run – run an executable in the appropriate environment
- caelus runpy – Run a custom python script
- caelus logs – process a solver log file from a run
- caelus clean – clean a case directory
- caelus build – Compile OpenFOAM or CML sources
caelus_sim– Parametric Run CLI- caelus_tutorials – Run tutorials
- Caelus Tasks
- Tutorials
Developer Manual¶
- Caelus Python API
- caelus.config – Caelus Configuration Infrastructure
- Caelus Python Configuration
CaelusCfgconfigure_logging()get_appdata_dir()get_caelus_root()get_config()get_cpl_root()get_default_config()rcfiles_loaded()reload_config()reset_default_config()search_cfg_files()- Caelus CML Environment Manager
CMLEnvFOAMEnvFOAMEnv.etc_file()FOAMEnv.from_modules()FOAMEnv.bin_dirFOAMEnv.build_dirFOAMEnv.build_optionFOAMEnv.environFOAMEnv.etc_dirsFOAMEnv.foam_api_infoFOAMEnv.foam_bashrcFOAMEnv.foam_versionFOAMEnv.lib_dirFOAMEnv.module_listFOAMEnv.mpi_bindirFOAMEnv.mpi_dirFOAMEnv.mpi_libdirFOAMEnv.project_dirFOAMEnv.rootFOAMEnv.site_dirFOAMEnv.site_libdirFOAMEnv.user_bindirFOAMEnv.user_dirFOAMEnv.user_libdirFOAMEnv.version
HelyxEnvHelyxEnv.etc_file()HelyxEnv.bin_dirHelyxEnv.build_dirHelyxEnv.build_optionHelyxEnv.environHelyxEnv.etc_dirsHelyxEnv.foam_bashrcHelyxEnv.lib_dirHelyxEnv.module_listHelyxEnv.mpi_bindirHelyxEnv.mpi_dirHelyxEnv.mpi_libdirHelyxEnv.project_dirHelyxEnv.site_dirHelyxEnv.site_libdirHelyxEnv.user_bindirHelyxEnv.user_dirHelyxEnv.user_libdirHelyxEnv.version
cml_get_latest_version()cml_get_version()discover_versions()get_cmlenv_instance()is_foam_var()
- caelus.utils – Basic utilities
- caelus.run – CML Execution Utilities
- Caelus Tasks Manager
TasksTasksMeta- CML Simulation
CMLSimBaseCMLSimBase.clean()CMLSimBase.clone()CMLSimBase.get_input_dict()CMLSimBase.load()CMLSimBase.save_state()CMLSimBase.LESPropertiesCMLSimBase.RASPropertiesCMLSimBase.basedirCMLSimBase.blockMeshDictCMLSimBase.casedirCMLSimBase.changeDictionaryDictCMLSimBase.cmlControlsCMLSimBase.controlDictCMLSimBase.decomposeParDictCMLSimBase.envCMLSimBase.fvSchemesCMLSimBase.fvSolutionCMLSimBase.nameCMLSimBase.parentCMLSimBase.run_configCMLSimBase.run_flagsCMLSimBase.transportPropertiesCMLSimBase.turbulencePropertiesCMLSimBase.udf
CMLSimCollectionCMLSimCollection.filter_cases()CMLSimCollection.load()CMLSimCollection.post()CMLSimCollection.prep()CMLSimCollection.save_state()CMLSimCollection.setup()CMLSimCollection.simulation_class()CMLSimCollection.solve()CMLSimCollection.status()CMLSimCollection.udf_instance()CMLSimCollection.basedirCMLSimCollection.case_namesCMLSimCollection.casedirCMLSimCollection.casesCMLSimCollection.envCMLSimCollection.nameCMLSimCollection.udfCMLSimCollection.udf_paramsCMLSimCollection.udf_script
CMLSimMetaCMLSimulationCMLSimulation.case_log()CMLSimulation.decompose_case()CMLSimulation.post_case()CMLSimulation.prep_case()CMLSimulation.reconstruct_case()CMLSimulation.run_tasks()CMLSimulation.solve()CMLSimulation.status()CMLSimulation.update()CMLSimulation.LESPropertiesCMLSimulation.RASPropertiesCMLSimulation.blockMeshDictCMLSimulation.changeDictionaryDictCMLSimulation.cmlControlsCMLSimulation.controlDictCMLSimulation.decomposeParDictCMLSimulation.fvSchemesCMLSimulation.fvSolutionCMLSimulation.job_idsCMLSimulation.logfileCMLSimulation.run_flagsCMLSimulation.solverCMLSimulation.task_fileCMLSimulation.transportPropertiesCMLSimulation.turbulenceProperties
- CML Parametric Run Manager
CMLParametricRuniter_case_params()normalize_variable_param()- Caelus Job Manager Interface
CaelusCmd- CML Execution Utilities
clean_casedir()clean_polymesh()clone_case()find_caelus_recipe_dirs()find_case_dirs()find_recipe_dirs()get_mpi_size()is_caelus_casedir()- Job Scheduler Interface
HPCQueueHPCQueue.nameHPCQueue.queueHPCQueue.accountHPCQueue.num_nodesHPCQueue.num_ranksHPCQueue.stdoutHPCQueue.stderrHPCQueue.join_outputsHPCQueue.mail_optsHPCQueue.email_addressHPCQueue.qosHPCQueue.time_limitHPCQueue.shellHPCQueue.mpi_extra_argsHPCQueue.delete()HPCQueue.get_queue_settings()HPCQueue.is_job_scheduler()HPCQueue.is_parallel()HPCQueue.prepare_mpi_cmd()HPCQueue.process_cml_run_env()HPCQueue.process_foam_run_env()HPCQueue.process_run_env()HPCQueue.submit()HPCQueue.update()HPCQueue.write_script()HPCQueue.queue_nameHPCQueue.script_body
PBSQueueParallelJobSerialJobSlurmQueuecaelus_execute()get_job_scheduler()python_execute()
- caelus.post – Post-processing utilities
- Post-processing interface
PostProcessing- Core function object utilities
DictMetaFuncObjMetaFunctionObjectFunctionObject.create()FunctionObject.funcobj_type()FunctionObject.enabledFunctionObject.executeControlFunctionObject.executeIntervalFunctionObject.latest_timeFunctionObject.libsFunctionObject.logFunctionObject.regionFunctionObject.rootFunctionObject.timeEndFunctionObject.timeStartFunctionObject.timesFunctionObject.writeControlFunctionObject.writeInterval
- Sets and surfaces sampling
SampledDataSampledSetSampledSetsSampledSurfaceSampledSurfacesSampling- Force and Force coefficients interface
ForceCoeffsForcesLiftDragLiftDrag.UinfLiftDrag.dragDirectionLiftDrag.liftDirectionLiftDrag.maxCpLiftDrag.minCpLiftDrag.nAveragingStepsLiftDrag.outputRegionDataLiftDrag.patchesLiftDrag.pitchAxisLiftDrag.porosityLiftDrag.referenceAreaLiftDrag.referenceLengthLiftDrag.rhoInfoLiftDrag.runOnLastIterOnlyLiftDrag.wheelbaseLiftDrag.writeFields
- Caelus Log Analyzer
LogProcessorLogProcessor.add_rule()LogProcessor.bounding_processor()LogProcessor.completion_processor()LogProcessor.continuity_processor()LogProcessor.convergence_processor()LogProcessor.courant_processor()LogProcessor.exec_time_processor()LogProcessor.exiting_processor()LogProcessor.extend_rule()LogProcessor.fatal_error_processor()LogProcessor.residual_processor()LogProcessor.time_processor()LogProcessor.watch_file()LogProcessor.bound_filesLogProcessor.case_dirLogProcessor.convergedLogProcessor.converged_timeLogProcessor.current_stateLogProcessor.failedLogProcessor.logfileLogProcessor.logs_dirLogProcessor.res_filesLogProcessor.solve_completedLogProcessor.subiter_mapLogProcessor.timeLogProcessor.time_str
SolverLog- Caelus Plotting Utilities
CaelusPlotLogWatcherPlotsMetamake_plot_method()mpl_settings()
- caelus.io – CML Input File Manipulation
- Caelus/OpenFOAM Input File Interface
BlockMeshDictChangeDictionaryDictCmlControlsControlDictControlDict.create_default_entries()ControlDict.adjustTimeStepControlDict.applicationControlDict.deltaTControlDict.endTimeControlDict.functionsControlDict.graphFormatControlDict.maxCoControlDict.purgeWriteControlDict.runTimeModifiableControlDict.startFromControlDict.startTimeControlDict.stopAtControlDict.timeFormatControlDict.timePrecisionControlDict.writeCompressionControlDict.writeControlControlDict.writeFormatControlDict.writeIntervalControlDict.writePrecision
DecomposeParDictDictFileDictMetaFvSchemesFvSolutionLESPropertiesPolyMeshBoundaryRASPropertiesTransportPropertiesTurbModelPropsTurbulencePropertiescml_std_files- Caelus/OpenFOAM Dictionary Implementation
CaelusDictBoundaryListCalcDirectiveCodeStreamDimStrDimValueDimensionDirectiveEvalDirectiveFieldFoamTypeListTemplateMacroSubstitutionMultipleValues- Caelus Input File Pretty-printer
DictPrinterIndenterfoam_writer()
- caelus.scripts – CLI App Utilities
- caelus.config – Caelus Configuration Infrastructure