Aggregation

ffpack.utils.aggregation.cycleCountingAggregation(data, binSize=1.0)

Count the number of occurrences of each cycle digitized to the nearest bin.

Parameters

data (2d array) – Input cycle counting data [ [ value, count ], … ] for bin collection
binSize (scalar, optional) – bin size is the difference between each level, for example, binSize=1.0, the levels will be 0.0, 1.0, 2.0, 3.0 …

Returns

rst – Aggregated [ [ aggregatedValue, count ] ] by the binSize

Return type

2d array

Raises

ValueError – If the data dimension is not 2. If the data is empty

Notes

When a value is in the middle, it will be counted downward for example, 0.5 when binSize=1.0, the count will be counted to 0.0

Examples

>>> from ffpack.utils import cycleCountingAggregation
>>> data = [ [ 1.7, 2.0 ], [ 2.2, 2.0 ] ]
>>> rst = cycleCountingAggregation( data )

Counting matrix

ffpack.utils.countingMatrix.countingRstToCountingMatrix(countingRst)

Calculate counting matrix from rainflow counting result.

Parameters

countingRst (2d array) – Cycle counting result in form of [ [ rangeStart1, rangeEnd1, count1 ], [ rangeStart2, rangeEnd2, count2 ], … ].

Returns

rst (2d array) – A matrix contains the counting results.
matrixIndexKey (1d array) – A sorted array contains the index keys for the counting matrix.

Raises

ValueError – If the data dimension is not 2. If the data is not empty and not in dimension of n by 3.

Examples

>>> from ffpack.lsm import countingRstToCountingMatrix
>>> countingRst = [ [ -2.0, 1.0, 1.0 ], [ 5.0, -1.0, 3.0 ], [ -4.0, 4.0, 0.5 ] ]
>>> rst, matrixIndexKey = countingRstToCountingMatrix( countingRst )

Derivatives

ffpack.utils.derivatives.centralDiffWeights(Np, ndiv=1)

Return weights for an Np-point central derivative 1.

This function came from scipy.misc module, we put it here since scipy.misc module is completely removed in SciPy v1.12.0.

Assumes equally-spaced function points.

If weights are in the vector w, then derivative is w[ 0 ] * f( x - ho * dx ) + … + w[ -1 ] * f( x + h0 * dx )

Parameters

Np (integer) – Number of points for the central derivative.
ndiv (integer, optional) – Number of divisions. Default is 1.

Returns

w – Weights for an Np-point central derivative. Its size is Np.

Return type

ndarray

Notes

Can be inaccurate for a large number of points.

Examples

>>> def f( x ):
...     return 2 * x**2 + 3
>>> x = 3.0 # derivative point
>>> h = 0.1 # differential step
>>> Np = 3 # point number for central derivative
>>> weights = centralDiffWeights( Np ) # weights for first derivative
>>> vals = [ f( x + ( i - Np / 2 ) * h) for i in range( Np )]
>>> sum( w * v for (w, v) in zip( weights, vals ) ) / h
11.79999999999998
This value is close to the analytical solution:
f'(x) = 4x, so f'(3) = 12

References

1: https://en.wikipedia.org/wiki/Finite_difference

ffpack.utils.derivatives.derivative(func, x0, dx=1.0, n=1, args=(), order=3)

Find the n-th derivative of a function at a point.

This function came from scipy.misc module, we put it here since scipy.misc module is completely removed in SciPy v1.12.0.

Given a function, use a central difference formula with spacing dx to compute the nth derivative at x0.

Parameters

func (function) – Input function.
x0 (float) – The point at which the nth derivative is found.
dx (float, optional) – Spacing.
n (int, optional) – Order of the derivative. Default is 1.
args (tuple, optional) – Arguments
order (int, optional) – Number of points to use, must be odd.

Notes

Decreasing the step size too small can result in round-off error.

Examples

>>> def f(x):
...     return x**3 + x**2
>>> derivative( f, 1.0, dx=1e-6 )
4.9999999999217337

ffpack.utils.derivatives.gradient(func, nvar, n=1, dx=0.001, order=3)

Find n-th gradient of a scalar-valued differentiable function.

Parameters

func (function) – Input scalar-valued differentiable function.
nvar (integer) – The number of input variables for the input function. Input function will be called like func( X ) = func( [ X[ 0 ], X[ 1 ], …, X[ nvar - 1 ] ] ).
n (integer, optional) – Order of the derivative. Default is 1.
dx (scalar, optional) – Spacing for derivative calculation.
order (integer, optional) – Number of points used for central derivative weights, must be odd.

Returns

rst – n-th gradient of function, i.e., [ \(\partial^n f / \partial X_0^n, \dots, \partial^n f / \partial X_{nvar}^n\) ]. In general, the i-th element in the list is the n-th derivative of the func w.r.t. i-th input variable. Therefore, rst[ i ] = \(\partial^n f / \partial X_i^n\) and it can be called like rst[ i ]( X0 ) to evaluate the n-th derivative w.r.t. i-th variable at point X0. It should be noted that X0 MUST be a list, NOT a numpy array.

Return type

1d array

Notes

Decreasing the step size too small can result in round-off error.

Examples

>>> def f( X ):
...     return X[ 0 ]**3 + X[ 1 ]**2
>>> gradient( f, nvar=2, n=1 )
Output will be a function list of the 1st derivative of func
>>> [ lambda X: 3 * X[ 0 ]**2, lambda X: 2 * X[ 1 ] ]
>>> gradient( f, nvar=2, n=2 )
Output will be a function list of the 2nd derivative of func
>>> [ lambda X: 6 * X[ 0 ], lambda X: 2 ]

ffpack.utils.derivatives.gramSchmidOrth(A, alignVec=None)

Perform Gram-Schmidt orthogonization to matrix.

Parameters

A (2d matrix) – Input matrix. The orthogonization is performed w.r.t. each column vector. The input matrix must be a square matrix.
alignVec (1d array) – If alignVec exists, the alignVec will be the first vector for orthogonization.

Returns

B (2d matrix) – The matrix in which each column vector is orthogonized.
J (2d matrix) – The transformation matrix to perform the orthogonization, e.g., JA = B

Notes

A must be square and of full-rank, i.e., all rows (or, equivalently, columns) must be linearly independent.

Examples

>>> A = [ [ 1, 0 ], [ 0, 1 ] ]
>>> alignVec = [ 0.5, 0.5 ]
>>> B, J = gramSchmidOrth( A, alignVec )

ffpack.utils.derivatives.hessianMatrix(func, nvar, dx=0.001, order=3)

Find Hessian matrix for a scalar-valued differentiable function.

Parameters

func (function) – Input scalar-valued differentiable function.
nvar (integer) – The number of input variables for the input function. Input function will be called like func( X ) = func( [ X[ 0 ], X[ 1 ], …, X[ nvar - 1 ] ] ).
dx (scalar, optional) – Spacing for derivative calculation.
order (integer, optional) – Number of points used for central derivative weights, must be odd.

Returns

rst – Hessian matrix. rst[ i ][ j ] = \(\partial f / ( \partial X_i \partial X_j )\). It can be called like rst[ i ][ j ]( X0 ) to evaluate the value at point X0. It should be noted that X0 MUST be a list, NOT a numpy array.

Return type

2d array

Notes

Decreasing the step size too small can result in round-off error.

Examples

>>> def f( X ):
...     return X[ 0 ]**3 + X[ 1 ]**2
>>> hessianMatrix( f, nvar=2 )
Output will be a function list of the 1st derivative of func
>>> [ [ lambda X: 6 * X[ 0 ], lambda X: 0 ],
...   [ lambda X: 0, lambda X: 2] ]

Digitization

ffpack.utils.digitization.sequenceDigitization(data, resolution=1.0)

Digitize the sequence data to a specific resolution

The sequence data are digitized by the round method.

Parameters

data (1d array) – Sequence data to digitize.
resolution (bool, optional) – The desired resolution to round the data points.

Returns

rst – A list contains the digitized data.

Return type

1d array

Raises

ValueError – If the data dimension is not 1. If the data length is less than 2 with keedEnds == False If the data length is less than 3 with keedEnds == True

Notes

The default round function will round half to even: 1.5, 2.5 => 2.0:

Examples

>>> from ffpack.utils import sequenceDigitization
>>> data = [ -1.0, 2.3, 1.8, 0.6, -0.4, 0.8, -1.6, -2.5, 3.4, 0.3, 0.1 ]
>>> rst = sequenceDigitization( data )

Fitter

class ffpack.utils.fitter.SnCurveFitter(data, fatigueLimit)

Fitter for a SN curve based on the experimental data.

__init__(data, fatigueLimit)

Initialize a fitter for a SN curve based on the experimental data.

Parameters

data (2d array) – Experimental data for fitting in a 2D matrix, e.g., [ [ N1, S1 ], [ N2, S2 ], …, [ Ni, Si ] ]
fatigueLimit (scalar) – Fatigue limit indicating the minimum S that can cause fatigue.

Raises

ValueError – If the data dimension is not 2. If the data length is less than 2. If the fatigueLimit is less than or equal 0. If N_i or S_i is less than or equal 0.

Examples

>>> from ffpack.utils import SnCurveFitter
>>> data = [ [ 10, 3 ], [ 1000, 1 ] ]
>>> fatigueLimit = 0.5
>>> snCurveFitter = SnCurveFitter( data, fatigueLimit )

getN(S)

Query fatigue life N for a given S

Parameters: S (scalar) – Input S for fatigue life query.
Returns: rst – Fatigue life under the query S. If S is less than or equal fatigueLimit, -1 will be returned.
Return type: scalar
Raises: ValueError – If the S is less than or equal 0.

Examples

>>> rst = snCurveFitter.getN( 2 )

Sequence filter

ffpack.utils.sequenceFilter.sequenceHysteresisFilter(data, gateSize)

Filter data within the gateSize.

Any cycle that has an amplitude smaller than the gate is removed from the data. This is done by scan the data, i.e., point i, to check if the next points, i.e., i + 1, i + 2, … are within the gate from point i.

Parameters

data (1darray) – Sequence data to get peaks and valleys.
gateSize (scalar) – Gate size to filter the data.

Returns

rst – A list contains the filtered data.

Return type

1darray

Raises

ValueError – If the data dimension is not 1. If the data length is less than 2. If gateSize is not a scalar or not positive.

Examples

>>> from ffpack.utils import sequenceHysteresisFilter
>>> data = [ 2, 5, 3, 6, 2, 4, 1, 6, 1, 3, 1, 5, 3, 6, 3, 6, 4, 5, 2 ]
>>> gateSize = 3.0
>>> rst = sequenceHysteresisFilter( data, gateSize )

ffpack.utils.sequenceFilter.sequencePeakValleyFilter(data, keepEnds=False)

Remove the intermediate value and only get the peaks and valleys of the data

The peak and valley refer the data points that are EXACTLY above and below the neighbors, not equal.

Parameters

data (1darray) – Sequence data to get peaks and valleys.
keepEnds (bool, optional) – If two ends of the original data should be preserved.

Returns

rst – A list contains the peaks and valleys of the data.

Return type

1darray

Raises

ValueError – If the data dimension is not 1. If the data length is less than 2 with keedEnds == False. If the data length is less than 3 with keedEnds == True.

Examples

>>> from ffpack.utils import sequencePeakValleyFilter
>>> data = [ -0.5, 1.0, -2.0, 3.0, -1.0, 4.5, -2.5, 3.5, -1.5, 1.0 ]
>>> rst = sequencePeakValleyFilter( data )