Utilities Documentation

HELPR utility modules support parameter handling, plotting, postprocessing, and unit conversions.

parameter docu

Contains utilities for defining and managing parameter inputs.

class helpr.utilities.parameter.Parameter(name, value, lower_bound=0, upper_bound=np.inf, error_function=ValueError)

Bases: float

Class to enable checking and enforcing parameter bounds.

name
value
lower_bound
upper_bound
error_function
static check_size(obj, name)

Ensures object is a float, or extracts float from single element array or list.

Parameters:

  • obj (float, list, or np.ndarray) – Input object to check.

  • name (str) – Name of the parameter (for error reporting).

Returns:

The extracted or cast float value.

Return type:

float

Raises:

ValueError – If the input is a list/array with more than one element.

static parameter_bounds_check(name, value, lower_bound, upper_bound, error_function)

Checks that parameter values are within specified bounds.

Parameters:

  • name (str) – Name of the parameter.

  • value (float) – Value to check.

  • lower_bound (float) – Minimum acceptable value.

  • upper_bound (float) – Maximum acceptable value.

  • error_function (callable) – Function to raise in case of bound violation.

Raises:

error_function – If the value is not within the bounds.

helpr.utilities.parameter.get_length(data)

Returns the ‘length’ of the input data.

Parameters:

data (float, int, list, or np.ndarray) – Input data to evaluate.

Returns:

Length of the input if it’s a list or array; 1 if it’s a float or int.

Return type:

int

Raises:

ValueError – If the input is of an unsupported type.

plots docu

Provides plotting functions for simulation results and data visualization.

helpr.utilities.plots.ecdf(sample)

Calculates empirical cumulative distribution function (ECDF) for dataset.

Parameters:

sample – samples to be represented as an empirical cdf

Returns:

A tuple containing: - np.ndarray: The cumulative probabilities. - np.ndarray: The sorted quantiles of the sample.

Return type:

tuple

helpr.utilities.plots.failure_assessment_diagram_equation(load_ratio)

Calculates line from FAD equation. Eq. 9.22 on page 9-61 of API 579-1/ASME FFS-1, June, 2016 Fitness-For-Service

Parameters:

load_ratio (np.ndarray) – The load ratio values for which to calculate the FAD line.

Returns:

The calculated toughness ratio values corresponding to the input load ratios.

Return type:

np.ndarray

helpr.utilities.plots.failure_assessment_diagram_equation_v2(load_ratio)

Calculates line from FAD equation. Eq. supposed to be in API 579 2021 Fitness-For-Service

Parameters:

load_ratio (np.ndarray) – The load ratio values for which to calculate the FAD line.

Returns:

The calculated toughness ratio values corresponding to the input load ratios.

Return type:

np.ndarray

helpr.utilities.plots.generate_crack_growth_rate_plot(life_assessment, save_fig=False)

Creates a crack growth rate plot.

Parameters:

  • life_assessment (dict or DataFrame) – Single life assessment results.

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns the file path of the saved figure; otherwise, returns None.

Return type:

str or None

helpr.utilities.plots.generate_pipe_life_assessment_plot(life_assessment, postprocessed_criteria, criteria=None, pipe_name='', save_fig=False)

Generates deterministic life assessment plot.

Parameters:

  • life_assessment (dict or DataFrame) – Single pipe life assessment results.

  • postprocessed_criteria (dict or DataFrame) – Life criteria results.

  • criteria (list, optional) – QoI to plot (postprocessed_criteria keys)

  • pipe_name (str, optional) – Name of pipe to specify as title, defaults to no title.

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns a tuple containing the file path of the saved figure and the plot data; otherwise, returns None.

Return type:

tuple or None

helpr.utilities.plots.get_time_str()

Get date and time in ‘y m d - H M S’ format.

Returns:

The current date and time formatted as ‘y m d - H M S’.

Return type:

str

helpr.utilities.plots.plot_cycle_life_cdf_ci(analysis_results, criteria=None)
Creates a plot of confidence intervals around cdfs of analysis results.

criteria=None):

Parameters:

  • analysis_results (CrackEvolutionAnalysis) – Ensemble life assessment results.

  • criteria (list) – QoI to plot (postprocessed_criteria keys)

helpr.utilities.plots.plot_cycle_life_cdfs(analysis_results, criteria=None, save_fig=False)

Creates a plot with cdfs of analysis results.

Parameters:

  • analysis_results (CrackEvolutionAnalysis) – Ensemble life assessment results.

  • criteria (list) – QoI to plot (postprocessed_criteria keys)

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns a tuple containing the file path of the saved figure and the plot data; otherwise, returns None.

Return type:

tuple or None

helpr.utilities.plots.plot_cycle_life_criteria_scatter(analysis_results, criteria=None, color_by_variable=False, save_fig=False)

Creates scatter plots of cycle life QOI results.

If save_fig is True, the function returns the file-path string (when color_by_variable is False) or a list of file-paths (when color_by_variable is True).

Parameters:

  • analysis_results (CrackEvolutionAnalysis) – Ensemble life assessment results.

  • criteria (list) – QoI to plot (postprocessed_criteria).

  • color_by_variable (bool, optional) – When True each variable gets its own colour.

  • save_fig (bool, optional) – When True the plot is saved to a PNG file.

Returns:

  • If save_fig is True and color_by_variable is False, the file path of the saved figure.

  • If color_by_variable is True, a list of file paths - one for each variable.

Return type:

str or list of str

helpr.utilities.plots.plot_cycle_life_pdfs(analysis_results, criteria=None, save_fig=False)

Creates pdfs of life cycle analysis results.

Parameters:

  • analysis_results (CrackEvolutionAnalysis) – Ensemble life assessment results.

  • criteria (str) – Life criteria to plot, defaults to ‘Cycles to a (crit)’.

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns the file path of the saved figure; otherwise, returns None.

Return type:

str or None

helpr.utilities.plots.plot_det_design_curve(dk, da_dn, save_fig=False)

Creates a plot of design curve values exercised in an analysis.

Parameters:

  • dk (pandas.DataFrame) – Change in stress intensity factor.

  • da_dn (pandas.DataFrame) – Change of crack size over change in cycles (da/dn).

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns the file path of the saved figure; otherwise, returns None, None.

Return type:

str or None

helpr.utilities.plots.plot_failure_assessment_diagram(life_assessment, life_criteria, fad_type, nominal=False, nominal_life_criteria=False, save_fig=False)

Creates a failure assessment diagram (FAD).

Parameters:

  • life_assessment (dict) – Single or Ensemble life assessment results.

  • life_criteria (dict) – Single or Ensemble of postprocessed life criteria results.

  • fad_type (str) – Type of FAD calculations presented.

  • nominal (dict or bool, optional) – Nominal results and flag for nominal or probabilistic results.

  • nominal_life_criteria (dict or bool, optional) – Nominal postprocessed life criteria results.

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns the file path of the saved figure; otherwise, returns None.

Return type:

str or None

helpr.utilities.plots.plot_log_hist(data, label, logbins=None)

Create a log10-scale histogram of the given data.

Parameters:

  • data (list) – Data to bin and plot.

  • label (str) – Legend label for data.

  • logbins (np.ndarray, optional) – Option to pass in log spaced bins if already computed. Default is None.

Returns:

logbins – Bin locations in log10 spacing.

Return type:

np.array

helpr.utilities.plots.plot_mitigation_histograms(cycles_to_critical_crack, cycles_till_mitigation, save_fig=False)

Create histogram plots showing cracks failing over time and the impact of inspection.

Parameters:

  • cycles_to_critical_crack (list) – Cycle count at which crack reaches critical size.

  • cycles_till_mitigation (list) – Cycle count at which a crack was identified through inspection and mitigated

  • save_fig (bool, optional) – If True, the figure is saved as a PNG and file path is returned. Default is False.

Returns:

If save_fig is True, returns a tuple:

  • str: file path to the saved image

  • list of np.ndarray: histogram line data for plotting

If save_fig is False, returns (None, None).

Return type:

tuple or None

helpr.utilities.plots.plot_pipe_life_ensemble(life_assessment, criteria=None, save_fig=False)

Creates plot of ensemble pipe life assessment results.

Parameters:

  • life_assessment (CrackEvolutionAnalysis) – Ensemble life assessment results

  • criteria (list) – QoI to plot (postprocessed_criteria keys)

  • save_fig (bool, optional) – Flag to save plot to a png file.

Returns:

If save_fig is True, returns a tuple containing the file path of the saved figure and the plot data; otherwise, returns None.

Return type:

tuple or None

helpr.utilities.plots.plot_random_loading_profiles(minimum_pressure, maximum_pressure, pressure_units='MPa', cycle_description='Cycle [#]', save_fig=False)

Create plots showing random pressure loading and load ratio (R) in terms of cycles.

Parameters:

  • minimum_pressure (list) – Minimum pressure values for each cycle in pressure loading profile

  • maximum_pressure (list) – Maxium pressure values for each cycle in pressure loading profile

  • pressure_units (str) – Units of pressure values being plotted

  • cycle_description (str) – Label for x-axis describing units of pressure loading profile indices

  • save_fig (bool, optional) – If True, the figure is saved as a PNG and file path is returned. Default is False.

Returns:

If save_fig is True, returns a tuple:

  • str: file path to the saved image

  • list of np.ndarray: line data for plotting

If save_fig is False, returns (None, None).

Return type:

tuple or None

helpr.utilities.plots.plot_sensitivity_results(analysis_results, criteria=None, save_fig=False, filename='sensitivity')

Creates a plot of sensitivity results.

Parameters:

  • analysis_results (CrackEvolutionAnalysis) – Ensemble life assessment results.

  • criteria (str, optional) – Life criteria to plot, defaults to ‘Cycles to a (crit)’.

  • save_fig (bool, optional) – Flag to save plot to a png file.

  • filename (str, optional) – Base filename for saved plot. Defaults to ‘sensitivity’.

Returns:

If save_fig is True, returns the file path of the saved figure; otherwise, returns None.

Return type:

str or None

helpr.utilities.plots.plot_unscaled_mitigation_cdf(cycles_to_critical_crack, cycles_till_mitigation, save_fig=False)

Creates a plot of unscaled cdfs showing impact of inspection/mitigation.

Parameters:

  • cycles_to_critical_crack (list) – Cycle count at which crack reaches critical size

  • cycles_till_mitigation (list) – Cycle count at which a crack was identified through inspection and mitigated

  • save_fig (bool, optional) – If True, saves the plot as a PNG file and returns the file path and plot data Default is False.

Returns:

If save_fig is True, returns a tuple:

  • str: file path to saved image

  • list of np.ndarray: line data from the plotted CDFs

If save_fig is False, returns (None, None)

Return type:

tuple or None

postprocessing docu

Utilities for cleaning, summarizing, and transforming simulation outputs.

helpr.utilities.postprocessing.calc_pipe_life_criteria(cycle_results, pipe, material)

Calculates overall pipe life criteria.

Parameters:

  • cycle_results (list of dicts) – Complete load cycling results.

  • pipe (Pipe) – Pipe specification

  • material (object or list of objects) – Object or list of objects with attribute fracture_resistance.

Returns:

Aggregated life criteria results: - ‘a(crit)’ : list of critical crack depths - ‘Cycles to a(crit)’ : [list of cycles, list of a/t values] - ‘Cycles to 25% a(crit)’ : [list of cycles, list of a/t values] - ‘Cycles to 1/2 Nc’ : [list of cycles, list of a/t values]

Return type:

dict

Raises:

UserWarning – If critical conditions are not met and default values are used.

helpr.utilities.postprocessing.determine_qoi_values(crack_instance, fracture_resistance, wall_thickness)

Helper function to determine quality of interest values.

Parameters:

  • crack_instance (dict) – Dictionary with crack growth data containing keys like ‘Kmax’, ‘Kres’, ‘a (m)’, and ‘Total cycles’.

  • fracture_resistance (float) – Critical fracture resistance (MPa√m).

  • wall_thickness (float) – Wall thickness of the pipe (m).

Returns:

  • life_criteria (dict) – Dictionary containing: - a(crit): critical crack depth - Cycles to a(crit): total cycles and a/t value - Cycles to 25% a(crit): total cycles and a/t value - Cycles to 1/2 Nc: total cycles and a/t value

  • warning_1 (bool) – True if a_crit was not reached and max a/t < 0.8.

  • warning_2 (bool) – True if Kmax + Kres < fracture resistance but max a/t >= 0.8.

helpr.utilities.postprocessing.find_intersection(load_ratio_data, toughness_ratio_data, cycles, a_over_t)

Finds the intersection point where the toughness ratio exceeds the FAD values.

Parameters: - load_ratio_data: Array of load ratios. - toughness_ratio_data: Array of toughness ratios. - cycles: Array of total cycles corresponding to load ratios. - a_over_t: Array of a/t values corresponding to load ratios.

Returns: - A dictionary containing the intersection details or a message if no intersection is found.

helpr.utilities.postprocessing.report_single_cycle_evolution(all_results, pipe_index)

Creates a DataFrame object for plotting a single crack cycle evolution.

Parameters:

  • all_results (list of dicts) – All load cycling results.

  • pipe_index (int) – Index of single pipe instance.

Returns:

single_cycle_evolution – DataFrame for plotting of single instance.

Return type:

pd.DataFrame

helpr.utilities.postprocessing.report_single_pipe_life_criteria_results(life_results, pipe_index)

Reports pipe life criteria results for single instance.

Parameters:

  • life_results (dict) – Complete load cycling results.

  • pipe_index (int) – Index of single pipe instance.

Returns:

pipe_life – Collected life criteria results.

Return type:

pandas.DataFrame

saving docu

Functions for saving analysis results.

helpr.utilities.saving.capitalize_rules(value: str, name: list)

Enforces capitalization rules for multi-word strings.

Parameters:

  • value (str) – Individual word from a variable name.

  • name (list) – The full name split into words.

Returns:

Capitalized or original string based on context.

Return type:

str

helpr.utilities.saving.check_for_units(value: str)

Checks for brackets in strings to indicate unit values.

Parameters:

value (str) – The string to check.

Returns:

True if the string contains brackets indicating units, False otherwise.

Return type:

bool

helpr.utilities.saving.clean_results_names(results)

Cleans up variable names for saving to csv.

Parameters:

results (CrackEvolutionAnalysis) – Results of crack evolution analysis stored in associated object

Returns:

Dictionary mapping original result keys to cleaned names.

Return type:

dict

helpr.utilities.saving.save_deterministic_results(results, folder_name)

Saves deterministic results to a csv file. CSV file has nominal input parameters specified first, then subset of cycle evolution results

Parameters:

  • results (CrackEvolutionAnalysis) – Results of crack evolution analysis stored in associated object

  • folder_name (str) – Folder to store csv into

helpr.utilities.saving.save_life_criteria_data(life_criteria, folder_name, study_type='nominal')

Save pipe life criteria results to a CSV file.

Parameters:

  • life_criteria (dict) – Dictionary of life criteria outputs from crack evolution analysis.

  • folder_name (str) – Directory path where the CSV file will be saved.

  • study_type (str, optional) – Type of analysis (‘nominal’ or ‘probabilistic’), by default ‘nominal’.

helpr.utilities.saving.save_parameter_characterizations(results, folder_name)

Saves deterministic or probabilistic parameter characterizations used in analysis to a csv file.

Parameters:

  • results (CrackEvolutionAnalysis) – Results of crack evolution analysis stored in associated object

  • folder_name (str) – Folder to store csv into.

helpr.utilities.saving.save_probabilistic_results(results, folder_name)

Saves probabilistic results to a csv file.

Parameters:

  • results (CrackEvolutionAnalysis) – Results of crack evolution analysis stored in associated object

  • folder_name (str) – Folder to store csv into.

unit_conversion docu

Functions for converting between different physical units.

Common unit conversion functions.

helpr.utilities.unit_conversion.convert_in_to_m(inch_value: float) → float

Converts inches to meters.

Parameters:

inch_value (float) – The value in inches to be converted.

Returns:

The converted value in meters.

Return type:

float

helpr.utilities.unit_conversion.convert_ksi_to_mpa(ksi_value: float) → float

Converts KSI to MPa.

Parameters:

ksi_value (float) – The value in KSI to be converted.

Returns:

The converted value in MPa.

Return type:

float

helpr.utilities.unit_conversion.convert_psi_to_mpa(psi_value: float) → float

Converts PSI to MPa.

Parameters:

psi_value (float) – The value in PSI to be converted.

Returns:

The converted value in MPa.

Return type:

float

helpr.utilities.unit_conversion.get_variable_units(variable_name: str, for_plotting: bool = True) → str

Specifies units used for analysis variables

Parameters:

  • variable_name (str) – The name of the variable for which to retrieve the units.

  • for_plotting (bool, optional) – A flag indicating whether the units are for plotting (default is True).

Returns:

A string representing the units of the specified variable.

Return type:

str