caelus.post – Post-processing utilities

Provides log analysis and plotting utilities

SolverLog	Caelus solver log file interface.
CaelusPlot	Caelus Data Plotting Interface

Caelus Log Analyzer

This module provides utilities to parse and extract information from solver outputs (log files) that can be used to monitor and analyze the convergence of runs. It implements the SolverLog class that can be used to access time histories of residuals for various fields of interest.

Example

>>> logs = SolverLog()
>>> print ("Available fields: ", logs.fields)
>>> ux_residuals = logs.residual("Ux")

The actual extraction of the logs is performed by LogProcessor which uses regular expressions to match lines of interest and convert them into tabular files suitable for loading with numpy.loadtxt or pandas.read_table.

class caelus.post.logs.LogProcessor(logfile, case_dir=None, logs_dir='logs')

Bases: object

Process the log file and extract information for analysis.

This is a low-level utility to parse log files and extract information using regular expressions from the log file. Users should interact with solver output using the SolverLog class.

Parameters:

• logfile (str) – Name of the Caelus log file
• casedir (path) – Path to the case directory (default: cwd)
• logs_dir (path) – Relative path to the directory where logs are written

add_rule(regexp, actions)

Add a user-defined rule for processing

Parameters:

• regexp (str) – A string that can be compiled into a regexp
• action (func) – A coroutine that can consume matching patterns

bounding_processor(**kwargs)

Process the bounding lines

completion_processor(**kwargs)

Process End line indicating solver completion

continuity_processor(**kwargs)

Process continuity error lines from log file

convergence_processor(**kwargs)

Process convergence information (steady solvers only)

courant_processor(**kwargs)

Process Courant Number lines

exec_time_processor(**kwargs)

Process execution/clock time lines

exiting_processor(**kwargs)

Process exiting option

extend_rule(line_type, actions)

Extend a pre-defined regexp with extra functions

The default action for LogProcessor is to output processed lines into files. Additional actions on pre-defined lines (e.g., “time”) can be hooked via this method.

Parameters:

• line_type (str) – Pre-defined line type
• actions (list) – A list of coroutines that receive the matching lines

fatal_error_processor(**kwargs)

Process CAELUS FATAL ERROR line

residual_processor(**kwargs)

Process a residual line and output data to the relevant file.

time_processor(**kwargs)

Processor for the Time line in log files

watch_file(target=None, wait_time=0.1)

Process a log file for an in-progress run.

This method takes one parameter, target, a coroutine that is called at the end of every timestep. See LogWatcher for an example of using target to plot residuals for monitoring the run.

Parameters:

• target (coroutine) – A consumer acting on the data
• wait_time (seconds) – Wait time between checking the log file for updates

bound_files = None

Open file handles for bounding outputs

case_dir = None

Absolute path to the case directory

converged = None

Flag indicating convergence message in logs

converged_time = None

Timestep when the steady state solver converged

current_state

Return the current state of the logs processor

failed = None

Flag indicating whether the solver failed

logfile = None

User-supplied log file (relative to case directory)

logs_dir = None

Absolute path to the directory containing processed logs

res_files = None

Open file handles for the residual outputs

solve_completed = None

Flag indicating solver completion in logs (if End is found)

subiter_map = None

(variable, subIteration) pairs tracking the number of predictor subIterations for each flow variable

time = None

Track the latest time that was processed by the utility

time_str = None

Time as a string (for output)

class caelus.post.logs.SolverLog(case_dir=None, logs_dir='logs', force_reload=False, logfile=None)

Bases: object

Caelus solver log file interface.

SolverLog extracts information from solver outputs and allows interaction with the log data as numpy.ndarray or pandas.Dataframe objects.

Parameters:

• case_dir (path) – Absolute path to case directory
• logs_dir (path) – Path to logs directory relative to case_dir
• force_reload (bool) – If True, force reread of the log file even if the logs were processed previously.
• logfile (file) – If force_reload, then log file to process

Raises:

RuntimeError – An error is raised if no logs directory is available and the user has not provided a logfile that can be processed on the fly during initialization.

bounding_var(field)

Return the bounding information for a field

continuity_errors()

Return the time history of continuity errors

residual(field, all_cols=False)

Return the residual time-history for a field

Caelus Plotting Utilities

This module provides the capability to plot various quantities of interest using matplotlib through CaelusPlot.

class caelus.post.plots.CaelusPlot(casedir=None, plotdir='results')

Bases: object

Caelus Data Plotting Interface

Currently implemented:

• Plot residual time history
• Plot convergence of forces and force coeffcients

Parameters:

• casedir (path) – Path to the case directory
• plotdir (path) – Directory where figures are saved

plot_force_coeffs_hist(plotfile=None, dpi=300, **kwargs)

Plot force coefficients

Parameters:

• func_object (str) – The function object used in controlDict
• plotfile – File to save plot (e.g., residuals.png)
• dpi – Resolution for saving plots (default=300)

plot_forces_hist(plotfile=None, dpi=300, **kwargs)

Plot forces

Parameters:

• func_object (str) – The function object used in controlDict
• plotfile – File to save plot (e.g., residuals.png)
• dpi – Resolution for saving plots (default=300)

plot_residuals_hist(plotfile=None, dpi=300, **kwargs)

Plot time-history of residuals for a Caelus run

Parameters:

• fields (list) – Plot residuals only for the fields in this list
• plotfile – File to save plot (e.g., residuals.png)
• dpi – Resolution for saving plots (default=300)

casedir = None

Path to the case directory

plot_continuity_errors = None

Flag indicating whether continuity errors are plotted along with residuals

plotdir = None

Path to plots output directory

solver_log = None

Instance of SolverLog

class caelus.post.plots.LogWatcher(logfile, case_dir=None)

Bases: object

Real-time log monitoring utility

Parameters:

• logfile (str) – Name of the Caelus log file
• casedir (path) – Path to the case directory (default: cwd)

continuity_processor(**kwargs)

Capture continuity errors for plot updates

plot_residuals(**kwargs)

Update plot for residuals

residual_processor(**kwargs)

Capture residuals for plot updates

skip_field(field)

Helper function to determine if field must be processed

time_processor(**kwargs)

Capture time array

plot_fields = None

List of fields to plot. If None, plots all available fields

skip_fields = None

List of fields to skip. If None, plots all available fields

time_array = None

Time array used for plotting data

class caelus.post.plots.PlotsMeta

Bases: type

Provide interactive and non-interactive versions of plot methods.

This metaclass automatically wraps methods starting with _plot such that these methods can be used in both interactive and non-interactive modes. Non-interactive modes are automatically enabled if the user provides a file name to save the resulting figure.

caelus.post.plots.make_plot_method(func)

Make a wrapper plot method

caelus.post.plots.mpl_settings(*args, **kwds)

Temporarily switch matplotlib settings for a plot