pyflange.io

Reading and writing flange fatigue cases in the PyFlange JSON format.

This module implements the PyFlange JSON case format, documented in detail in the JSON format reference. In particular it provides:

  • Loaders, that convert a JSON case file (or the equivalent dictionary) into PyFlange objects: load_fatiguecase, load_fatiguecase_sampler and the lower-level create_* functions.
  • Exporters, that convert PyFlange objects back into dictionaries in the same format (*_to_dict functions) and write dictionaries to JSON or Excel files (dict_to_json, dict_to_excel).
  • Monte Carlo helpers: sample_fatiguecase, that runs a simulation and returns a table of realizations, and create_realization, that rebuilds a single realization from that table.
Format versions

The current format version is 0.2.0 (FORMAT_VERSION). Files without a format_version field are assumed to be version 0.1.0 (the format used by the former Forrester tool) and are upgraded on the fly by upgrade_case, so they keep producing the same results.

Units

All values are expressed in SI units (m, N, Pa, rad), except where stated otherwise in the format reference.

Example 
from pyflange.io import load_fatiguecase, fatiguecase_to_dict, dict_to_json

fcase = load_fatiguecase("case.json")       # a BoltFatigueAnalysis object
print(fcase.damage, fcase.fatigue_life)

dict_to_json(fatiguecase_to_dict(fcase, verbose=True), "case-res.json")

DEFAULT_FLANGE_SEGMENT_TYPE = 'PolynomialLFlangeSegment' module-attribute

str: The flange segment type used when FlangeSegment.type is omitted (IEC 61400-6 AMD1 model).

FLANGE_SEGMENT_TYPES = ('PolynomialLFlangeSegment', 'PolynomialLFlangeSegmentED2') module-attribute

tuple: The flange segment types supported by the JSON format.

FORMAT_VERSION = '0.2.0' module-attribute

str: The version of the JSON format written by this module.

LEGACY_DS_REF_MEAN = 62000000.0 module-attribute

float: Mean fatigue reference stress range implicitly used by format 0.1.0 samplers, in Pa. Format 0.1.0 files get it assigned when upgraded.

SAMPLE_COLUMNS = ['BoltPreload', 'GapShapeFactor', 'TiltAngle', 'GapAngle', 'GapHeight', 'FatigueClass', 'MomentRangeCoefficient', 'Damage', 'AllowableDamage', 'FatigueLife', 'SMF', 'Utilization'] module-attribute

list: The columns of the table returned by sample_fatiguecase.

SUPPORTED_FORMAT_VERSIONS = ('0.1.0', '0.2.0') module-attribute

tuple: The JSON format versions that this module can read.

bolt_to_dict(bolt)

Converts a bolt object to a dictionary in the JSON format.

Parameters:
Returns:
  • dict –

    The bolt parameters, with type "MetricBolt".
Raises:
  • ValueError –

    If the bolt type is not supported.

create_bolt(**params)

Creates a bolt object from a dictionary of parameters.

Parameters:
  • **params –

    The bolt parameters. The type key selects the bolt kind: "StandardMetricBolt" (keys designation, material_grade, shank_length, shank_diameter_ratio, stud) or "MetricBolt" (keys nominal_diameter, thread_pitch, yield_stress, ultimate_tensile_stress, elastic_modulus, poissons_ratio, shank_length, shank_diameter_ratio, stud).
Returns:
  • –

    pyflange.bolts.MetricBolt: The bolt object.
Raises:
  • ValueError –

    If the bolt type is not supported.

create_distribution(**params)

Creates a scipy distribution from a dictionary of parameters.

Parameters:
  • **params –

    Distribution parameters. The Distribution key selects the distribution kind:

    • "Normal": keys Mean, CoV.
    • "LogNormal": keys Mean, CoV.
    • "Weibull": keys Shape, Scale.
    • "Beta": keys Alpha, Beta and optionally x0, x1 (bounds of the definition interval, default 0 and 1).
Returns:
  • –

    scipy.stats.rv_frozen: A frozen scipy continuous distribution.
Raises:
  • ValueError –

    If an unsupported distribution type is provided.

create_fatiguecase(data, SMF=None)

Creates a BoltFatigueAnalysis object from a case dictionary.

Parameters:
  • data (dict) –

    A case dictionary, in any supported format version.

  • SMF (float, default: None ) –

    Stress multiplication factor. If omitted, the SMF value of the case is used, or 1.0 if the case has none.
Returns:
  • –

    pyflange.fatigue.BoltFatigueAnalysis: The fatigue analysis object.

create_fatiguecase_sampler(fseg, markov_matrix, **params)

Creates a sampler of random fatigue cases.

The random flange segments are of the same type as fseg and share its deterministic parameters. Their shell stiffness is always interpolated from the FEA data (see pyflange.flangesegments.shell_stiffness) as a function of the random gap angle.

Parameters:
  • fseg (PolynomialLFlangeSegment) –

    The base flange segment object.

  • markov_matrix (MarkovMatrix) –

    The base Markov matrix object.

  • **params –

    Statistical parameters (Stats section, current format version), for preload, plastic loss, DFT, gap, tilt, load range factor, fatigue class factor, allowable damage and stress multiplication factor.
Returns:
  • Generator –

    A generator that yields randomized BoltFatigueAnalysis objects.
Raises:
  • ValueError –

    If an unsupported distribution type is provided for any parameter.

  • KeyError –

    If a required parameter is missing.

create_fatiguecurve(**params)

Creates a fatigue curve object from a dictionary of parameters.

Parameters:
  • **params –

    Fatigue curve parameters (BoltFatigueCurve section). The optional type key selects the curve kind:

    • "BoltFatigueCurve" (default): keys BoltNominalDiameter, DS_ref, gamma_M.
    • "SingleSlopeFatigueCurve": keys m, DS_ref, N_ref.
    • "DoubleSlopeFatigueCurve": keys m1, m2, DS_ref, N_ref, where DS_ref and N_ref define the knee point.
Returns:
  • –

    pyflange.fatigue.FatigueCurve: The fatigue curve object.
Raises:
  • ValueError –

    If the curve type is not supported.

create_flangesegment(**params)

Creates a flange segment from a dictionary of parameters.

Given a dictionary containing the parameters for a flange segment object in the PyFlange JSON format (FlangeSegment section), returns the corresponding flange segment. Only L-flange segments are supported.

The bolt preload is given either as preload_ratio (fraction of the bolt tensile yield force, As * fy) or as an absolute force Fv, but not both.

Parameters:
  • **params –

    Flange segment parameters. Expected keys are 'a', 'b', 's', 't', 'R', 'central_angle', 'Zg', 'bolt', 'preload_ratio' or 'Fv', 'Do', 'washer', 'nut', 'gap', 'tilt_angle', 'E', 'G', 's_ratio', 'r', 'k_shell', 'PPL', 'DFT', 'settlement_factor' and, optionally, 'type' (default DEFAULT_FLANGE_SEGMENT_TYPE). Other keys are ignored.
Returns:
  • PolynomialLFlangeSegment –

    The flange segment object (possibly a PolynomialLFlangeSegmentED2).
Raises:
  • ValueError –

    If an unsupported type is provided, or if the preload is not specified exactly once.

create_gap_sampler(flange_diameter, **params)

Creates a random gap sampler from a dictionary of parameters.

Parameters:
  • flange_diameter (float) –

    The outer diameter of the flange.

  • **params –

    Gap sampler parameters (Stats.Gap section). The JointDistribution key selects the kind of sampler:

    • "IEC 61400-6:2020 AMD1": keys FlatnessTolerance, Angle (distribution), ShapeFactor (distribution).
    • "IEC 61400-6:2020 ED2": key FlatnessTolerance.
    • "ClaytonCopula": keys Theta, Height (distribution), Angle (distribution), ShapeFactor (distribution).
Returns:
  • Generator –

    A sampler yielding random pyflange.flangesegments.Gap objects.
Raises:
  • ValueError –

    If an unsupported joint distribution is provided.

create_markovmatrix(**params)

Creates a Markov matrix object from a dictionary of parameters.

Parameters:
  • **params –

    Markov matrix parameters (MarkovMatrix section). Expected keys are 'range', 'mean', 'cycles', 'duration'.
Returns:
  • –

    pyflange.fatigue.MarkovMatrix: The Markov matrix object.

create_nut(**params)

Creates a nut object from a dictionary of parameters.

Parameters:
  • **params –

    The nut parameters. The type key selects the nut kind: "ISOHexNut" or "RoundNut" (key designation), or "HexNut" (keys nominal_diameter, thickness, inscribed_diameter, circumscribed_diameter, bearing_diameter, elastic_modulus, poissons_ratio).
Returns:
  • –

    pyflange.bolts.HexNut: The nut object.
Raises:
  • ValueError –

    If the nut type is not supported.

create_realization(data, record)

Rebuilds a single Monte Carlo realization.

Given the case that generated a sample and one row of the table returned by sample_fatiguecase (or of the corresponding CSV file), rebuilds the random fatigue case that produced that row.

Parameters:
  • data (dict) –

    The case dictionary that generated the sample.

  • record (Mapping) –

    One realization, with the keys listed in SAMPLE_COLUMNS (e.g. a pandas.Series row).
Returns:
  • –

    pyflange.fatigue.BoltFatigueAnalysis: The rebuilt fatigue case.

create_sampler(**params)

Creates a pyflange sampler from a dictionary of parameters.

Parameters:
  • **params –

    Sampler parameters. All the distributions supported by create_distribution are accepted, plus "Product", which samples the product of two independent variables described by the Dist1 and Dist2 keys.
Returns:
  • Generator –

    A sampler yielding random values.
Raises:
  • ValueError –

    If an unsupported distribution type is provided.

create_washer(params)

Creates a washer object from a dictionary of parameters.

Parameters:
  • params (dict | None) –

    The washer parameters, or None for no washer. The type key selects the washer kind: "ISOFlatWasher" (key designation) or "FlatWasher" (keys outer_diameter, inner_diameter, thickness, elastic_modulus, poissons_ratio).
Returns:
  • –

    pyflange.bolts.FlatWasher | None: The washer object, or None.
Raises:
  • ValueError –

    If the washer type is not supported.

dict_to_excel(d, file_path)

Writes a dictionary to an Excel file.

This utility function takes a dictionary and an Excel file name as inputs, flattens the dictionary into a list of chained-key-value pairs, and writes it to an Excel file in a two-column table, where the first column contains the keys and the second column contains the corresponding values. Each value cell is also given an Excel name equal to its key, so that it can be referenced by name from other workbooks.

Example

Given the following dictionary: d = { "a": 10, "b": { "c": 20, "d": 30 } }

This function will write it to Excel in the following format: | KEY | VALUE | |-----|-------| | a | 10 | | b.c | 20 | | b.d | 30 |

Parameters:
  • d (dict) –

    The dictionary to be written.

  • file_path (str) –

    The path to the Excel file to be created.

dict_to_json(d, file_path)

Writes a dictionary to a JSON file.

Numpy scalars and arrays are converted to plain Python numbers and lists.

Parameters:
  • d (dict) –

    The dictionary to be written.

  • file_path (str) –

    The path to the JSON file to be created.

fatiguecase_to_dict(fcase, verbose=False)

Converts a fatigue analysis to a dictionary in the JSON format.

The returned dictionary contains the case input (it can be loaded back with create_fatiguecase) and the analysis results.

Parameters:
  • fcase (BoltFatigueAnalysis) –

    The fatigue analysis.

  • verbose (bool, default: False ) –

    If True, the flange segment report (see flangesegment_to_dict), the bolt stress Markov matrix and the fatigue life are included too. Defaults to False.
Returns:
  • dict –

    The fatigue case data and results (damage, allowable_damage, SMF and, if verbose, FatigueLife).
Raises:
  • ValueError –

    If fcase is not a BoltFatigueAnalysis object.

fatiguecurve_to_dict(sncurve)

Converts a fatigue curve object to a dictionary in the JSON format.

Parameters:
  • sncurve (FatigueCurve) –

    A BoltFatigueCurve, SingleSlopeFatigueCurve or DoubleSlopeFatigueCurve object.
Returns:
  • dict –

    The fatigue curve parameters. For a BoltFatigueCurve, the knee point of the design curve is reported too, as m1, m2, DS12 and N_ref.
Raises:
  • ValueError –

    If the fatigue curve type is not supported.

flangesegment_to_dict(fseg, verbose=False)

Converts a flange segment to a dictionary in the JSON format.

Parameters:
  • fseg (PolynomialLFlangeSegment) –

    The flange segment object.

  • verbose (bool, default: False ) –

    If True, the dictionary also contains a report of derived and intermediate quantities (preload after losses, polynomial reference points and coefficients, transfer functions, stiffnesses, etc.). These extra keys are ignored when the dictionary is loaded back. Defaults to False.
Returns:
  • dict –

    The flange segment parameters.
Raises:
  • ValueError –

    If the flange segment type is not supported.

format_version(data)

Returns the format version of a case dictionary.

Parameters:
  • data (dict) –

    A case dictionary, as read from a JSON case file.
Returns:
  • str –

    The value of the format_version field, or "0.1.0" if the field is missing.

gap_to_dict(gap)

Converts a gap object to a dictionary in the JSON format.

Parameters:
  • gap (Gap) –

    The gap object.
Returns:
  • dict –

    The gap parameters.
Raises:
  • ValueError –

    If gap is not a Gap object.

load_fatiguecase(file_path, SMF=None)

Loads a BoltFatigueAnalysis object from a JSON file.

Given the path of a JSON file containing a flange fatigue case in the PyFlange JSON format, returns the corresponding BoltFatigueAnalysis object.

Parameters:
  • file_path (str) –

    The path to the JSON file.

  • SMF (float, default: None ) –

    Stress multiplication factor. If omitted, the SMF value of the case is used, or 1.0 if the case has none.
Returns:
  • –

    pyflange.fatigue.BoltFatigueAnalysis: The loaded fatigue analysis object.

load_fatiguecase_sampler(file_path)

Loads a fatigue case sampler from a JSON file.

Parameters:
  • file_path (str) –

    The path to the JSON file containing the fatigue case and its Stats section.
Returns:
  • Generator –

    A generator that yields randomized BoltFatigueAnalysis objects.

load_inputfile(file_path)

Loads a JSON input file to a dictionary.

The content is returned as it is, without any format upgrade or validation. Use upgrade_case to convert it to the current version.

Parameters:
  • file_path (str) –

    Path of the JSON file.
Returns:
  • dict –

    The content of the JSON file.

markovmatrix_to_dict(mkvm)

Converts a Markov matrix object to a dictionary in the JSON format.

Parameters:
Returns:
  • dict –

    The Markov matrix parameters.
Raises:
  • ValueError –

    If mkvm is not a MarkovMatrix object.

nut_to_dict(nut)

Converts a nut object to a dictionary in the JSON format.

Parameters:
  • nut (HexNut) –

    The nut object.
Returns:
  • dict –

    The nut parameters, with type "HexNut".
Raises:
  • ValueError –

    If the nut type is not supported.

sample_fatiguecase(data, size, seed=None, progress=None)

Runs a Monte Carlo simulation of a fatigue case.

Parameters:
  • data (dict) –

    A case dictionary, including the Stats section.

  • size (int) –

    Number of realizations to generate.

  • seed (int, default: None ) –

    Seed of the random number generator. If given, the numpy global random generator is re-seeded, so that the simulation is reproducible. If omitted, the current random state is used.

  • progress (callable, default: None ) –

    A function called as progress(i) after the generation of the i-th realization (1-based).
Returns:
  • –

    pandas.DataFrame: A table with one row per realization and the columns listed in SAMPLE_COLUMNS. Lengths are in m, forces in N, angles in rad, stresses in Pa, fatigue life in the time units of the Markov matrix duration. FatigueClass is the knee-point stress range of the sampled bolt S-N curve and MomentRangeCoefficient the factor applied to the load ranges.

upgrade_case(data)

Converts a case dictionary to the current format version.

The input dictionary is not modified: a converted copy is returned. Upgrading a version 0.1.0 case:

  • sets format_version to the current version;
  • adds DS_ref_mean = 62 MPa to Stats.FatigueClassFactor, if the Stats section is present, which is the value implicitly used by the version 0.1.0 Monte Carlo sampler.
Parameters:
  • data (dict) –

    A case dictionary in any supported format version.
Returns:
  • dict –

    An equivalent case dictionary in the current format version.
Raises:
  • ValueError –

    If the format version is not supported.

washer_to_dict(washer)

Converts a washer object to a dictionary in the JSON format.

Parameters:
  • washer (FlatWasher | None) –

    The washer object.
Returns:
  • –

    dict | None: The washer parameters, with type "FlatWasher", or None if washer is None.
Raises:
  • ValueError –

    If the washer type is not supported.