Physics Documentation

api docu

class helpr.physics.api.CrackEvolutionAnalysis(outer_diameter, wall_thickness, flaw_depth, max_pressure, min_pressure, temperature, volume_fraction_h2, yield_strength, fracture_resistance, flaw_length, crack_growth_model=None, delta_c_rule=None, stress_intensity_method=None, surface=None, aleatory_samples=0, epistemic_samples=0, sample_type='deterministic', random_seed=None, max_cycles=None, cycle_step=None)

Class to hold API capability for carrying out pipeline fracture and fatigue analyses.

crack_growth_model

max_cycles

cycle_step

nominal_input_parameter_values

sampling_input_parameter_values

number_of_aleatory_samples

number_of_epistemic_samples

sample_type

uncertain_parameters

random_seed

nominal_load_cycling

Results from crack growth analysis for a deterministic (single) pipe instance.

Type:: dict

nominal_life_criteria

Life criteria results for a deterministic (single) pipe instance.

Type:: dict

nominal_stress_state

Deterministic stress state specification.

Type:: GenericStressState

load_cycling

Results from crack growth analysis for all samples in a probabilistic study.

Type:: dict

life_criteria

Life criteria results for all samples in a probabilistic study.

Type:: dict

stress_state

Probabilistic stress state specification.

Type:: GenericStressState

ex_rates_plot

Filepath to generated rate plot.

Type:: str or None

crack_growth_plot

Filepath to generated crack growth plot.

Type:: str or None

apply_inspection_mitigation(probability_of_detection, detection_resolution, inspection_frequency, criteria)

Run inspection and mitigation analysis on crack evolution results.

Parameters:

probability_of_detection (float) – Probability of a crack being detected at each inspection.
detection_resolution (float) – Crack depth that is detectable by inspection. For example, a value of 0.3 indicates any crack larger than 30% of wall thickness is detectable.
inspection_frequency (int) – Number of cycles between each inspection. For example, a 4-year inspection interval would have a frequency of 4 * 365 cycles.
criteria (str) – Failure criteria to select from life criteria results.

Returns:

mitigated – List of bool values for each sample indicating whether or not the failure was mitigated.

Return type:

list

assemble_failure_assessment_diagram(save_fig=False)

Creates failure assessment diagram.

Parameters:: save_fig (bool, optional) – Flag for saving the diagram to a png file.

static capitalize_rules(value: str, name: list): Enforces capitalization rules for multi-word strings.

static check_for_units(value: str): Checks for brackets in strings to indicate unit values.

check_parameter_names(): Function to ensure parameter object names match assigned parameter.

clean_results_names(): Cleans up variable names for saving to csv.

collect_intermediate_variables(analysis_modules, nominal=False): Extracts intermediate variable values from analysis for pre and post processing steps

execute_crack_growth_analysis(analysis_modules): Starts the process running crack growth analysis.

gather_single_crack_cycle_evolution(single_pipe_index=None)

Gets results for a single pipe crack growth analysis from an ensemble analysis.

Parameters:: single_pipe_index (int, optional) – Index of requested pipe. Defaults to None.
Returns:: DataFrame of single pipe analysis results.
Return type:: pandas.DataFrame

gen_random_seed(random_seed): Sets random seed for recreating.

generate_input_parameter_plots(save_figs=False): Creates plots of the samples of the input parameters.

generate_probabilistic_results_plots(plotted_variable)

Creates ensemble of plots for probabilistic analysis results.

Parameters:: plotted_variable (str) – Pipe life criteria to plot.

get_design_curve_plot(): Returns plot ready for GUI display.

get_random_seed(): Returns the random seed value.

perform_deterministic_study(): Performs a deterministic analysis. Calculates crack growth evolution and then failure assessment

perform_probabilistic_study(): Performs a probabilistic analysis. Calculates crack growth evolution and then failure assessment

perform_study(): Starts crack evolution analysis study.

postprocess_single_crack_results(single_pipe_index=None, save_figs=False)

Postprocesses a single pipe’s results from an ensemble analysis. If no pipe index is specified, nominal results are shown.

Parameters:

single_pipe_index (int, optional) – Index of requested pipe. Defaults to None.
save_figs (bool, optional) – Flag that enables saving plots to png files. Defaults to False.

print_nominal_intermediate_variables(): Prints nominal values of intermediate variables

save_deterministic_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:: folder_name (str) – Folder to store csv into

save_parameter_characterizations(folder_name)

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

Parameters:: folder_name (str) – Folder to store csv into.

save_probabilistic_results(folder_name)

Saves probabilistic results to a csv file.

Parameters:: folder_name (str) – Folder to store csv into.

save_results(folder_name=None, output_dir=None)

Saves crack evolution simulation results.

Parameters:

folder_name (str, optional) – Folder name to store results into. Defaults to ‘Results/’.
output_dir (str, optional) – Directory path for creating the results folder. Defaults to current working directory.

set_random_state(): Sets up the random state.

setup_crack_growth_analysis(parameter_value_dict, sample_size): Creates the underlying modules for the crack growth analysis.

setup_deterministic_study(): Setup modules for deterministic analysis.

setup_probabilistic_study(): Setup modules for probabilistic analysis.

setup_study(): Setup crack evolution analysis modules.

static specify_study(input_parameters, aleatory_samples, epistemic_samples, sample_type, random_state): Builds up study framework in terms of study type, sample size distribution type, and uncertainty classification.

crack_growth docu

class helpr.physics.crack_growth.CrackGrowth(environment, growth_model_specification, sample_size=1)

Definition for crack growth physics model.

environment_specification

model_arguments

sample_size

delta_k

delta_a

delta_n

calc_air_curve_da(c=6.89E-12, m=3): Calculates delta a (change in crack size) from air curve.

calc_air_curve_dn(c=6.89E-12, m=3): Calculates delta n (change in # of cycles) from air curve.

calc_change_in_crack_size(delta_n, delta_k): Calculates the change in crack size given delta_k.

calc_code_case_2938_da_higher_k(parameter=1.5E-11, m=3.66, multiplier=2): Calculates delta a (change in crack size) for higher k values following code case 2938 (stress driven).

calc_code_case_2938_da_lower_k(parameter=3.5E-14, m=6.5, multiplier=0.4286): Calculates delta a (change in crack size) for lower k values following code case 2938 (hydrogen driven).

calc_code_case_2938_dn_higher_k(parameter=1.5E-11, m=3.66, multiplier=2): Calculates delta n (change in # of cycles) for higher k values following code case 2938 (stress driven).

calc_code_case_2938_dn_lower_k(parameter=3.5E-14, m=6.5, multiplier=0.4286): Calculates delta n (change in # of cycles) for lower k values following code case 2938 (hydrogen driven).

calc_da_code_case_2938(): Uses code case 2938 to calculate delta A.

calc_da_paris_law(c, m): Calculates delta a (change in crack size) from general paris law form.

calc_delta_n(delta_a, delta_k): “Calculates delta N (change in number of cycles).

calc_dn_code_case_2938(): Uses code case 2938 to calculate delta N.

calc_dn_paris_law(c, m): Calculates delta n (change in # of cycles) from general paris law form.

calc_fugacity_correction(p, multiplier, case): Calculates hydrogen fugacity correction for delta n (change in # of cycles).

get_single_crack_growth_model(sample_index)

Creates a crack growth object for a single instance from ensemble.

Parameters:: single_pipe_index (int) – Index of requested pipe instance.

helpr.physics.crack_growth.get_design_curve(specified_r, specified_fugacity, crack_growth_model=None, samples=99)

Extracts ASME design curves from model.

Parameters:

specified_r (float) – R value.
specified_fugacity (float) – Fugacity coefficient.
crack_growth_model (CrackGrowth, optional) – Specified crack growth model, defaults to code case 2938.
samples (int, optional) – Number of samples.

Returns:

delta_k (list) – List of delta K values.
da_dn (list) – List of delta A / delta N values.

crack_initiation docu

class helpr.physics.crack_initiation.DefectSpecification(flaw_depth, flaw_length, surface='inside', sample_size=1, location_factor=1)

Definition of crack initiation physics.

flaw_depth

flaw_length

surface

location_factor

get_single_defect(sample_index)

Returns single defect instance from ensemble defect object.

Parameters:: sample_index (int) – Index of requested pipe instance.
Returns:: Specification for the pipe instance.
Return type:: DefectSpecification

cycle_evolution docu

class helpr.physics.cycle_evolution.CycleEvolution(pipe, stress_state, defect, environment, material, crack_growth_model, delta_c_rule='proportional')

Class for running fatigue evolution analysis.

pipe_specification

stress_state

defect_specification

environment_specification

material_specification

number_of_pipe_instances

crack_growth

cycle_dict

Dictionary of pandas Series containing all cycle results.

Type:: dict

cycle

Dictionary containing data for the current cycle.

Type:: dict

calc_delta_k(k_max): Calculates delta k value.

calc_k_max_f_q(phi=np.pi / 2, previous_step_values=False): Calculates k_max, f, and q values.

calc_life_assessment(max_cycles=None, cycle_step=None)

Runs a fatigue crack life assessment analysis.

Parameters:

max_cycles (int or None, optional) – Maximum number of cycles to run the life assessment for before stopping. If None, the assessment will run until instances reach a/t > 0.8. Note that an assessment may stop before reaching max_cycles if all instances reach a/t > 0.8 before that number of cycles. Default is None.
cycle_step (float or None, optional) – Number of cycles to iterate by at each evaluation step. If None, the number of cycles will be dynamically adjusted each iteration based on the crack growth. Default is None.

Returns:

cycle_dict – Complete dict of results for all samples.

Return type:

dict

static change_a_over_t_step_size(current_step_size, change_in_a_over_t): Calculates a/t step size.

check_stopping_criteria(max_cycles): Determines whether to stop life assessment based on current crack conditions and the maximum number of cycles.

compute_cycle_at(): Computes results for single a/t cycle.

compute_cycle_n(cycle_step): Computes results for an explicit number of cycles.

create_clean_cycle(): Resets the cycle dictionary.

create_cycle_dict(): Initialize dictionary to store full fatigue crack analysis

initialize_c(): Initializes value of c based on initial a/c ratio in stress state module

initialize_cycle_dict(): Sets up initial cycle dictionary.

selecting_a_over_t_step_size(): Adaptively calculates a/t step size.

step_through_cycles(max_cycles, cycle_step): Main loop for stepping through cycles in fatigue crack analysis

update_a(): Calculates current crack depth (a) value.

update_a_over_t(): Calculates current a/t value.

update_c(): Calculates current crack width (c) value.

update_c_through_delta_k(): Updates cycle values for c, eta, k_max, f, q, and delta k.

update_cycle_dict(): Inserts single cycle results into overall analysis results.

update_delta_a(): Calculates current delta a value.

update_delta_k(): Updates delta k value at current cycle.

update_delta_n(): Calculates current delta n value.

update_k_max_f_q(): Updates k_max, f, and q values at current cycle.

update_total_cycles(): Calculates current cycle count.

environment docu

class helpr.physics.environment.EnvironmentSpecification(max_pressure, min_pressure, sample_size=1, temperature=293, volume_fraction_h2=1, reference_pressure=106)

Pipe interior environment specification.

max_pressure

min_pressure

temperature

volume_fraction_h2

reference_pressure

fugacity

Fugacity coefficient of blended gas.

Type:: float

reference_fugacity

Fugacity coefficient of pure H2.

Type:: float

fugacity_ratio: (fugacity / reference fugacity) ** 1/2.

r_ratio

Max pressure / min pressure.

Type:: float

calc_derived_quantities(): Calculates other attributes based on input parameters.

calc_fugacity(pressure, temperature, volume_fraction_h2): Calculates fugacity.

static calc_fugacity_coefficient(pressure, temperature, co_volume=15.84)

Calculates fugacity using Abel-Noble EOS Reference Pressure.

Parameters:

pressure (float) – Pressure [MPa].
temperature (float) – Temperature [K].
co_volume (float, optional) – CO volume (b), defaults to 15.84 [cm^3/mol].

Returns:

reference_pressure

Return type:

float

calc_fugacity_ratio(): Calculates fugacity ratio.

calc_r_ratio(): Calculates r ratio.

get_single_environment(sample_index)

Extracts a single environment instance from an ensemble.

Parameters:: sample_index (int) – Index of requested pipe instance.
Returns:: Specification for the pipe instance.
Return type:: EnvironmentSpecification

fracture docu

class helpr.physics.fracture.FailureAssessment(fracture_resistance, yield_stress)

Class for failure assessment calculations.

fracture_resistance

yield_stress

assess_failure_state(primary_stress_intensity_factor, primary_reference_stress_solution, crack_depth, crack_length, secondary_stress_intensity_factor=None, zeta_file=os.path.join(path, '../data/Table_9.3.nc')): function to calculate location of failure assessment diagram

calc_toughness_ratio_api(load_ratio, primary_stress_intensity_factor, crack_depth, crack_length, secondary_stress_intensity_factor, zeta_file): calculates the toughness ratio to use in a failure assessment diagram using the level 2 assessment from API 579-1.

helpr.physics.fracture.path = '/home/runner/work/helpr/helpr/src/helpr/physics': Module to hold fracture assessment diagram (FAD) functionality

inspection_mitigation docu

class helpr.physics.inspection_mitigation.InspectionMitigation(probability_of_detection, detection_resolution, inspection_frequency)

Inspection Mitigation - Determine when a pipe is inspected for cracks and mitigate cracks identified through inspection.

probability_of_detection

detection_resolution

inspection_frequency

determine_inspection_indices(cycle_count: DataFrame, number_of_inspections: int, inspection_array: array) → DataFrame

Identifies indices corresponding to cycle counts of interest.

Parameters:

cycle_count (pandas.DataFrame) – DataFrame of cycle count results.
number_of_inspections (int) – Total number of inspections.
inspection_array (numpy.ndarray) – Array of cycle counts at each inspection time.

Returns:

inspection_indices – Indices for cycle data corresponding to inspection times.

Return type:

pandas.DataFrame

determine_inspection_schedule(cycle_count: DataFrame) → tuple[int, array]

Determines inspection schedule based based on inspection frequency and highest number cycle count in results.

Parameters:

cycle_count (pandas.DataFrame) – DataFrame of cycle count results.

Returns:

number_of_inspections (int) – Total number of inspections.
inspection_array (numpy.ndarray) – Array of cycle counts at each inspection time.

inspect_then_mitigate(load_cycling: dict, failure_criteria: np.array, random_state=npr.default_rng())

Performs inspection and mitigation analysis on crack evolution results.

Parameters:

load_cycling (dict) – Analysis load cycling results.
failure_criteria (numpy.ndarray) – Analysis failure criteria.
random_state (numpy.random, optional) – Random state, defaults to standard numpy rng.

Returns:

mitigated (list) – List of bool values for each sample indicating whether or not the failure was mitigated.
mitigation (dict) – Dict of Series describing each sample’s mitigation results.

helpr.physics.inspection_mitigation.inspect_crack(inspection_indices: Series, crack_size: Series, failure_criteria: float, detection_resolution: float, inspection_array: DataFrame, cycle_count: DataFrame) → Series: Determines if inspected crack is detectable.

helpr.physics.inspection_mitigation.mitigate_crack(detectable: Series, random_state: Generator, probability_of_detection: float) → Series: Determines if mitigation of a crack occurs.

material docu

class helpr.physics.material.MaterialSpecification(yield_strength, fracture_resistance, sample_size=1)

Class defining material specifications for base material and welds.

fracture_resistance

yield_strength

get_single_material(sample_index)

Returns single material specification from ensemble object.

Parameters:: sample_index (int) – Index of requested pipe instance.
Returns:: Specification for the pipe instance.
Return type:: MaterialSpecification

pipe docu

class helpr.physics.pipe.Pipe(outer_diameter, wall_thickness, sample_size=1)

Class defining physical Pipe properties.

outer_diameter

wall_thickness

pipe_avg_radius

inner_diameter

calc_average_radius(): Calculates average pipe radius.

calc_inner_diameter(): Calculates inner diameter.

calc_t_over_r(): calculates the ratio of wall thickness to inner radius

get_single_pipe(sample_index)

Returns single pipe instance.

Parameters:: sample_index (int) – Index of requested pipe instance.
Returns:: Single pipe instance.
Return type:: Pipe

stress_state docu

class helpr.physics.stress_state.GenericStressState(pipe, environment, material, defect, stress_intensity_method=None)

Parent Class for generic Stress State capabilities.

pipe_specification

environment_specification

material_specification

defect_specification

stress_intensity_method

initial_crack_depth

calc_allowable_stress(): Calculates the pipe’s total allowable stress.

calc_f(): Calculates the current f values.

calc_hoop_stress(remaining_thickness): Calculates hoop stress.

calc_initial_crack_depth(): Calculates initial crack depth.

calc_longitudinal_stress(remaining_thickness): Calculates longitudinal stress.

calc_q(current_a_over_c): Calculates Q variable from Equation (9B.95) in API 579-1.

calc_remaining_wall_thickness(crack_depth): Calculates the remaining (non-cracked) pipe wall thickness.

calc_stress_intensity_factor(crack_depth, crack_length): Calculates stress intensity factor (k).

calc_stress_solution(crack_depth): Calculates stress solution.

check_initial_stress_criteria(): Checks the initial stress state of the pipe.

get_single_stress_state(sample_index)

Returns single stress state instance.

Parameters:: sample_index (int) – Index of requested pipe instance.
Returns:: Specification for the stress state instance.
Return type:: GenericStressState

class helpr.physics.stress_state.InternalAxialHoopStress(pipe, environment, material, defect, stress_intensity_method, sample_size=1)

Stress State Class for Internal Axial Hoop Stress Cases.

calc_G_parameters_finite_length(A, Q, phi): Calculates influence coefficients for a finite length surface cracks based on equations in API 579-1 Section 9B.5.10.

calc_k_solution_finite_length_part_through_flaw_api(crack_depth, crack_length, phi=np.pi / 2)

Calculates stress intensity factor for longitudinal direction surface cracks with semi-elliptical shape, internal pressure (KCSCLE1), given in Equation (9B.186) in API 579-1 Section 9B.5.10.

Dimensional limits:

0.0 <= a/t <= 0.8
0.03125 <= a/c <= 2.0
phi <= pi/2; for pi/2 < phi <= pi, K_I(phi) = K_I(pi - phi)
0.0 <= t/inner_radius <= 1.0

calc_k_solution_finite_length_part_through_internal_flaw(crack_depth, crack_length): Calculates stress intensity factor for finite length part-through internal flaws.

calc_k_solution_long_part_through_flaw_api(crack_depth, crack_length)

Calculates stress intensity factor for longitudinal direction surface cracks with infinite length, internal pressure (KCSCLL1), given in Equation (9B.176) in API 579-1 Section 9B.5.4.

Dimensional limits:

0.0 <= a/t <= 0.8
0.0 <= t/inner_radius <= 1.0

calc_k_solution_long_part_through_internal_flaw(crack_depth, crack_length): Calculates k solution for long part-through internal flaws.

calc_ref_stress_api(crack_depth): Calculates the reference stress as per the API 579-1 methodology included in Annex 9C.5.10, using the net section collapse criteria.

calc_stress_intensity_factor(crack_depth, crack_length, phi=np.pi / 2)

Calculates the stress intensity factor. For finite length flaws, either the Anderson analytical method (method='anderson') or the API 579-1 method (method='api') can be used.

Parameters:

crack_depth (float) – Current crack depth (m).
crack_length (float) – Current crack length (m).
phi (float, optional) – Angle to crack tip (rad). Only used for API finite length solution.

calc_stress_solution(crack_depth)

Calculates stress solution.

Parameters:: crack_depth (float) – Crack depth (m).

check_anderson_solution_assumptions(): Checks that the inputs do not violate the Anderson solution dimensional limits

check_api_solution_assumptions(): Checks that the inputs do not violate the API 579-1 dimensional limits

interp_table_parameters(table, **table_args): Interpolates values for the influence coefficients based on provided in API 579-1. The table_args provided should match the dimensions in the provided table.

load_api_tables(): Loads the data from the necessary lookup tables from API 579-1.

open_nc_table(nc_file): Opens a saved NetCDF file of lookup table values from API 579-1.

class helpr.physics.stress_state.InternalCircumferentialLongitudinalStress(pipe, environment, material, defect, stress_intensity_method=None)

Stress State Class for Internal Circumferential Longitudinal Stress Cases.

calc_f(q_value, radius_thickness_ratio, xi): Calculates current f value.

calc_stress_intensity_factor(crack_depth, crack_length)

Calculates stress intensity factor.

Parameters:

crack_depth (float) – Current crack depth, a (m).
crack_length (float) – Current crack length, 2c (m)

calc_stress_solution(crack_depth)

Calculates stress solution.

Parameters:: crack_depth (float) – Crack depth (m).