tmdsimpy.nlforces.JenkinsForce

class tmdsimpy.nlforces.JenkinsForce(Q, T, kt, Fs)

Bases: HystereticForce

Implementation of the a Jenkins element model for hysteresis in joints.

Parameters:

Q(Nnl, N) numpy.ndarray

Matrix tranform from the N degrees of freedom (DOFs) of the system to the Nnl local nonlinear DOFs.

T(N, Nnl) numpy.ndarray

Matrix tranform from the local Nnl forces to the N global DOFs.

ktfloat

Tangential stiffness coefficient.

Fsfloat

Slip force.

See also

VectorJenkins

Implementation that uses a more efficient vectorization of local forces for AFT calculation.

Notes

Implementation is tested for float kt and Fs, but may work for vectors of size Nnl.

Tests also focus on Nnl == 1, class may not work for simultaneous elements.

__init__(Q, T, kt, Fs)

Methods

__init__(Q, T, kt, Fs)
aft(U, w, h[, Nt, tol, max_repeats, atol, rtol])	Implementation of the alternating frequency-time method to extract harmonic nonlinear force coefficients (hysteretic forces).
force(X[, update_hist])	Calculate global nonlinear forces for some global displacement vector.
init_history()	Method to initialize history variables for the hysteretic model.
init_history_harmonic(unlth0[, h])	Initialize history variables for harmonic (AFT) analysis.
instant_force(unl, unldot[, update_prev])	Calculates local force based on local nonlinear displacements.
instant_force_harmonic(unl, unldot, h, cst)	Evaluates the force at a instantaneous set of displacement and velocity along with harmonic derivatives.
local_force_history(unlt, unltdot, h, cst, ...)	Evaluate the local forces for steady-state harmonic motion used in AFT.
nl_force_type()	Method to identify the force type as hysteretic.
reset_real_mu()	Resets friction slip force to initial value.
set_prestress_mu()	Sets friction slip force to zero while saving initial value in a different variable.
update_history(unl, fnl)	Updates hysteretic states by storing displacement and force values.

aft(U, w, h, Nt=128, tol=1e-07, max_repeats=2, atol=1e-10, rtol=1e-10)

Implementation of the alternating frequency-time method to extract harmonic nonlinear force coefficients (hysteretic forces).

Parameters:

U(N*Nhc,) numpy.ndarray

Displacement harmonic DOFs (global)

wfloat

Frequency in rad/s. Needed in case there is velocity dependency.

hnumpy.ndarray, sorted

List of harmonics. The list corresponds to Nhc harmonic components.

Ntint power of 2, optional

Number of time steps used in evaluation. The default is 128.

tolfloat, optional

This argument is ignored for hysteretic forces. It is included for compatability of interface. The default is 1e-7.

max_repeatsint, optional

Number of times to repeat the time series to converge the initial state with local_force_history. Two is sufficient for slider models. The default is 2.

atolfloat, optional

Absolute tolerance on local_force_history force convergence to steady-state (final state of cycle). The default is 1e-10.

rtolfloat, optional

Relative tolerance on local_force_history force convergence to steady-state (final state of cycle). The default is 1e-10.

Returns:

Fnl(N*Nhc,) numpy.ndarray

Nonlinear hamonic force coefficients

dFnldU(N*Nhc,N*Nhc) numpy.ndarray

Jacobian of Fnl with respect to U

dFnldw(N*Nhc,) numpy.ndarray

Jacobian of Fnl with respect to w

Notes

A calc_grad optional argument should be added in the future to allow for compatibility with other functions/methods/classes.

WARNING: Needs further verification for cases using multiple nonlinear displacements and or nonlinear output forces.

WARNING: Does not support velocity dependencies in gradient calculation

force(X, update_hist=False)

Calculate global nonlinear forces for some global displacement vector.

Parameters:

X(N,) numpy.ndarray

Global displacements.

update_histbool, optional

Flag to save displacement and force from the evaluation as history variables for subsequent calls to this function. The default is False.

Returns:

F(N,) numpy.ndarray

Global nonlinear force.

dFdX(N,N) numpy.ndarray

Derivative of F with respect to X.

init_history()

Method to initialize history variables for the hysteretic model.

This consists of setting previous displacements and forces to be zero.

Returns:

None.

init_history_harmonic(unlth0, h=array([0]))

Initialize history variables for harmonic (AFT) analysis.

Parameters:

unlth0(Nnl,) numpy.ndarray

Zeroth harmonic contributions to a time series of displacements. History displacements are initialized at this value.

hnumpy.ndarray, sorted

List of harmonics used in subsequent analysis. The default is numpy.array([0]).

Returns:

None.

instant_force(unl, unldot, update_prev=False)

Calculates local force based on local nonlinear displacements.

Parameters:

unl(Nnl,) numpy.ndarray

Local nonlinear displacements to evaluate force at.

unldot(Nnl,) numpy.ndarray

Local nonlinear velocities to evaluate force at.

update_prevbool, optional

Flag to store the results of the evaluation for the start of the subsequent step. The default is False.

Returns:

fnlfloat

Evaluated local nonlinear forces.

dfnldunlfloat

Derivative of fnl with respect to current displacements unl.

dfnldupfloat

Derivative of fnl with respect to previous displacements.

dfnldfpfloat

Derivative of fnl with respect to previous forces.

Notes

Implementation only allows for a single nonlinear element, thus output shapes are reduced to scalar.

instant_force_harmonic(unl, unldot, h, cst, update_prev=False)

Evaluates the force at a instantaneous set of displacement and velocity along with harmonic derivatives.

Parameters:

unl(Nnl,) numpy.ndarray

Local nonlinear displacements to evaluate force at.

unldot(Nnl,) numpy.ndarray

Local nonlinear velocities to evaluate force at.

h1D numpy.ndarray, sorted

List of harmonics used in subsequent analysis. Corresponds to Nhc harmonic components.

cst(Nhc,) numpy.ndarray

Evaluation of harmonics without coefficients at the given instant in time. If zeroth harmonic is included, the first entry is 1.0. Beyond that, it is cosine and then sine at the appropriate harmonic for the given instant in time then the next harmonic etc.

update_prevbool, optional

Flag to store the results of the evaluation for the start of the subsequent step. The default is False.

Returns:

fnl(1,) numpy.ndarray

Local nonlinear forces

dfduh(1, 1, Nhc) numpy.ndarray

Derivative of fnl with respect to displacement harmonic coefficients.

dfdudh(1, 1, Nhc) numpy.ndarray

Derivative of fnl with respect to velocities harmonic coefficients.

Notes

Starts calculation based on init_history_harmonic.

Implementation of this function may work for Nnl > 1, but this function depends on instant_force, which does not support Nnl > 1.

local_force_history(unlt, unltdot, h, cst, unlth0, max_repeats=2, atol=1e-10, rtol=1e-10)

Evaluate the local forces for steady-state harmonic motion used in AFT. (General hysteretic model implementation)

Parameters:

unlt(Nt,Nnl) numpy.ndarray

Local displacements, rows are different time instants and columns are different displacement DOFs.

unltdot(Nt,Nnl) numpy.ndarray

Local velocities, rows are different time instants and columns are different displacement DOFs.

h1D numpy.ndarray, sorted

List of harmonics used in subsequent analysis. Corresponds to Nhc harmonic components.

cst(Nt,Nhc) numpy.ndarray

Evaluation of each harmonic component (columns) at a given instant in time (row = instant in time). These are without any harmonic coefficients, so are just cosine and sine evaluations.

unlth0(Nnl,) numpy.ndarray

Zeroth harmonic contributions to a time series of displacements. This is passed to init_history_harmonic to initialize model.

max_repeatsint, optional

Number of times to repeat the time series to converge the initial state. Two is sufficient for slider models. The default is 2.

atolfloat, optional

Absolute tolerance on force time series convergence to steady-state (final state of cycle). The default is 1e-10.

rtolfloat, optional

Relative tolerance on force time series convergence to steady-state (final state of cycle). The default is 1e-10.

Returns:

ft(Nt,Nnl) numpy.ndarray

Local nonlinear forces. First index is time instants, second index is which local nonlinear force DOF.

dfduh(Nt,Nnl,Nnl,Nhc) numpy.ndarray

Derivative of forces w.r.t. displacement harmonic coefficients. First two indices correspond to ft. Third index corresponds to which local nonlinear displacement. Fourth index corresponds to which of the Nhc harmonic components.

dfdudh(Nt,Nnl,Nnl,Nhc) numpy.ndarray

Derivative of forces w.r.t. velocities harmonic coefficients. First two indices correspond to ft. Third index corresponds to which local nonlinear displacement. Fourth index corresponds to which of the Nhc harmonic components.

Notes

WARNING: Derivatives with respect to harmonic velocities are not fully tested or considered so may be incorrect.

Convergence criteria is atol or rtol passes. To require a choice, pass in -1 for the other.

nl_force_type()

Method to identify the force type as hysteretic.

Returns:

int

1, indicating hysteretic force type.

reset_real_mu()

Resets friction slip force to initial value. Useful for after prestress analysis with zero friction coefficient.

Returns:

None

set_prestress_mu()

Sets friction slip force to zero while saving initial value in a different variable. Useful for prestress analysis.

Returns:

None

update_history(unl, fnl)

Updates hysteretic states by storing displacement and force values.

Parameters:

unl(Nnl,) numpy.ndarray

Local nonlinear element displacements to be saved.

fnl(Nnl,) numpy.ndarray

Local nonlinear element forces to be saved.

Returns:

None.