ogstools.logparser package#

functions used by logparser.

ogstools.logparser.analysis_convergence_coupling_iteration(df)[source]#
Return type:

Any

ogstools.logparser.analysis_convergence_newton_iteration(df)[source]#

Convergence metrics need to be interpreted as norm |x|,`|dx|`, |dx|/|x| and are specific to defined <convergence_criterion> in prj - file.

Return type:

DataFrame

ogstools.logparser.analysis_simulation(df)[source]#
Return type:

DataFrame

ogstools.logparser.analysis_simulation_termination(df)[source]#
Return type:

DataFrame

ogstools.logparser.analysis_time_step(df)[source]#

Analysis with focus on computation time per time step. It combines time step specific measurements ‘output time’ and ‘time step solution time’ with iteration specific measurements ‘assembly time’, ‘linear solver time’, ‘Dirichlet time’. Time from iteration are accumulated.

Return type:

DataFrame

ogstools.logparser.convergence_order_per_ts_iteration(df, n=3)[source]#

Compute the convergence order of iterative solver errors.

\(q(n=3) = \frac{\log | \frac{x_{k-1}}{x_{k}} |}{\log | \frac{x_{k-2}}{x_{k-1}} |}\) \(q(n=4) = \frac{\log | \frac{x_{k+1}-x_{k}}{x_{k}-x_{k-1}} |}{\log | \frac{x_{k}-x_{k-1}}{x_{k-1}-x_{k-2}} |}\)

Return type:

ndarray

ogstools.logparser.errors_per_ts_iteration(df, metric='dx')[source]#
Return type:

ndarray

ogstools.logparser.fill_ogs_context(df_raw_log)[source]#

Only needed for logs of Version 1. Fill missing values in OpenGeoSys (OGS) log DataFrame by context. This function fills missing values in an OpenGeoSys (OGS) log DataFrame by context.

Parameters:

df_raw_log (DataFrame) – DataFrame containing the raw OGS log data. Usually, the result of pd.DataFrame(parse_file(file))

Returns:

pd.DataFrame with missing values filled by context.

Return type:

DataFrame

References: Pandas documentation : https://pandas.pydata.org/pandas-docs/stable/user_guide/

Notes: Some logs do not contain information about time_step and iteration. The information must be collected by context (by surrounding log lines from same mpi_process). Logs are grouped by mpi_process to get only surrounding log lines from same mpi_process. There are log lines that give the current time step (when time step starts). It can be assumed that in all following lines belong to this time steps, until next collected value of time step. Some columns that contain actual integer values are converted to float. See https://pandas.pydata.org/pandas-docs/stable/user_guide/integer_na.html ToDo list of columns with integer values are known from regular expression

ogstools.logparser.model_and_clock_time(df)[source]#

Process the dataframe of an OGS log for inspection of data over time.

The resulting dataframe’s index is ‘model_time’. The remaining columns consist of: ‘time_step’, ‘step_size’, ‘iterations’ and ‘clock_time’.

Parameters:

df (DataFrame) – The dataframe of an OGS log

Returns:

The processed dataframe.

Return type:

DataFrame

ogstools.logparser.ogs_regexes()[source]#

Defines regular expressions for parsing OpenGeoSys log messages.

Returns:

A list of tuples, each containing a regular expression pattern and the corresponding message class.

Return type:

list[tuple[str, type[Log]]]

ogstools.logparser.parse_file(file_name, maximum_lines=None, force_parallel=False)[source]#

Parses a log file from OGS, applying regex patterns to extract specific information,

The function supports processing files in serial or parallel mode. In parallel mode, a specific regex is used to match log entries from different processes.

Parameters:
  • file_name (str | Path) – The path to the log file, as a string or Path object.

  • maximum_lines (int | None) – Optional maximum number of lines to read from the file. If not provided, the whole file is read.

  • force_parallel (bool) – Should only be set to True if OGS run with MPI with a single core

Returns:

A list of extracted records based on the applied regex patterns. The exact type and structure of these records depend on the regex patterns and their associated processing functions.

Return type:

list[Any]

ogstools.logparser.plot_convergence(df, metric='dx', x_metric='time_step', **kwargs)[source]#

Create a heatmap of the nonlinear solver convergence data.

The individual values in the heatmap correspond to the top right indices on the x- and y-axis. E.g. the very first entry which fills the space between timesteps 0-1 and iteration 0-1 belongs to the first iteration of the first timestep. Thus we immediately read on which iteration a timestep converged and on which timestep the simulation ended. Per default logarithmic scaling is used. Set log_scale to False to use linear scaling.

Parameters:
  • df (DataFrame) – Dataframe of a simulation log.

  • metric (Literal['dx', 'dx_x', 'x']) – Which metric / column of the Dataframe to plot. dx (absolute error), dx_x (relative error), x (residual)

  • x_metric (Literal['time_step', 'model_time']) – x_axis can represent either “time_step” or “model_time”

Return type:

Figure

Keyword Arguments:
Returns:

A figure with a heatmap of the nonlinear solver convergence data.

Return type:

Figure

ogstools.logparser.plot_convergence_order(df, n=3, x_metric='time_step', **kwargs)[source]#

Create a heatmap of the nonlinear solver convergence order.

see: convergence_order_per_ts_iteration() In order to estimate the convergence order we need to take into account multiple values and thus cannot assign each iteration a convergence order. Only for iterations i of i >= n an order is calculated and plotted. Per default the scale is limited to a range of 0 to 2 to limit the view to meaningful data. Set the keyword arguments vmin and vmax`to `None to see the entire scale.

Parameters:
  • df (DataFrame) – Dataframe of a simulation log.

  • n (Literal[3, 4]) – Number of error values to use to estimate the convergence order.

  • x_metric (Literal['time_step', 'model_time']) – x_axis can represent either “time_step” or “model_time”

Return type:

Figure

Keyword Arguments:
Returns:

A figure with a heatmap of the nonlinear solver convergence order.

Return type:

Figure

ogstools.logparser.read_version(file)[source]#

Read the version of the OGS log file.

Parameters:

file (Path) – Path to the OGS log file.

Returns:

The version number as an integer.

Return type:

int

ogstools.logparser.time_step_vs_iterations(df)[source]#
Return type:

DataFrame

Submodules#