tmdsimpy.nlforces.HystereticForce

class tmdsimpy.nlforces.HystereticForce(Q, T)

Bases: NonlinearForce

Template class for hysteretic nonlinear forces.

This type of forces requires knowledge of the displacement history to calculate forces. This class does not actually implement any nonlinear forces.

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.

Notes

Each of the local Nnl nonlinear forces can depend on all nonlinear DOFs.

__init__(Q, T)

Methods

__init__(Q, T)
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)	Template force function for evaluating the nonlinear force for a set of global displacements.
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_harmonic(unl, unldot, h, cst)	Evaulating local forces at an instant in time with harmonic gradients.
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.

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)

Template force function for evaluating the nonlinear force for a set of global displacements.

Parameters:

X(N,) numpy.ndarray

Global displacements

Returns:

F(N,) numpy.ndarray

Global forces

dFdX(N,N) numpy.ndarray

Derivative of global forces with respect to global displacements X

init_history()

Method to initialize history variables for the hysteretic model.

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

Returns:

None.

init_history_harmonic(unlth0, h)

Initialize history variables for harmonic (AFT) analysis.

Parameters:

unlth0(Nnl,) numpy.ndarray

Zeroth harmonic contributions to a time series of displacements. History displacements can be initialized at this value if desired. Some models may choose to initialize harmonic displacements at other values. This is included for compatibility in those cases.

hnumpy.ndarray, sorted

List of harmonics used in subsequent analysis.

Returns:

None.

instant_force_harmonic(unl, unldot, h, cst)

Evaulating local forces at an instant in time with harmonic gradients.

Parameters:

unl(Nnl,) numpy.ndarray

Local displacements for force calculation

unltdot(Nnl,) numpy.ndarray

Local velocities for force calculation

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.

Returns:

ft(Nnl,) numpy.ndarray

Local nonlinear forces

dfduh(Nnl,Nnl,Nhc) numpy.ndarray

Derivative of forces w.r.t. displacement harmonic coefficients. First index corresponds to ft. Second index corresponds to unl. Third index corresponds to which of the Nhc harmonic components.

dfdudh(Nnl,Nnl,Nhc) numpy.ndarray

Derivative of forces w.r.t. velocities harmonic coefficients. First index corresponds to ft. Second index corresponds to unl. Third index corresponds to which of the Nhc harmonic components.

Notes

Uses history initialized in init_history_harmonic. Updates history for the next call based on the current results.

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.