The WoehlerCurve class#

class pylife.materiallaws.WoehlerCurve(pandas_obj)[source]#

Represent a Wöhler curve stored in a pandas object.

A Wöhler curve, also called an S-N curve, relates a load amplitude to the number of cycles to failure. The accessor accepts scalar curve parameters in a pandas.Series or row-wise curve parameters in a pandas.DataFrame.

Parameters:

pandas_obj (pandas.Series or pandas.DataFrame) – Pandas object containing Wöhler curve parameters.

Notes

The signal contract is validated and completed as follows:

  • k_1 : Mandatory slope in the finite-life range above the knee point, dimensionless.

  • ND : Mandatory number of cycles at the knee point, sometimes called endurance cycles, in cycles.

  • SD : Mandatory load amplitude at the knee point, sometimes called endurance limit, in a consistent load unit such as MPa or N.

  • k_2 : Optional slope below the knee point, dimensionless. Default is numpy.inf, representing a horizontal endurance branch.

  • TN : Optional scatter range in cycle direction, defined as N_90 / N_10. Default is 1.0 if neither TN nor TS is given; otherwise it is derived from TS ** k_1.

  • TS : Optional scatter range in load direction, defined as SD_90 / SD_10. Default is 1.0 if neither TN nor TS is given; otherwise it is derived from TN ** (1 / k_1).

  • failure_probability : Optional failure probability represented by the stored curve. Default is 0.5.

The S-N terminology follows fatigue testing practice, for example DIN 50100. The load unit is not fixed by pyLife; use one consistent unit for SD and all load values passed to the accessor.

property ND#

Return the number of cycles at the knee point.

property SD#

Return the load amplitude at the knee point.

property TN#

Return the scatter range in cycle direction.

property TS#

Return the scatter range in load direction.

basquin_cycles(load, failure_probability=None)[source]#

Calculate cycle numbers from loads using the Basquin equation.

Parameters:

  • load (array_like) – Load amplitudes in the same unit as SD.

  • failure_probability (float or array_like or None, optional) – Failure probability for which the cycle numbers are calculated. If None, use the accessor’s current failure_probability. Default is None.

Returns:

Numbers of cycles to failure for the given load values. The result is a pandas.Series if load is a series.

Return type:

numpy.ndarray or pandas.Series

Notes

The finite-life branch follows

\[N = ND \left(\frac{L}{SD}\right)^{-k}\]

with k_1 above the knee point and k_2 below it. If k_2 is infinite, loads below SD lead to infinite life.

Examples

>>> import pandas as pd
>>> wc = pd.Series({'k_1': 5.0, 'ND': 1e6, 'SD': 100.0}).woehler
>>> float(wc.basquin_cycles(200.0))
31250.0
basquin_load(cycles, failure_probability=None)[source]#

Calculate loads from cycle numbers using the Basquin equation.

Parameters:

  • cycles (array_like) – Numbers of cycles to failure.

  • failure_probability (float or array_like or None, optional) – Failure probability for which the load amplitudes are calculated. If None, use the accessor’s current failure_probability. Default is None.

Returns:

Load amplitudes in the same unit as SD. The result is a pandas.Series if cycles is a series.

Return type:

numpy.ndarray or pandas.Series

Notes

This method inverts the Basquin relation used by basquin_cycles():

\[L = SD \left(\frac{N}{ND}\right)^{-1/k}\]
broadcast(parameter, droplevel=None)#

Broadcast the parameter to the object of self.

Parameters:

  • parameter (scalar, numpy.ndarray, pandas.Series or pandas.DataFrame) – The operand to align with the object of self.

  • droplevel (list of str, optional) – Names of index levels that are dropped from the returned parameter before it is returned. Use it when a parameter must not be resolved along those levels, e.g. when a material parameter is constant over all load steps. Default is None, which keeps all levels.

Returns:

  • parameter (scalar, pandas.Series or pandas.DataFrame) – The broadcast operand, index aligned with obj.

  • obj (pandas.Series or pandas.DataFrame) – The broadcast object of self, index aligned with parameter.

Examples

The behavior of the Broadcaster is best illustrated by examples:

  • Broadcasting pandas.Series to a scalar results in a scalar and a pandas.Series.

    obj = pd.Series([1.0, 2.0], index=pd.Index(['foo', 'bar'], name='idx'))
obj

    idx
foo    1.0
bar    2.0
dtype: float64

    parameter, obj = Broadcaster(obj).broadcast(5.0)

parameter

    array(5.)

    obj

    idx
foo    1.0
bar    2.0
dtype: float64

  • Broadcasting pandas.DataFrame to a scalar results in a pandas.DataFrame and a pandas.Series.

    obj = pd.DataFrame({
    'foo': [1.0, 2.0],
    'bar': [3.0, 4.0]
}, index=pd.Index([1, 2], name='idx'))
obj
    foo bar
    idx
    1 1.0 3.0
    2 2.0 4.0 
    parameter, obj = Broadcaster(obj).broadcast(5.0)

parameter

    idx
1    5.0
2    5.0
dtype: float64

    obj
    foo bar
    idx
    1 1.0 3.0
    2 2.0 4.0

  • Broadcasting pandas.DataFrame to a a pandas.Series results in a pandas.DataFrame and a pandas.Series, if and only if the index name of the object is None.

    obj = pd.Series([1.0, 2.0], index=pd.Index(['tau', 'chi']))
obj

    tau    1.0
chi    2.0
dtype: float64

    parameter = pd.Series([3.0, 4.0], index=pd.Index(['foo', 'bar'], name='idx'))
parameter

    idx
foo    3.0
bar    4.0
dtype: float64

    parameter, obj = Broadcaster(obj).broadcast(parameter)

parameter

    idx
foo    3.0
bar    4.0
dtype: float64

    obj
    tau chi
    idx
    foo 1.0 2.0
    bar 1.0 2.0
cycles(load, failure_probability=None)[source]#

Calculate cycle numbers from load amplitudes.

Parameters:

  • load (array_like) – Load amplitudes in the same unit as SD.

  • failure_probability (float or array_like or None, optional) – Failure probability for which the cycle numbers are calculated. If None, use the accessor’s current failure_probability. Default is None.

Returns:

Numbers of cycles to failure for the given load values. The result is a pandas.Series if load is a series.

Return type:

numpy.ndarray or pandas.Series

Notes

By default the calculation is performed according to the Basquin equation using basquin_cycles(). Derived classes can override this method to implement a different fatigue law.

fail_if_key_missing(keys_to_check, msg=None)#

Raise an exception if any key is missing in the signal.

Parameters:

  • keys_to_check (list of str) – The keys that need to be available in the signal.

  • msg (str, optional) – A printf style format string for the error message taking two %s arguments: the expected keys and the missing keys. By default a message naming the signal class is generated.

Raises:

AttributeError – If the underlying object is neither a pandas.DataFrame nor a pandas.Series, or if any of keys_to_check is not provided by the signal.

See also

get_missing_keys

Return the missing keys instead of raising.

Notes

This is the canonical way to assert a signal contract in the _validate() implementation of a derived class.

property failure_probability#

Return the represented failure probability.

classmethod from_parameters(**kwargs)#

Make a signal instance from a parameter set.

This is a convenience function to instantiate a signal from individual parameters rather than from a pandas object.

Parameters:

**kwargs (scalar or array_like) – The signal keys and their values. If more than one value is given and the values are iterable, a pandas.DataFrame backed signal is created, otherwise a pandas.Series backed one.

Returns:

An instance of the signal class the method is called on.

Return type:

PylifeSignal

Examples

For a signal class like

@pd.api.extensions.register_dataframe_accessor('foo_signal')
class FooSignal(PylifeSignal):
    pass

the following two expressions are equivalent

pd.Series({'foo': 1.0, 'bar': 2.0}).foo_signal
FooSignal.from_parameters(foo=1.0, bar=2.0)
get_missing_keys(keys_to_check)#

Get a list of keys that are missing in the signal.

Parameters:

keys_to_check (list of str) – The keys that need to be available in the signal.

Returns:

The keys of keys_to_check that the signal does not provide, in the order in which they were given. An empty list means that the signal is complete.

Return type:

list of str

Raises:

AttributeError – If the underlying object is neither a pandas.DataFrame nor a pandas.Series.

See also

fail_if_key_missing

Raise instead of returning the missing keys.

Notes

This method is meant to be used in the _validate() implementation of a derived class when a missing key is not necessarily an error, e.g. when a default value can be derived.

property k_1#

Return the finite-life Wöhler slope.

property k_2#

Return the Wöhler slope below the knee point.

keys()#

Get the keys the signal provides.

Returns:

The keys of the underlying pandas object.

Return type:

pandas.Index

Raises:

AttributeError – If the underlying object is neither a pandas.DataFrame nor a pandas.Series.

Notes

For a pandas.DataFrame backed signal the columns are returned, for a pandas.Series backed one the index.

load(cycles, failure_probability=None)[source]#

Calculate load amplitudes from cycle numbers.

Parameters:

  • cycles (array_like) – Numbers of cycles to failure.

  • failure_probability (float or array_like or None, optional) – Failure probability for which the load amplitudes are calculated. If None, use the accessor’s current failure_probability. Default is None.

Returns:

Load amplitudes in the same unit as SD. The result is a pandas.Series if cycles is a series.

Return type:

numpy.ndarray or pandas.Series

Notes

By default the calculation is performed according to the Basquin equation using basquin_load(). Derived classes can override this method to implement a different fatigue law.

miner_elementary()[source]#

Set k_2 according to the Miner elementary method.

Returns:

Copy of the curve with k_2 set to k_1.

Return type:

WoehlerCurve

miner_haibach()[source]#

Set k_2 according to the Miner-Haibach method.

Returns:

Copy of the curve with k_2 set to 2 * k_1 - 1.

Return type:

WoehlerCurve

miner_original()[source]#

Set k_2 according to the Miner original method.

Returns:

Copy of the curve with k_2 set to numpy.inf.

Return type:

WoehlerCurve

to_pandas()#

Expose the pandas object of the signal.

Returns:

The pandas object representing the signal.

Return type:

pandas.DataFrame or pandas.Series

Notes

The default implementation just returns the object given when instantiating the signal class. Derived classes may return a modified or augmented object, if they store some extra information.

By default the object is not copied. So make a copy yourself, if you intend to modify it.

transform_to_failure_probability(failure_probability)[source]#

Transform the Wöhler curve to another failure probability.

Parameters:

failure_probability (float or array_like or None) – Target failure probability. If None, return the accessor itself without changing the stored curve.

Returns:

Curve accessor transformed to failure_probability or self if failure_probability is None.

Return type:

WoehlerCurve