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, stress_intensity_method=None, aleatory_samples=0, epistemic_samples=0, sample_type='deterministic', random_seed=None, step_cycles=False)

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

crack_growth_model

step_cycles

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

failure_assessment_plot

Filepath to generated failure assessment 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_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.

perform_probabilistic_study(): Performs a probabilistic analysis.

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_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_a(): “Calculates delta A (change in crack size).

calc_delta_n(): “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.

update_delta_k_delta_a(delta_k, delta_a): Updates delta k and delta a values.

update_delta_k_delta_n(delta_k, delta_n): Updates delta k and delta n values.

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, sample_size=1, location_factor=1)

Definition of crack initiation physics.

flaw_depth

flaw_length

location_factor

a_over_c

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

set_a_over_c(flaw_depth): Sets the a/c (depth/length) value using crack depth. Currently assumed to be a constant ratio.

cycle_evolution docu

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

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(): Calculates current delta k value.

calc_life_assessment(step_cycles: bool = False)

Runs a fatigue crack life assessment analysis.

Parameters:: step_cycles (bool or int, optional) – Flag for evolving analysis by cycle or by a/t value, defaults to False (a/t). Passing an int will run the analysis the specified number of cycles.
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.

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

compute_cycle_n(): Computes results for a single (n) cycle.

create_clean_cycle(): Resets the cycle dictionary.

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

initialize_cycle_dict(optimize=False): Sets up initial cycle dictionary.

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

setup_a_crit_solve(parallel=False): Sets up solving function for ‘a critical’ value for each sample.

static solve_for_a_crit(single_instance): Creates an individual class object to solve ‘a critical’ for each instance.

step_through_cycles(step_cycles: bool = False): 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(optimize=False): Calculates current crack width (c) value.

update_c_through_delta_k(optimize=False): 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(): Calculates current delta k value.

update_delta_n(): Calculates current delta n value.

update_k_max_f_q(optimize=False): Calculates current k_max, f, and q values.

update_total_cycles(): Calculates current cycle count.

class helpr.physics.cycle_evolution.OptimizeACrit(pipe, stress_state, defect, environment, material, crack_growth_model)

ACrit optimization solver using a single cycle instance.

pipe

stress_state

defect

environment

material

crack_growth_model

determine_a_crit(a_crit): Acts as objective function for optimization of a crit.

minimize_for_a_crit(): Performs optimization for crit value.

setup_a_crit_solve(parallel=False): Initializes solver for a critical value.

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(stress_intensity_factor, reference_stress_solution)

Calculates failure assessment variables.

Parameters:

stress_intensity_factor (pandas.Series) – Series of stress intensity factors from analysis results.
reference_stress_solution (pandas.Series) – Series of reference stress solutions.

Returns:

toughness_ratio (pandas.Series) – Ratio of stress intensity factors to fracture resistance.
load_ratio (pandas.Series) – Ratio of reference stress solutions to yield stress.

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: pd.DataFrame) → tuple[int, np.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, sample_size=1)

Parent Class for generic Stress State capabilities.

pipe_specification

environment_specification

material_specification

defect_specification

stress_intensity_method

initial_crack_depth

a_crit

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(a_over_c, optimize=False): 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, optimize=False): 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.

determine_a(a_value, optimize=False): Determines either the critical or current value of a.

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_k_solution_finite_length_long_direction_internal_flaw_api(crack_depth, crack_length, A_file=os.path.join(os.path.dirname(os.path.realpath(__file__)), '../data/Table_9B12.nc'), phi=np.pi / 2, optimize=False)

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, optimize=False): Calculates stress intensity factor for finite length part-through internal flaws.

calc_k_solution_infinite_length_long_direction_internal_flaw_api(crack_depth, crack_length, G_file=os.path.join(os.path.dirname(os.path.realpath(__file__)), '../data/Table_9B10.nc'), optimize=False)

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, optimize=False): Calculates k solution for long part-through internal flaws.

calc_stress_intensity_factor(crack_depth, crack_length, optimize=False, method='Anderson')

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).
optimize (bool, optional) – Flag for a_crit optimization.

calc_stress_solution(crack_depth)

Calculates stress solution.

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

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

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, optimize=False)

Calculates stress intensity factor.

Parameters:

crack_depth (float) – Current crack depth (m).
eta (float) – Current eta value.
optimize (bool, optional) – Flag for a_crit optimization.

calc_stress_solution(crack_depth)

Calculates stress solution.

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