Mechanical Models
Small strain mechanical constitutive models including elasticity, plasticity, viscoelasticity, and damage.
-
void abaqus2smart_M_light(const double *stress, const double *ddsdde, const int &nstatev, double *statev, const int &ndi, const int &nshr, arma::vec &sigma, arma::mat &Lt, arma::vec &Wm, arma::vec &statev_smart)
Light transfer from Abaqus output arrays to simcoon format (mechanical).
Converts stress, tangent, and state variables from Abaqus format. Use this after calling an external Abaqus UMAT to retrieve results.
- Parameters:
stress – Abaqus stress array (ntens)
ddsdde – Abaqus tangent operator array (ntens \(\times\) ntens, column-major)
nstatev – Number of state variables
statev – Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
sigma – [out] simcoon stress vector (6)
Lt – [out] simcoon tangent matrix ( \(6 \times 6\))
Wm – [out] simcoon work quantities vector (4): Wm, Wm_r, Wm_ir, Wm_d
statev_smart – [out] simcoon state variables vector
-
void abaqus2smart_M(const double *stress, const double *ddsdde, const double *stran, const double *dstran, const double *time, const double &dtime, const double &temperature, const double &Dtemperature, const int &nprops, const double *props, const int &nstatev, double *statev, const int &ndi, const int &nshr, const double *drot, arma::vec &sigma, arma::mat &Lt, arma::vec &Etot, arma::vec &DEtot, double &T, double &DT, double &Time, double &DTime, arma::vec &props_smart, arma::vec &Wm, arma::vec &statev_smart, arma::mat &DR, bool &start)
Full transfer from Abaqus input arrays to simcoon format (mechanical).
Converts all UMAT inputs from Abaqus format to simcoon Armadillo format. STATEV layout: Wm (4), then, when ndi < 3, the 6 - ntens stress-free strain components the material point solves (condensed_state.hpp, simcoon order, rotated with DROT and returned in Etot), then the law’s state variables (nstatev - 4 - (6 - ntens)). Use this before calling a simcoon constitutive model from an Abaqus UMAT wrapper.
- Parameters:
stress – Abaqus stress array
ddsdde – Abaqus tangent operator array
stran – Abaqus total strain array
dstran – Abaqus strain increment array
time – Abaqus time array [step_time, total_time]
dtime – Time increment
temperature – Temperature at start of increment
Dtemperature – Temperature increment
nprops – Number of material properties
props – Abaqus material properties array
nstatev – Number of state variables
statev – Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
drot – Abaqus rotation increment matrix ( \(3 \times 3\), column-major)
sigma – [out] simcoon stress vector
Lt – [out] simcoon tangent matrix
Etot – [out] simcoon total strain vector
DEtot – [out] simcoon strain increment vector
T – [out] simcoon temperature
DT – [out] simcoon temperature increment
Time – [out] simcoon total time
DTime – [out] simcoon time increment
props_smart – [out] simcoon properties vector
Wm – [out] simcoon work quantities vector
statev_smart – [out] simcoon state variables vector
DR – [out] simcoon rotation matrix
start – [out] true if this is the first increment
-
void abaqus2smart_T(const double *stress, const double *ddsdde, const double *ddsddt, const double *drplde, const double &drpldt, const double *stran, const double *dstran, const double *time, const double &dtime, const double &temperature, const double &Dtemperature, const int &nprops, const double *props, const int &nstatev, double *statev, const int &ndi, const int &nshr, const double *drot, arma::vec &sigma, arma::mat &dSdE, arma::vec &dSdT, arma::vec &drpldE, double &drpldT, arma::vec &Etot, arma::vec &DEtot, double &T, double &DT, double &Time, double &DTime, arma::vec &props_smart, arma::vec &Wm, arma::vec &Wt, arma::vec &statev_smart, arma::mat &DR, bool &start)
Full transfer from Abaqus input arrays to simcoon format (thermomechanical).
Converts all thermomechanical UMAT inputs from Abaqus format. Includes thermal tangent operators and heat generation terms. STATEV layout: Wm (4), Wt (3), then the stress-free strain components when ndi < 3 (as abaqus2smart_M), then the law’s state variables.
- Parameters:
stress – Abaqus stress array
ddsdde – Abaqus mechanical tangent array
ddsddt – Abaqus stress-temperature tangent array
drplde – Abaqus heat generation-strain tangent array
drpldt – Abaqus heat generation-temperature tangent
stran – Abaqus total strain array
dstran – Abaqus strain increment array
time – Abaqus time array
dtime – Time increment
temperature – Temperature at start of increment
Dtemperature – Temperature increment
nprops – Number of material properties
props – Abaqus material properties array
nstatev – Number of state variables
statev – Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
drot – Abaqus rotation increment matrix
sigma – [out] simcoon stress vector
dSdE – [out] simcoon mechanical tangent matrix
dSdT – [out] simcoon stress-temperature derivative (6)
drpldE – [out] simcoon heat generation-strain derivative (6)
drpldT – [out] simcoon heat generation-temperature derivative
Etot – [out] simcoon total strain vector
DEtot – [out] simcoon strain increment vector
T – [out] simcoon temperature
DT – [out] simcoon temperature increment
Time – [out] simcoon total time
DTime – [out] simcoon time increment
props_smart – [out] simcoon properties vector
Wm – [out] simcoon mechanical work quantities vector
Wt – [out] simcoon thermal work quantities vector
statev_smart – [out] simcoon state variables vector
DR – [out] simcoon rotation matrix
start – [out] true if this is the first increment
-
void smart2abaqus_M(double *stress, double *ddsdde, double *statev, const int &ndi, const int &nshr, const arma::vec &sigma, const arma::vec &statev_smart, const arma::vec &Wm, const arma::mat &Lt, const bool &nlgeom = true, const arma::vec &Etot_end = arma::vec())
Transfer simcoon output to Abaqus format (mechanical, simple).
Converts stress, tangent, and state variables to Abaqus format. Use this to return results from a simcoon model to an Abaqus UMAT.
- Parameters:
stress – [out] Abaqus stress array
ddsdde – [out] Abaqus tangent operator array
statev – [out] Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
sigma – simcoon stress vector
statev_smart – simcoon state variables vector
Wm – simcoon work quantities vector
Lt – simcoon tangent matrix (dsigma/deps of the corotated kernel), condensed on the element’s components when ndi < 3 (select_umat_M): ddsdde is its block on them
nlgeom – whether the step is geometrically nonlinear (abaqus_nlgeom(dfgrd1)): ddsdde then gets abaqus_jacobian of Lt for the 3D, plane-strain and axisymmetric cases; plane stress and 1D take the condensed tangent as it is
Etot_end – total strain at the end of the increment (Etot + DEtot): when ndi < 3 its stress-free components are stored in STATEV after Wm (layout in abaqus2smart_M); empty leaves those slots untouched
-
arma::mat abaqus_jacobian(const arma::mat &Lt, const arma::vec &sigma)
The Abaqus material Jacobian of a corotated kernel tangent.
Abaqus defines DDSDDE through the Jaumann rate of the Kirchhoff stress divided by J: \( \frac{1}{J}\frac{\partial (J\boldsymbol{\sigma})}{\partial \boldsymbol{\varepsilon}} = \frac{\partial \boldsymbol{\sigma}}{\partial \boldsymbol{\varepsilon}} + \boldsymbol{\sigma} \otimes \mathbf{I} \). The kernels return the first term in Abaqus’s corotated frame; this adds the symmetric part of the second (the default symmetric solver keeps that part). Used by smart2abaqus_M and smart2abaqus_T for NLGEOM steps. Without NLGEOM the Jacobian is the kernel tangent (J = 1 by assumption), which also keeps linear-perturbation procedures (*FREQUENCY, *BUCKLE) on the right stiffness.
- Parameters:
Lt – kernel tangent (6x6, Voigt, engineering shears)
sigma – Cauchy stress at the end of the increment (6)
- Returns:
DDSDDE as a 6x6 matrix
-
bool abaqus_nlgeom(const double *dfgrd1)
Whether Abaqus runs the step with NLGEOM: DFGRD1 is the identity otherwise.
- Parameters:
dfgrd1 – the DFGRD1 array of the UMAT interface (9 values)
-
std::string abaqus_umat_name(const char *cmname)
The law name an Abaqus CMNAME carries: its characters up to the first blank or NUL (80 at most), without the kinematic-form suffix
_Rof abaqus_kinematic_form().EPICP_closed_Rnames the lawEPICP_closedin its rate form; the_closedsuffix is recognised in any case (Abaqus upper-cases material names:EPICP_CLOSED). A token longer than five characters that the registry (umat_registry()) does not hold and that does not end with_closedcarries a descriptive tail (EPICP_STEEL): its first five characters are the law, said once per name on the error stream. A token that then still names no law stops the analysis.- Parameters:
cmname – the CMNAME argument of the UMAT (space padded, 80 characters)
-
int abaqus_kinematic_form(const char *cmname)
The kinematic form an Abaqus material name asks for under NLGEOM.
The total form (strain space, \( \ln\mathbf{U} \) and its dual stress, read from DFGRD0/DFGRD1, no history) is the default; the suffix
_R(e.g.EPICP_R) asks for the rate form (log_R, corate 3), whose accumulated strain and frame rotation take the last abaqus_kinematic_statev() STATEV entries._R(case insensitive) must end the name token read by abaqus_umat_name(); any other tail is part of the law name. A NUL-terminated name (a C caller) is read up to its terminator only.- Parameters:
cmname – the CMNAME argument of the UMAT (space padded, 80 characters)
- Returns:
corate_type_total, or 3 for
_R
-
int abaqus_kinematic_statev(const int &corate_type)
STATEV entries the kinematic form keeps at the end of STATEV: 15 for the rate form (the accumulated box strain, 6, and the log_R frame rotation, 9, column-major), 0 for the total form.
-
int fea_law_statev(const int &nstatev, const int &nheader, const int &ndi, const int &nshr, const int &corate_type)
STATEV entries left to the law behind an FE bridge (Abaqus UMAT, Ansys USERMAT).
STATEV holds, in order, the bridge’s header (
nheader:4 for Wm, 7 for Wm and Wt), the stress-free strain of a condensed state (ndi < 3, make_condensed_state()), the law’s variables, then the abaqus_kinematic_statev() entries of the kinematic form (Abaqus only). The STATEV size (Abaqus DEPVAR, Ansys TB,STATE) must cover the bridge’s own entries: switching an Abaqus material to_Rasks for 15 more. The law’s own count is not known here; a size short of it shifts the trailing entries into the law’s variables.- Parameters:
nstatev – the STATEV size (NSTATV, nStatev)
nheader – 4 (umat_singleM, usermat_singleM) or 7 (umat_singleT)
ndi – number of direct stress components
nshr – number of shear stress components
corate_type – abaqus_kinematic_form(), corate_type_total for Ansys
- Throws:
std::invalid_argument – when the size is below the bridge’s own entries
- Returns:
the law’s share of STATEV, \( \geq 0 \)
-
bool fea_numerical_failure(const std::exception &e)
Whether an exception out of a material-point call is a numerical failure of the trial state, which a smaller increment may cure.
True for a std::runtime_error (a simcoon_error of a matrix function or decomposition, an Armadillo failure) other than simcoon::exception_solver, which the dispatch raises for an unsupported configuration (a refused corate or formulation); false for those and for an input error (std::logic_error: an unknown law, a short STATEV, an unsupported element layout). The FE entries (umat_singleM, umat_singleT, usermat_singleM) request a smaller increment on true and stop the analysis on false.
-
bool abaqus_finite_route(const std::string &umat_name, const int &ndi, const int &corate_type, const bool &thermomechanical, const double *dfgrd1)
Whether an Abaqus call runs the finite-strain route (the deformation gradient driving select_umat_M_finite / the thermomechanical finite dispatch).
True for an NLGEOM step (abaqus_nlgeom()) and a law the finite dispatch serves in the requested form (every thermomechanical law under the rate form, the total form where total_formulation_serves_T(); the mechanical ones with a finite kernel in the registry (umat_entry::finite), the total form only where total_formulation_serves()), whatever (NDI, NSHR): a condensed state (plane stress, beams) solves its free stretches on the finite route (run_umat_M / run_umat_T, condensed_F). Otherwise the bridge keeps the corotational small-strain route on STRAN/DSTRAN (NLGEOM=NO, the small-strain-only laws).
ndiis kept for the callers’ symmetry with the small-strain route.
-
void abaqus2smart_finite(state_variables &sv, const double *drot, const double *dfgrd0, const double *dfgrd1, const double *kin_statev, const int &corate_type, const double &DTime, const condensed_state &cs)
Abaqus -> the finite-strain state of a material point, from the deformation gradients.
Called after abaqus2smart_M / abaqus2smart_T, whose STRESS read (rotated by DROT by Abaqus) it turns back into the start Kirchhoff stress in the global basis, \( \boldsymbol\tau_n = J_0\,\Delta\mathbf{R}^{T}\boldsymbol\sigma\,\Delta\mathbf{R} \). F0, F1 = DFGRD0, DFGRD1; the box strain is \( \ln\mathbf{U}_0 \) (total form) or the accumulated log_R strain and frame read from
kin_statev(rate form; zero entries, Abaqus’s initial STATEV, read as an undeformed start); DR and Detot follow from corate_kinematics, the Green-Lagrange pair from F. STRAN, DSTRAN and DROT play no further part. For a condensed state (csactive) the host’s free components of DFGRD0/1 are placeholders: F0 is rebuilt from the point’s strain state (condensed_F; the free box strain of the last increment comes fromkin_statevunder the rate form, from the STATEV slots of the stress-free strain that abaqus2smart_M / _T read into sv.Etot under the total form) and F1 with the free stretches of the start, the Newton of run_umat_M / run_umat_T moving them to the stress-free state.- Parameters:
sv – [in/out] the global state variables of the point
drot – DROT (9, column-major), the rotation Abaqus applied to STRESS
dfgrd0 – DFGRD0 (9, column-major)
dfgrd1 – DFGRD1 (9, column-major)
kin_statev – the last abaqus_kinematic_statev() entries of STATEV (rate form), unused otherwise
corate_type – corate_type_total or 3 (abaqus_kinematic_form())
DTime – time increment
cs – the condensed state of (NDI, NSHR), inactive for three direct components
-
arma::vec finite_box_strain_end(const state_variables &sv, const int &corate_type)
Box strain at the end of the increment on the finite route: the commit of set_start, \( \Delta\mathbf{R}\,\mathbf{e}\,\Delta\mathbf{R}^T + \Delta\mathbf{e} \) under the rate form, \( \mathbf{H}_{n+1} = \mathbf{H}_n + \Delta\mathbf{H} \) under the total one.
- Parameters:
sv – the state after the law
corate_type – corate_type_total or 3
- Returns:
the strain (6), what the rate form stores in its kinematic STATEV and a condensed state in its stress-free strain slots
-
void smart2abaqus_finite_M(const state_variables &sv, const arma::mat &Lt, const int &corate_type, arma::vec &sigma, arma::mat &ddsdde, double *kin_statev)
The finite-strain point -> the Abaqus stress and material Jacobian (mechanical).
STRESS is the Cauchy stress \( \boldsymbol\tau/J \) in the global basis, and DDSDDE the Jacobian Abaqus defines under NLGEOM, \( \frac{1}{J}\,\partial\Delta(J\boldsymbol\sigma)/\partial\Delta\boldsymbol\varepsilon \) with the Jaumann rate of the Kirchhoff stress: the box tangent mapped to \( \partial\mathbf{S}/\partial\mathbf{E} \) (DtauDe_corate_2_DSDE) then to that rate (DSDE_2_Dsigma_JaumannDD). It replaces abaqus_jacobian, which serves the corotational route. The rate form writes its end strain and frame to
kin_statev.- Parameters:
sv – the global state variables after the finite dispatch
Lt – the box tangent of the dispatch (state_variables_M::Lt or state_variables_T::dSdE)
corate_type – corate_type_total or 3
sigma – [out] Cauchy stress (6)
ddsdde – [out] Abaqus Jacobian (6x6)
kin_statev – [out] the last abaqus_kinematic_statev() entries of STATEV (rate form)
-
void smart2abaqus_finite_T(const state_variables_T &sv, const int &corate_type, const double &DTime, arma::vec &sigma, arma::mat &ddsdde, arma::vec &ddsddt, double &rpl, arma::vec &drplde, double &drpldt, double *kin_statev)
The finite-strain point -> the Abaqus outputs of a coupled temperature-displacement step.
smart2abaqus_finite_M for STRESS and DDSDDE, then the heat per unit CURRENT volume and time, as Abaqus integrates it over the deformed body. With \( r \) the heat of the increment per reference volume and \( J = \det\mathbf{F}_1 \): \( \mathrm{RPL} = r/(J\Delta t) \), \( \mathrm{DRPLDT} = (\partial r/\partial\theta)/(J\Delta t) \), \( \mathrm{DDSDDT} = (\partial\boldsymbol\tau/\partial\theta)/J \) ( \( J \) fixed at fixed \( \mathbf{F} \)) and, from \( \delta\mathbf{E} = \mathbf{F}^{T}\delta\boldsymbol\varepsilon\,\mathbf{F} \) and \( \delta J = J\,\mathrm{tr}\,\delta\boldsymbol\varepsilon \), \( \mathrm{DRPLDE} = \left(\mathbf{F}\,\frac{\partial r}{\partial\mathbf{E}}\,\mathbf{F}^{T} - r\,\mathbf{I}\right)/(J\Delta t) \), \( \partial r/\partial\mathbf{E} \) from box_covector_2_dE(). All zero rates at \( \Delta t = 0 \).
- Parameters:
sv – the global state variables after the finite dispatch
corate_type – corate_type_total or 3
DTime – time increment
sigma – [out] Cauchy stress (6)
ddsdde – [out] Abaqus Jacobian (6x6)
ddsddt – [out] DDSDDT (6)
rpl – [out] RPL
drplde – [out] DRPLDE (6)
drpldt – [out] DRPLDT
kin_statev – [out] the last abaqus_kinematic_statev() entries of STATEV (rate form)
-
void smart2abaqus_M_full(double *stress, double *ddsdde, double *stran, double *dstran, double *time, double &dtime, double &temperature, double &Dtemperature, int &nprops, double *props, int &nstatev, double *statev, const int &ndi, const int &nshr, double *drot, const arma::vec &sigma, const arma::mat &Lt, const arma::vec &Etot, const arma::vec &DEtot, const double &T, const double &DT, const double &Time, const double &DTime, const arma::vec &props_smart, const arma::vec &Wm, const arma::vec &statev_smart, const arma::mat &DR, bool &start)
Full transfer from simcoon to Abaqus format (mechanical).
Converts all simcoon outputs to Abaqus UMAT format. Use this for complete state transfer in external UMAT wrappers.
- Parameters:
stress – [out] Abaqus stress array
ddsdde – [out] Abaqus tangent operator array
stran – [out] Abaqus total strain array
dstran – [out] Abaqus strain increment array
time – [out] Abaqus time array
dtime – [out] Time increment
temperature – [out] Temperature
Dtemperature – [out] Temperature increment
nprops – Number of material properties
props – [out] Abaqus material properties array
nstatev – Number of state variables
statev – [out] Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
drot – [out] Abaqus rotation increment matrix
sigma – simcoon stress vector
Lt – simcoon tangent matrix
Etot – simcoon total strain vector
DEtot – simcoon strain increment vector
T – simcoon temperature
DT – simcoon temperature increment
Time – simcoon total time
DTime – simcoon time increment
props_smart – simcoon properties vector
Wm – simcoon work quantities vector
statev_smart – simcoon state variables vector
DR – simcoon rotation matrix
start – simcoon start flag
-
void smart2abaqus_T(double *stress, double *ddsdde, double *ddsddt, double *drplde, double &drpldt, double &rpl, double *statev, const int &ndi, const int &nshr, const arma::vec &sigma, const arma::vec &statev_smart, const double &r, const arma::vec &Wm, const arma::vec &Wt, const arma::mat &dSdE, const arma::vec &dSdT, const arma::vec &drpldE, const double &drpldT, const bool &nlgeom = true, const arma::vec &Etot_end = arma::vec())
Transfer simcoon output to Abaqus format (thermomechanical).
Converts thermomechanical outputs to Abaqus UMAT format. Includes thermal tangent operators and heat generation.
- Parameters:
stress – [out] Abaqus stress array
ddsdde – [out] Abaqus mechanical tangent array
ddsddt – [out] Abaqus stress-temperature tangent array
drplde – [out] Abaqus heat generation-strain tangent array
drpldt – [out] Abaqus heat generation-temperature tangent
rpl – [out] Abaqus heat generation rate
statev – [out] Abaqus state variables array
ndi – Number of direct stress components
nshr – Number of shear stress components
sigma – simcoon stress vector
statev_smart – simcoon state variables vector
r – simcoon heat generation rate
Wm – simcoon mechanical work quantities vector
Wt – simcoon thermal work quantities vector
dSdE – simcoon mechanical tangent matrix (condensed when ndi < 3, select_umat_T)
dSdT – simcoon stress-temperature derivative (6, condensed when ndi < 3)
drpldE – simcoon heat generation-strain derivative (6, condensed when ndi < 3)
drpldT – simcoon heat generation-temperature derivative
nlgeom – as smart2abaqus_M
Etot_end – as smart2abaqus_M, stored after Wm and Wt (layout in abaqus2smart_T)
-
fea_components ansys_components(const int &nDirect, const int &nShear)
The Ansys components: 11, 22, 33, 12, 23, 13 in 3D (13 and 23 swapped), 11, 22, 33, 12 in plane strain and axisymmetry, 11, 22, 12 in plane stress, 11 in 1D.
- Throws:
std::invalid_argument – for another (nDirect, nShear)
-
template<class V>
void fe2vec(const double *a, const fea_components &K, V &v) FE vector (ntens) -> simcoon 6 entries, zero outside K.
-
template<class V>
void vec2fe(const V &v, const fea_components &K, double *a) simcoon 6 entries -> FE vector (ntens).
-
void fe2mat(const double *a, const fea_components &K, arma::mat &M)
FE ntens x ntens matrix, column-major (Fortran) -> the K x K block of a 6x6 (zero elsewhere).
-
void mat2fe(const arma::mat &M, const fea_components &K, double *a)
The K x K block of a 6x6 -> FE ntens x ntens matrix, column-major (Fortran).
-
void ansys2smart_M(const double *stress, const double *dsdePl, const double *strain, const double *dstrain, const double &Time, const double &Temp, const double &dTemp, const int &nprops, const double *props, const int &nstatev, const double *statev, const int &nDirect, const int &nShear, arma::vec &sigma, arma::mat &Lt, arma::vec &Etot, arma::vec &DEtot, double &T, double &DT, arma::vec &props_smart, arma::vec &Wm, arma::vec &statev_smart, bool &start)
Ansys USERMAT -> simcoon (mechanical).
Ansys passes the element’s ncomp components (11, 22, 33, 12, 23, 13 in 3D: 13 and 23 swapped against simcoon; 11, 22, 33, 12 in plane strain and axisymmetry; 11, 22, 12 in plane stress; 11 in 1D). USTATEV holds the four works Wm, then the stress-free strain of a condensed state (plane stress, 1D: the components select_umat_M solves, in simcoon order), then the law’s variables, as the Abaqus bridge (abaqus2smart_M). Ansys hands stress and strain in its co-rotated frame, where every variable is defined and updated: the rotation increment of the law is the identity (the former rotateM argument is unused, reserved by Ansys).
- Parameters:
stress – Ansys stress (ncomp)
dsdePl – Ansys tangent on input (ncomp x ncomp, column-major), as abaqus2smart_M reads DDSDDE
strain – Ansys total strain at the start of the increment (ncomp)
dstrain – Ansys strain increment (ncomp)
Time – time at the start of the increment
Temp – temperature at the start of the increment
dTemp – temperature increment
nprops – number of law properties
props – the law properties (the bridge’s model code excluded)
nstatev – USTATEV size
statev – USTATEV
nDirect – number of direct components
nShear – number of shear components
sigma – [out] stress (6)
Lt – [out] the input tangent (6x6, zero outside the element’s components)
Etot – [out] total strain at the start (6), the stored stress-free strain included
DEtot – [out] strain increment (6)
T – [out] temperature
DT – [out] temperature increment
props_smart – [out] law properties
Wm – [out] works (4)
statev_smart – [out] law state variables
start – [out] first increment (Time = 0)
- Throws:
std::invalid_argument – for a component layout the bridge does not serve
-
void smart2ansys_M(double *stress, double *dsdePl, double *statev, double &sedEl, double &sedPl, const int &nDirect, const int &nShear, const arma::vec &sigma, const arma::mat &Lt, const arma::vec &Wm, const arma::vec &statev_smart, const arma::vec &Etot_end)
simcoon -> Ansys USERMAT (mechanical).
The stress and dsdePl (ncomp x ncomp, column-major) on the element’s components; the tangent arrives condensed from select_umat_M for plane stress and 1D and goes out as it is (the kernel tangent, no further term). USTATEV gets Wm, the solved stress-free strain and the law’s variables (ansys2smart_M()). sedEl and sedPl, which Ansys uses for output only, get the recoverable work \( W_m^r \) and the non-recoverable one \( W_m^{ir} + W_m^d \).
- Parameters:
stress – [out] Ansys stress (ncomp)
dsdePl – [out] Ansys tangent (ncomp x ncomp, column-major)
statev – [out] USTATEV
sedEl – [out] elastic work (Ansys output)
sedPl – [out] plastic work (Ansys output)
nDirect – number of direct components
nShear – number of shear components
sigma – stress (6)
Lt – tangent (6x6)
Wm – works (4)
statev_smart – law state variables
Etot_end – total strain at the end of the increment (6)
-
void umat_damage_LLD_0(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Ladevèze-Le Dantec (LLD) damage model of the unidirectional ply, with coupled transverse-shear plasticity in effective stress (LLDM0).
Matrix-dominated degradation of a unidirectional fibre-reinforced ply: two scalar damage variables, \( d_{22} \) (transverse) and \( d_{12} \) (shear), and a plasticity of the matrix written in the effective (undamaged) stress. No fibre failure. The equations below are in the fibre frame, fibres along 1;
props(0)puts the fibres along the global axis 1, 2 or 3, the law then runs in that frame and returns its stress, tangent and plastic strain in the global one.Damaged elasticity. Transversely isotropic compliance \( \mathbf{S}_0 \) (moduli \( E_L, E_T, \nu_{TL}, \nu_{TT}, G_{LT} \), \( G_{TT} = E_T/(2(1+\nu_{TT})) \)), damaged as
\[ \tilde{\mathbf{S}}(d_{22}, d_{12}):\quad S_{22}, S_{33}, S_{23}, S_{66} \leftarrow \frac{S^0}{1-d_{22}}, \qquad S_{44}, S_{55} \leftarrow \frac{S^0}{1-d_{12}}, \]the fibre terms \( S_{11}, S_{12}, S_{13} \) unchanged, and \( \boldsymbol{\sigma} = \tilde{\mathbf{L}} : (\boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,\Delta\theta - \boldsymbol{\varepsilon}^p) \), \( \tilde{\mathbf{L}} = \tilde{\mathbf{S}}^{-1} \). \( \nu_{TL} \) is the MINOR Poisson ratio ( \( \nu_{TL} = \nu_{LT} E_T/E_L \), about 0.02 for carbon/epoxy), the convention of L_isotrans().Plasticity in effective stress. With \( \tilde{\boldsymbol{\sigma}} = \mathbf{L}_0 : (\boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,\Delta\theta - \boldsymbol{\varepsilon}^p) \) and \( \boldsymbol{\Theta} = \mathrm{diag}(0, A_{ts}, A_{ts}, 1, 1, 0) \) (transverse and fibre-plane shear stresses only),
\[ f = \sigma^{\mathrm{Mises}}\!\left(\boldsymbol{\Theta}\tilde{\boldsymbol{\sigma}}\right) - R(p) - \sigma_{ts,0} \leq 0, \qquad R(p) = \beta_{ts}\, p^{m_{ts}}, \]with the associated flow \( \dot{\boldsymbol{\varepsilon}}^p = \dot p\, \partial f/\partial\tilde{\boldsymbol{\sigma}} = \dot p\, \boldsymbol{\Theta}\,\boldsymbol{\eta}(\boldsymbol{\Theta}\tilde{\boldsymbol{\sigma}}) \) ( \( \boldsymbol{\eta} \) = eta_stress()). The effective stress does not depend on the damage: the plasticity is solved first (convex cutting plane, Fischer-Burmeister), the damage then at fixed plastic strain.Damage. The driving forces of the criterion are unilateral in the transverse direction,
\[ Y_{22} = \frac{\langle\sigma_{22}\rangle_+^2 + \langle\sigma_{33}\rangle_+^2}{2E_T(1-d_{22})^2}, \quad Y_{12} = \frac{\sigma_{12}^2 + \sigma_{13}^2}{2G_{LT}(1-d_{12})^2}, \quad Y_{ts} = \sqrt{Y_{12} + b\,Y_{22}}, \quad Y_t = \sqrt{Y_{22}}, \]and both damage variables follow \( Y_{ts} \) (Kuhn-Tucker, \( \dot d \geq 0 \)):\[ d_{22} + \lambda(d_{22}) = \frac{\langle Y_{ts} - Y_{22,0}\rangle_+}{Y_{22,c}}, \qquad d_{12} + \lambda(d_{12}) = \frac{\langle Y_{ts} - Y_{12,0}\rangle_+}{Y_{12,c}}, \]\( \lambda \) the penalty of lagrange_pow_1() keeping \( d < 1 \). The two are coupled through \( Y_{ts} \) and through the stress they both relax (the damage directions \( \boldsymbol{\Lambda}_j = \partial\tilde{\mathbf{S}}/\partial d_j : \boldsymbol{\sigma} \)): the 2x2 system is full and non-symmetric. Transverse failure: when \( Y_t > Y_{22,u} \), \( d_{22} \) jumps to 0.99 and stays there; \( d_{12} \) keeps its own law.Tangent. The tangent of the two-stage update: \( \mathrm{d}\boldsymbol{\varepsilon}^e/\mathrm{d}\boldsymbol{\varepsilon} \) from the plasticity, the flow direction held fixed over the increment (continuum: its error is first order in the increment), then the exact linearization of the active damage conditions, \( \mathbf{L}_t = \tilde{\mathbf{L}}\,\frac{\mathrm{d}\boldsymbol{\varepsilon}^e}{\mathrm{d}\boldsymbol{\varepsilon}} - \sum_j \tilde{\mathbf{L}}\boldsymbol{\Lambda}_j \otimes \frac{\mathrm{d}d_j}{\mathrm{d}\boldsymbol{\varepsilon}} \).
tangent_modeis not used.Lreturns the damaged stiffness \( \tilde{\mathbf{L}} \).Work split. \( W_m^{ir} \) stores the hardening energy ( \( \tfrac12 (R_n + R_{n+1})\Delta p \)); \( W_m^{d} \) the plastic dissipation \( \bar{\boldsymbol{\sigma}}:\Delta\boldsymbol{\varepsilon}^p - \bar R\,\Delta p \) and the damage dissipation \( \bar{Y}^{th}_j \Delta d_j \) with the thermodynamic forces \( Y^{th}_j = \tfrac12\,\boldsymbol{\sigma}:\boldsymbol{\Lambda}_j \); \( W_m^{r} \) the rest (overbars: increment averages). \( W_m = W_m^r + W_m^{ir} + W_m^d \) at every increment.
Material Parameters (props, 18):
Index
Symbol
Description
props[0]
axis
Fibre axis (1, 2 or 3)
props[1]
\( E_L \)
Longitudinal Young’s modulus
props[2]
\( E_T \)
Transverse Young’s modulus
props[3]
\( \nu_{TL} \)
Minor Poisson ratio \( \nu_{LT} E_T/E_L \)
props[4]
\( \nu_{TT} \)
Transverse Poisson ratio
props[5]
\( G_{LT} \)
In-plane shear modulus
props[6]
\( \alpha_L \)
Longitudinal CTE
props[7]
\( \alpha_T \)
Transverse CTE
props[8]
\( Y_{12,0} \)
Shear damage threshold
props[9]
\( Y_{12,c} \)
Shear damage characteristic force
props[10]
\( Y_{22,0} \)
Transverse damage threshold
props[11]
\( Y_{22,c} \)
Transverse damage characteristic force
props[12]
\( Y_{22,u} \)
Transverse failure force (brittle)
props[13]
\( b \)
Transverse-shear coupling of \( Y_{ts} \)
props[14]
\( A_{ts} \)
Transverse weight of the plasticity criterion
props[15]
\( \sigma_{ts,0} \)
Initial yield stress
props[16]
\( m_{ts} \)
Hardening exponent
props[17]
\( \beta_{ts} \)
Hardening coefficient
State Variables (statev, 10):
Index
Symbol
Description
statev[0]
\( T_{init} \)
Reference temperature
statev[1]
\( d_{22} \)
Transverse damage
statev[2]
\( d_{12} \)
Shear damage
statev[3]
\( p \)
Accumulated plastic strain
statev[4-9]
\( \boldsymbol{\varepsilon}^p \)
Plastic strain (Voigt, engineering shears, global frame)
// Carbon/epoxy (T300/914-like), fibres along 1 vec props = {1, 138000., 11000., 0.0223, 0.40, 5500., -0.3e-6, 30e-6, 0.10, 0.30, 0.15, 0.40, 1.20, 2.5, 2.0, 50., 0.5, 300.}; vec statev = zeros(10);
References:
Ladevèze, P., & Le Dantec, E. (1992). “Damage modelling of the elementary ply for laminated composites.” Composites Science and Technology, 43(3), 257-267.
Allix, O., & Ladevèze, P. (1992). “Interlaminar interface modelling for the prediction of delamination.” Composite Structures, 22(4), 235-242.
Ladevèze, P. (1992). “A damage computational method for composite structures.” Computers & Structures, 44(1-2), 79-87.
Matzenmiller, A., Lubliner, J., & Taylor, R. L. (1995). “A constitutive model for anisotropic damage in fiber-composites.” Mechanics of Materials, 20(2), 125-152.
Pinho, S. T., et al. (2012). “Material and structural response of polymer-matrix fibre-reinforced composites.” Journal of Composite Materials, 46(19-20), 2313-2341.
- Parameters:
umat_name – Name of the constitutive model
Etot – Total strain at the beginning of the increment (6)
DEtot – Strain increment (6)
stress – Stress [in: start; out: end] (6)
Lt – Tangent modulus [output] (6x6)
L – Damaged elastic stiffness \( \tilde{\mathbf{L}} \) [output] (6x6)
DR – Rotation increment (3x3)
nprops – Number of material properties (18)
props – Material properties (table above)
nstatev – Number of state variables (10)
statev – State variables [input/output] (table above)
T – Temperature at the beginning of the increment
DT – Temperature increment
Time – Time at the beginning of the increment
DTime – Time increment
Wm – Total mechanical work [input/output]
Wm_r – Recoverable work [input/output]
Wm_ir – Stored (hardening) work [input/output]
Wm_d – Dissipated work (plasticity and damage) [input/output]
ndi – Number of direct stress components
nshr – Number of shear stress components
start – First increment flag
tnew_dt – Suggested time step ratio [output] (0.2 when a local loop does not converge)
tangent_mode – Not used: continuum tangent (see above)
-
void umat_external(const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, const int &solver_type, double &tnew_dt)
External mechanical UMAT subroutine wrapper.
Wrapper function for external user-defined material subroutines (UMATs) loaded as plugins at runtime. The actual constitutive model is implemented by the user through the plugin API (see umat_plugin_api.hpp).
Material parameters and state variables are user-defined and depend on the specific constitutive model implemented in the plugin.
See also
umat_plugin_ext_api for the native simcoon plugin base class
See also
umat_plugin_aba_api for Abaqus-compatible plugins
See also
umat_plugin_ans_api for ANSYS-compatible plugins
- Parameters:
Etot – Total strain tensor at beginning of increment (Voigt notation: 6x1 vector)
DEtot – Strain increment tensor (Voigt notation: 6x1 vector)
stress – Stress tensor (Voigt notation: 6x1 vector) [output]
Lt – Consistent tangent modulus (6x6 matrix) [output]
L – Elastic stiffness tensor (6x6 matrix) [output]
DR – Rotation increment matrix (3x3) for objective integration
nprops – Number of material properties
props – Material properties vector
nstatev – Number of state variables
statev – State variables vector [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work [output]
Wm_d – Dissipated work [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
solver_type – Solver type: 0=implicit (Newton), 1=explicit (RNL), 2=dynamic implicit
tnew_dt – Suggested new time step ratio for adaptive time stepping [output]
-
void umat_plasticity_chaboche(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Elastic-plastic constitutive model with Chaboche kinematic hardening (J2, two Armstrong-Frederick branches, Voce isotropic term).
This function implements the Chaboche unified viscoplasticity model for small and finite strain analysis. The model features:
J2 (von Mises) plasticity with associative flow rule
Multiple Armstrong-Frederick backstresses for nonlinear kinematic hardening
Optional isotropic hardening with Voce law
Dynamic recovery (recall terms) in backstress evolution
Convex Cutting Plane algorithm for return mapping
Thermal expansion effects
Consistent tangent modulus for implicit FE analysis
Constitutive Equations:
The yield function is defined as:
\[\Phi(\boldsymbol{\sigma}, \mathbf{X}, R) = \sigma_{eq}(\boldsymbol{\sigma} - \mathbf{X}) - R - \sigma_Y \leq 0 \]where:\( \sigma_{eq}(\boldsymbol{\eta}) = \sqrt{\frac{3}{2} \boldsymbol{\eta}_{dev} : \boldsymbol{\eta}_{dev}} \) is the von Mises equivalent stress
\( \boldsymbol{\eta} = \boldsymbol{\sigma} - \mathbf{X} \) is the shifted (effective) stress tensor
\( \mathbf{X} = \mathbf{X}_1 + \mathbf{X}_2 \) is the total backstress (two AF terms in this implementation)
\( R \) is the isotropic hardening stress
\( \sigma_Y \) is the initial yield stress
Armstrong-Frederick Backstress Evolution:
Each backstress component evolves according to the Armstrong-Frederick law with dynamic recovery:
\[\dot{\mathbf{X}}_i = \frac{2}{3} C_i \dot{\boldsymbol{\varepsilon}}^p - D_i \mathbf{X}_i \dot{p} \]where:\( C_i \) is the kinematic hardening modulus of the i-th backstress
\( D_i \) is the dynamic recovery (recall) parameter of the i-th backstress
\( \dot{\boldsymbol{\varepsilon}}^p \) is the plastic strain rate tensor
\( \dot{p} = \sqrt{\frac{2}{3} \dot{\boldsymbol{\varepsilon}}^p : \dot{\boldsymbol{\varepsilon}}^p} \) is the accumulated plastic strain rate
Physical Interpretation:
The \( C_i \) term represents strain hardening (backstress growth)
The \( D_i \mathbf{X}_i \dot{p} \) term represents dynamic recovery (backstress fading)
Multiple backstresses capture different scales of cyclic hardening behavior
Typically 2-3 backstress components are used
Isotropic Hardening (Optional):
The isotropic hardening follows the Voce law \( H_p = R(p) = Q \left( 1 - e^{-b p} \right) \) (the closed form of \( \dot{H}_p = b (Q - H_p) \dot{p} \), evaluated from the accumulated plastic strain \( p \) at every iterate; modular VoceHardening), where:
\( Q \) is the saturation value of the isotropic hardening stress
\( b \) is the hardening rate parameter
\( p \) is the accumulated plastic strain
Plastic Flow Rule:
The plastic strain rate follows the associative flow rule:
\[\dot{\boldsymbol{\varepsilon}}^p = \dot{p} \mathbf{n} \]where:\[\mathbf{n} = \frac{3}{2} \frac{\boldsymbol{\eta}_{dev}}{\sigma_{eq}(\boldsymbol{\eta})} \]is the flow direction (normal to the yield surface).Incremental Form (CCP Algorithm):
For an increment \( \Delta p \), the stress and backstresses are updated as:
\[\boldsymbol{\sigma}_{n+1} = \boldsymbol{\sigma}^{trial} - \Delta p \left( \mathbf{L} : \mathbf{n} + \frac{\partial \mathbf{n}}{\partial \boldsymbol{\sigma}} : \boldsymbol{\sigma} \right) \]\[\mathbf{X}_{i,n+1} = \mathbf{X}_{i,n} + \frac{2}{3} C_i \Delta \boldsymbol{\varepsilon}^p - D_i \mathbf{X}_{i,n} \Delta p \]The CCP algorithm solves for \( \Delta p \) using the Fischer-Burmeister complementarity condition:
\[FB(\Delta p, \Phi) = \sqrt{(\Delta p)^2 + \Phi^2} - \Delta p - \Phi = 0 \]Consistent Tangent Modulus:
The algorithmic tangent modulus accounts for both plastic flow and backstress evolution:
\[\mathbf{L}_t = \mathbf{L} - \frac{(\mathbf{L}:\mathbf{n}) \otimes (\mathbf{n}:\mathbf{L})}{\mathbf{n}:\mathbf{L}:\mathbf{n} + H_{tot}} \]where:\[H_{tot} = \sum_{i=1}^{2} \left( \tfrac{2}{3} C_i - D_i\, \mathbf{X}_i : \mathbf{n} \right) + b\,(Q - H_p) \]is the total hardening modulus combining the two kinematic contributions and the Voce isotropic term \( R'(p) = b (Q - H_p) \).Material Parameters (props):
Fixed layout — exactly ONE Voce isotropic term and TWO Armstrong–Frederick backstresses (nprops = 10). For a variable number of terms use the modular UMAT (MODUL) with ChabocheHardening / CombinedVoceHardening.
Index
Symbol
Description
Units
Typical Range
props[0]
\( E \)
Young’s modulus
Stress
50-500 GPa
props[1]
\( \nu \)
Poisson’s ratio
-
0.2-0.45
props[2]
\( \alpha \)
Coefficient of thermal expansion
1/Temperature
1e-6 to 1e-4 /K
props[3]
\( \sigma_Y \)
Initial yield stress
Stress
100-1000 MPa
props[4]
\( Q \)
Voce saturation stress
Stress
0-500 MPa
props[5]
\( b \)
Voce hardening rate
1/Strain
1-100
props[6]
\( C_1 \)
Kinematic modulus of backstress 1
Stress
10-500 GPa
props[7]
\( D_1 \)
Dynamic recovery of backstress 1
-
0-3000
props[8]
\( C_2 \)
Kinematic modulus of backstress 2
Stress
10-500 GPa
props[9]
\( D_2 \)
Dynamic recovery of backstress 2
-
0-3000
Notes on Parameter Selection:
First backstress typically has high \( C_1 \), low \( D_1 \) (long-range)
Second backstress typically has lower \( C_2 \), higher \( D_2 \) (short-range)
Set \( Q = b = 0 \) for pure kinematic hardening
State Variables (statev):
Total: \( n_{statev} = 33 \) ( \( T_{init} + p + \boldsymbol{\varepsilon}^p + \boldsymbol{a}_1 + \boldsymbol{a}_2 + \mathbf{X}_1 + \mathbf{X}_2 + H_p \)).
Index
Symbol
Description
Units
statev[0]
\( T_{init} \)
Initial/reference temperature
Temperature
statev[1]
\( p \)
Accumulated plastic strain
Strain
statev[2..7]
\( \boldsymbol{\varepsilon}^p \)
Plastic strain (Voigt, engineering shear)
Strain
statev[8..13]
\( \boldsymbol{a}_1 \)
Back-strain 1 (Voigt, engineering shear)
Strain
statev[14..19]
\( \boldsymbol{a}_2 \)
Back-strain 2 (Voigt, engineering shear)
Strain
statev[20..25]
\( \mathbf{X}_1 = \tfrac{2}{3} C_1 \boldsymbol{a}_1 \)
Backstress 1 (Voigt)
Stress
statev[26..31]
\( \mathbf{X}_2 = \tfrac{2}{3} C_2 \boldsymbol{a}_2 \)
Backstress 2 (Voigt)
Stress
statev[32]
\( H_p \)
Voce isotropic hardening stress \( R(p) \) (output)
Stress
// Example usage: 316 stainless steel (1 Voce term + 2 backstresses, fixed) vec props(10); props(0) = 200000; // E = 200 GPa props(1) = 0.3; // nu = 0.3 props(2) = 1.7e-5; // alpha = 17e-6 /K props(3) = 150; // sigma_Y = 150 MPa // Isotropic hardening (Voce, Hp = Q (1 - exp(-b p))) props(4) = 100; // Q = 100 MPa (saturation stress) props(5) = 10; // b = 10 (hardening rate) // First backstress (long-range) props(6) = 300000; // C1 = 300 GPa props(7) = 1000; // D1 = 1000 (moderate recovery) // Second backstress (short-range) props(8) = 50000; // C2 = 50 GPa props(9) = 100; // D2 = 100 (strong recovery) vec statev = zeros(33); // see the state-variable table statev(0) = 20.0; // Reference temperature 20°C vec Etot = {0.002, -0.0006, -0.0006, 0.0, 0.0, 0.0}; // 0.2% axial strain vec DEtot = {0.0001, -0.00003, -0.00003, 0.0, 0.0, 0.0}; vec stress = zeros(6); mat Lt = zeros(6,6); mat L = zeros(6,6); mat DR = eye(3,3); umat_plasticity_chaboche(Etot, DEtot, stress, Lt, L, DR, 12, props, 20, statev, 20.0, 0.0, 0.0, 1.0, Wm, Wm_r, Wm_ir, Wm_d, 3, 3, false, 0, tnew_dt); // Check backstress components vec X1 = statev.subvec(20, 25); // First backstress vec X2 = statev.subvec(26, 31); // Second backstressSee also
Ireal() for real identity tensor (Voigt \(6 \times 6\))
See also
Idev() for deviatoric projection tensor
See also
Fischer_Burmeister() for complementarity Solver Functions
See also
eta_stress() for shifted stress computation
See also
denom_FB_N_Mises() for CCP denominator
References:
Chaboche, J. L. (1986). “Time-independent constitutive theories for cyclic plasticity.” International Journal of Plasticity, 2(2), 149-188.
Chaboche, J. L. (1989). “Constitutive equations for cyclic plasticity and cyclic viscoplasticity.” International Journal of Plasticity, 5(3), 247-302.
Chaboche, J. L. (2008). “A review of some plasticity and viscoplasticity constitutive theories.” International Journal of Plasticity, 24(10), 1642-1693.
Armstrong, P. J., & Frederick, C. O. (1966). “A mathematical representation of the multiaxial Bauschinger effect.” CEGB Report RD/B/N731.
Lemaitre, J., & Chaboche, J. L. (1990). Mechanics of Solid Materials. Cambridge University Press.
Ortiz, M., & Simo, J. C. (1986). “An analysis of a new class of integration algorithms for elastoplastic constitutive relations.” International Journal for Numerical Methods in Engineering, 23(3), 353-366.
Note
Integrator. The isotropic term is \( H_p = R(p) = Q(1 - e^{-bp}) \) (modular VoceHardening, statev[32] is its output) in every mode. Under tangent_mode 0-2 the return mapping is the convex cutting plane loop below (flow at each iterate); under tangent_closest_point (3, full 3D states) the kernel runs the modular PlasticityMechanism (von Mises + VoceHardening + ChabocheHardening with 2 branches) on its own props and state through closest_point_return_mapping(): backward-Euler backstresses, flow at the converged stress, and cpp_consistent_tangent() — the exact (non-symmetric, dynamic recovery) operator the cutting-plane algorithmic tangent only approximates. Non-convergence requests tnew_dt = 0.5.
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
The Chaboche model excels at capturing ratcheting and cyclic plasticity
Note
Multiple backstresses are essential for accurate multiaxial loading predictions
Note
Parameter identification typically requires cyclic test data (tension-compression, torsion)
Note
For monotonic loading, simpler isotropic hardening may suffice
Note
The model assumes small strains (< 10%); use updated Lagrangian for larger strains
Note
Dynamic recovery (D > 0) prevents unbounded backstress growth under cycling
- Parameters:
umat_name – Name of the law (EPCHA), unused by the kernel
Etot – Total strain tensor at beginning of increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment tensor (Voigt notation: \(6 \times 1\) vector)
stress – Stress tensor (Voigt notation: \(6 \times 1\) vector) [output]
Lt – Consistent tangent modulus \( \mathbf{L}_t \) ( \(6 \times 6\) matrix) [output]
L – Elastic stiffness tensor ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (see table above)
nstatev – Number of state variables
statev – State variables vector (see table above) [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work stored in plastic deformation [output]
Wm_d – Dissipated (plastic) work [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
tangent_mode – tangent_* constant (parameter.hpp); the closest point is the kernel code tangent_closest_point (integrator=’closest_point’)
-
void umat_plasticity_iso(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default, const int &ncp = 0)
Elastic-plastic constitutive model with isotropic hardening (J2, power-law hardening).
This function implements an elastic-plastic material model for small and finite strain analysis. The model features:
J2 (von Mises) plasticity with associative flow rule
Isotropic hardening following a power law: \( H_p = k \cdot p^m \), evaluated through PowerLawHardening: exact for \( p \geq 10^{-6} \) and a \( C^1 \) quadratic blend below, because for \( m < 1 \) the exact slope \( m k p^{m-1} \) is infinite at the onset and the cutting-plane Newton cycles on the first plastic increment (committed off-surface, silently)
Convex Cutting Plane algorithm for return mapping
Thermal expansion effects
Consistent tangent modulus for implicit FE analysis
Constitutive Equations:
The yield function is defined as:
\[\Phi(\boldsymbol{\sigma}, p) = \sigma_{eq} - H_p(p) - \sigma_Y \leq 0 \]where:\( \sigma_{eq} = \sqrt{\frac{3}{2} \mathbf{s} : \mathbf{s}} \) is the von Mises equivalent stress
\( \mathbf{s} \) is the deviatoric stress tensor
\( H_p(p) = k \cdot p^m \) is the isotropic hardening function
\( p = \int \sqrt{\frac{2}{3} \dot{\boldsymbol{\varepsilon}}^p : \dot{\boldsymbol{\varepsilon}}^p} \, dt \) is the accumulated plastic strain
\( \sigma_Y \) is the initial yield stress
The plastic flow rule (associative plasticity):
\[\dot{\boldsymbol{\varepsilon}}^p = \dot{\lambda} \frac{\partial \Phi}{\partial \boldsymbol{\sigma}} = \dot{\lambda} \frac{3}{2} \frac{\mathbf{s}}{\sigma_{eq}} \]Evolution of accumulated plastic strain:
\[\dot{p} = \sqrt{\frac{2}{3} \dot{\boldsymbol{\varepsilon}}^p : \dot{\boldsymbol{\varepsilon}}^p} = \dot{\lambda} \]The Gibbs free energy of the single (lead) mechanism, with internal variables \( p \) and \( \boldsymbol{\varepsilon}^p \), reads
\[G = -\frac{1}{2}\,\boldsymbol{\sigma} : \mathbf{S} : \boldsymbol{\sigma} - \boldsymbol{\sigma} : \boldsymbol{\varepsilon}^p - \boldsymbol{\sigma} : \boldsymbol{\alpha}\,(\theta - \theta_0) + c_0\left[(\theta - \theta_0) - \theta \ln\frac{\theta}{\theta_0}\right] - \eta_0\,\theta + E_0 + F(\theta, p) \]Convex Cutting Plane Algorithm:
The CCP algorithm solves the return mapping problem by reformulating it as a complementarity problem:
Find \( \Delta p \geq 0 \) such that \( \Phi(\boldsymbol{\sigma}, p) \leq 0 \) and \( \Delta p \cdot \Phi = 0 \)
This is solved using the Fischer-Burmeister function for robust convergence
The method provides a consistent tangent modulus for implicit finite element analysis
Material Parameters (props):
The material properties vector must contain 6 constants:
Index
Symbol
Description
Units
props[0]
\( E \)
Young’s modulus
Stress
props[1]
\( \nu \)
Poisson’s ratio
-
props[2]
\( \alpha \)
Isotropic thermal expansion coefficient
1/Temperature
props[3]
\( \sigma_Y \)
Initial yield stress
Stress
props[4]
\( k \)
Hardening parameter
Stress
props[5]
\( m \)
Hardening exponent
-
State Variables (statev):
The state variables vector contains 8 internal variables:
Index
Symbol
Description
Units
statev[0]
\( T_{init} \)
Initial temperature
Temperature
statev[1]
\( p \)
Accumulated plastic strain
-
statev[2]
\( \varepsilon^p_{11} \)
Plastic strain component 11
-
statev[3]
\( \varepsilon^p_{22} \)
Plastic strain component 22
-
statev[4]
\( \varepsilon^p_{33} \)
Plastic strain component 33
-
statev[5]
\( \varepsilon^p_{12} \)
Plastic strain component 12 ( \(\times 2\) in Voigt)
-
statev[6]
\( \varepsilon^p_{13} \)
Plastic strain component 13 ( \(\times 2\) in Voigt)
-
statev[7]
\( \varepsilon^p_{23} \)
Plastic strain component 23 ( \(\times 2\) in Voigt)
-
// Example usage: vec Etot = {0.001, 0.0, 0.0, 0.0, 0.0, 0.0}; vec DEtot = {0.0001, 0.0, 0.0, 0.0, 0.0, 0.0}; vec stress = zeros(6); mat Lt = zeros(6,6); mat L = zeros(6,6); mat DR = eye(3,3); vec props = {70000, 0.3, 1e-5, 200, 500, 0.2}; vec statev = zeros(8); umat_plasticity_iso("EPICP", Etot, DEtot, stress, Lt, L, DR, 6, props, 8, statev, 20.0, 0.0, 0.0, 1.0, Wm, Wm_r, Wm_ir, Wm_d, 3, 3, true, tnew_dt);
See also
Fischer_Burmeister_m() for the complementarity Solver Functions
See also
L_iso() for isotropic elastic stiffness construction
See also
eta_stress() for plastic flow direction computation
Note
Integrator. Under tangent_mode 0-2 the return mapping is the convex cutting plane loop below; under tangent_closest_point (3, full 3D states) the kernel runs the modular PlasticityMechanism (von Mises + PowerLawHardening) on its own props and state through closest_point_return_mapping() and returns cpp_consistent_tangent(). For this radial law the two integrators converge to the same state; the closest-point branch carries the C1 onset regularisation of the power law (PowerLawHardening) and never commits an unconverged state (non-convergence requests tnew_dt = 0.5).
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
Voigt notation convention: [11, 22, 33, 12, 13, 23] with engineering shear strains ( \(\gamma = 2\varepsilon\))
Note
The consistent tangent modulus Lt ensures quadratic convergence in implicit Newton-Raphson schemes
Note
The tangent modulus Lt is always computed
- Parameters:
umat_name – Name of the constitutive model (EPICP)
Etot – Total strain tensor at beginning of increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment tensor (Voigt notation: \(6 \times 1\) vector)
stress – Stress tensor (Voigt notation: \(6 \times 1\) vector) [output]
Lt – Consistent tangent modulus \( \mathbf{L}_t = \frac{\partial \boldsymbol{\sigma}}{\partial \boldsymbol{\varepsilon}} \) ( \(6 \times 6\) matrix) [output]
L – Elastic stiffness tensor ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (see table above)
nstatev – Number of state variables
statev – State variables vector (see table above) [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work stored in hardening [output]
Wm_d – Dissipated (plastic) work [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
tangent_mode – tangent_* constant (parameter.hpp); under tangent_mode 2 the consistent tangent of the radial return is taken in closed form (Simo and Taylor 1985; de Souza Neto et al. 2008, box 7.4), exact at the converged return:
\[ \mathbf{L}_t = 3K\,\mathbf{I}_{vol} + 2G\,\theta\,\mathbf{I}_{dev} - 2G\,\bar{\theta}\,\mathbf{N}\otimes\mathbf{N},\quad \mathbf{N} = \frac{\mathbf{s}}{\|\mathbf{s}\|},\quad \theta = 1 - \frac{3G\,\Delta p}{q^{tr}},\quad \bar{\theta} = \frac{1}{1 + H/(3G)} - (1 - \theta) \]with \( q^{tr} = q + 3G\,\Delta p \) the trial von Mises stress and \( H = \mathrm{d}H_p/\mathrm{d}p \) at the converged \( p \)ncp – complementarity function of the cutting plane (NCPMethod code, state_variables::ncp): 0 Fischer-Burmeister (default), 1 min-NCP with a Fischer-Burmeister fallback
-
void umat_plasticity_johnson_cook_CCP(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &sigma, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Johnson-Cook elastic-viscoplastic constitutive law (EPJCK), mechanical version.
J2 (von Mises) plasticity with associated flow and the Johnson-Cook yield stress (Johnson & Cook, 1983), which multiplies a power-law strain hardening by a logarithmic strain-rate factor and a thermal-softening factor:
\[ \sigma_Y\left(p,\dot p,\theta\right) = \left(A + B\,p^{n}\right) \left(1 + C\,\ln\frac{\dot p}{\dot\varepsilon_0}\right) \left(1 - \theta^{*m}\right), \qquad \theta^{*} = \frac{\theta - \theta_{\mathrm{ref}}}{\theta_{\mathrm{melt}} - \theta_{\mathrm{ref}}} . \]The yield function, flow rule and loading/unloading conditions are\[ \Phi = \bar{\sigma} - \sigma_Y\left(p,\dot p,\theta\right) \leq 0, \qquad \dot{\boldsymbol{\varepsilon}}^{p} = \dot p\,\boldsymbol{\Lambda}, \quad \boldsymbol{\Lambda} = \frac{3}{2}\frac{\boldsymbol{\sigma}'}{\bar{\sigma}}, \qquad \dot p \geq 0, \quad \dot p\,\Phi = 0 , \]with the stress given by \( \boldsymbol{\sigma} = \mathbf{L} : \left(\boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,(\theta - \theta_0) - \boldsymbol{\varepsilon}^{p}\right) \).Regularization of the Johnson-Cook law. The logarithmic rate factor is clamped at its reference value, \( \ln(\dot p/\dot\varepsilon_0) \to \max\left(\ln(\dot p/\dot\varepsilon_0), 0\right) \): below \( \dot\varepsilon_0 \) (and in particular at the onset of yielding, \( \dot p = 0 \)) the material responds with its quasi-static, reference-rate yield stress (a \( C^0 \) kink of \( \Phi \) at \( \dot p = \dot\varepsilon_0 \), the definition of the law). The homologous temperature is clamped to \( [0, 1) \) so that the law is defined below \( \theta_{\mathrm{ref}} \) and never reaches the singular melting point; for \( m < 2 \) the softening \( T^{*m} \) is continued below \( T^* = 10^{-3} \) by a \( C^2 \) cubic (johnson_cook_softening), so that its temperature derivatives, read by the entropy and the heat of the thermomechanical law, stay bounded at \( \theta_{\mathrm{ref}} \). The power-law hardening \( B p^{n} \) with \( n < 1 \) has an infinite slope at the onset, which makes the cutting-plane Newton overshoot and cycle on the first plastic increment: it is evaluated through PowerLawHardening, i.e. exact for \( p \geq 10^{-6} \) and a \( C^1 \) quadratic blend below.
Discrete update. The plastic strain rate is treated fully implicitly over the increment, \( \dot p = \Delta p / \Delta t \). The rate factor therefore depends on the unknown \( \Delta p \) and its derivative enters the scalar Jacobian of the CCP iteration:
\[ K = \frac{\partial \Phi}{\partial p} + \frac{\partial \Phi}{\partial \Delta p} = -\,n B p^{n-1}\, f_{\dot\varepsilon}\, f_\theta - \left(A + B p^{n}\right) \frac{C}{\dot p\,\Delta t}\, f_\theta , \]so the iterates converge on the rate-dependent yield surface. With \( \Delta t = 0 \) the law degenerates to its rate-independent form. \( \Phi(\Delta p) \) is not convex across the kink \( \Delta p = \dot\varepsilon_0 \Delta t \) of the clamped rate factor, and a Newton started at \( \Delta p = 0 \) cycles between the two branches once \( \Delta t \lesssim C (A + B p^n) / (3 G \dot\varepsilon_0) \) (about \( 5\cdot10^{-5} \) s for AISI 4340). The kernel therefore decides the branch first, from \( \Phi \) at the kink: when positive, the loop starts at the kink with the right derivative of the rate factor and stays on the convex logarithmic branch, where Newton is monotone; otherwise it runs on the quasi-static branch from \( \Delta p = 0 \). Neither the unknown nor the law is altered.Tangent operator. Assembled by compute_tangent_operator() from the converged \( \hat{B} \), \( \boldsymbol{\kappa} = \mathbf{L}:\boldsymbol{\Lambda} \) and \( \partial\Phi/\partial\boldsymbol{\sigma} \), in the three modes of parameter.hpp:
tangent_none(0): \( \mathbf{L}_t = \mathbf{L} \), for explicit integration schemes;tangent_continuum(1): \( \mathbf{L}_t = \mathbf{L} - \hat{B}^{-1}\, \boldsymbol{\kappa}\otimes\left(\mathbf{L}:\partial\Phi/\partial\boldsymbol{\sigma}\right) \);tangent_algorithmic(2, default): the Simo-Hughes consistent operator; the flow Hessian is \( \partial\boldsymbol{\Lambda}/\partial\boldsymbol{\sigma} \) (deta_stress) and the rate term is already part of \( \hat{B} \), so the operator is the exact Jacobian of the backward-Euler (closest-point) map at fixed \( \Delta t \); the cutting-plane state coincides with it for radial increments (J2, isotropic). It is a fixed- \( \Delta t \) derivative: at a given strain rate it tends to \( \mathbf{L} \) as \( \Delta t \to 0 \).
Energy split. The stored energy of the hardening is the reference-rate work of the thermally softened hardening stress, \( G^{ir}(\theta, p) = f_\theta(\theta)\, B p^{n+1}/(n+1) \), so the hardening force is \( A_p = -\partial G^{ir}/\partial p = -f_\theta B p^{n} \) and the rate factor is a viscous overstress acting on the dissipation:
\[ \gamma = \left(\bar{\sigma} + A_p\right)\dot p = f_\theta \left[A f_{\dot\varepsilon} + B p^{n}\left(f_{\dot\varepsilon} - 1\right)\right]\dot p \geq 0 \]at every temperature and rate (with \( A_p = -B p^n \), EPICP’s isothermal form, the dissipation turns negative once \( f_\theta < B p^n / (A + B p^n) \)). The increments are \( \Delta W_m^{ir} = -\tfrac12 (A_p^n + A_p^{n+1})\,\Delta p \) and \( \Delta W_m^{d} = \tfrac12 (\boldsymbol{\sigma}^n + \boldsymbol{\sigma}^{n+1}):\Delta\boldsymbol{\varepsilon}^{p} + \tfrac12 (A_p^n + A_p^{n+1})\,\Delta p \), \( A_p \) being evaluated at the start and end temperatures.Material properties (props, 11):
Index
Symbol
Description
0
\( E \)
Young’s modulus
1
\( \nu \)
Poisson’s ratio
2
\( \alpha \)
Coefficient of thermal expansion (isotropic)
3
\( A \)
Initial yield stress
4
\( B \)
Hardening coefficient
5
\( n \)
Hardening exponent
6
\( C \)
Strain-rate sensitivity
7
\( \dot\varepsilon_0 \)
Reference strain rate (1/s)
8
\( m \)
Thermal-softening exponent
9
\( \theta_{\mathrm{ref}} \)
Reference temperature (K)
10
\( \theta_{\mathrm{melt}} \)
Melting temperature (K)
Admissible ranges, not checked by the kernel: \( \dot\varepsilon_0 > 0 \), \( \theta_{\mathrm{melt}} > \theta_{\mathrm{ref}} \), \( C \geq 0 \), \( n > 0 \), \( m > 0 \) (a zero denominator or a zero reference rate propagates NaN silently). A cutting-plane loop that reaches
maxiter_umatoff the surface setstnew_dtto 0.5 (step cut).State variables (statev, 9):
Index
Symbol
Description
0
\( \theta_0 \)
Initial temperature
1
\( p \)
Accumulated plastic strain
2-7
\( \boldsymbol{\varepsilon}^{p} \)
Plastic strain (Voigt 11 22 33 12 13 23)
8
\( \dot p \)
Plastic strain rate over the last increment (output)
The same statev layout as EPICP (plastic strain at offset 2) is declared in the finite-strain convention table of umat_smart.cpp, so EPJCK is served by the log-strain / Kirchhoff box route under every objective rate.
- Parameters:
umat_name – Name of the constitutive law (EPJCK)
Etot – Total strain at \( t_n \) (6x1 Voigt)
DEtot – Strain increment (6x1 Voigt)
sigma – Stress [input/output] (6x1 Voigt)
Lt – Tangent modulus [output] (6x6), see
tangent_modeL – Elastic stiffness tensor [output] (6x6)
DR – Rotation increment (3x3)
nprops – Number of material properties (11)
props – Material properties vector
nstatev – Number of state variables (9)
statev – State variables vector [input/output]
T – Temperature at \( t_n \)
DT – Temperature increment
Time – Time at \( t_n \)
DTime – Time increment (drives the plastic strain rate \( \dot p = \Delta p/\Delta t \))
Wm – Total mechanical work [input/output]
Wm_r – Recoverable mechanical work [input/output]
Wm_ir – Irrecoverable (stored) mechanical work [input/output]
Wm_d – Dissipated mechanical work [input/output]
ndi – Number of direct stress components
nshr – Number of shear stress components
start – Flag for the first increment
tnew_dt – Suggested time step ratio [output]
tangent_mode – Tangent assembly mode: tangent_none (0, elastic L for explicit integration), tangent_continuum (1) or tangent_algorithmic (2, default)
-
void umat_sma_mono(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Micromechanical monocrystal model for SMA based on Patoor et al. (1996).
This function implements the micromechanical monocrystal model of Patoor et al. (1996) for shape memory alloys. The model describes the martensitic phase transformation in a single crystal by tracking N individual martensite variants, where N is typically 12 or 24 depending on the crystallographic system.
Elastic Symmetry Selection:
The elastic behavior is determined by the umat_name parameter:
umat_name
Symmetry
Elastic Parameters
SMAMO
Isotropic
E, nu
SMAMC
Cubic
C11, C12, C44
Key Features:
Explicit tracking of N martensite variant volume fractions \( f_n \) (n = 1, …, N)
Crystallographic transformation strains for each variant
Variant selection driven by resolved thermodynamic driving force
Inter-variant interactions through hardening matrix
Applicable to single crystal SMA behavior
Supports multiple elastic symmetry types
Physical Background:
In single crystal SMAs, the austenite-to-martensite transformation occurs through the formation of distinct crystallographic variants. For cubic-to-monoclinic transformations (e.g., NiTi), there are typically 12 or 24 habit plane variants, each characterized by:
A specific transformation strain tensor \( \boldsymbol{\varepsilon}^{tr}_n \)
A habit plane normal and transformation direction
Variant Volume Fractions:
The microstructural state is characterized by N variant volume fractions:
\[f_n \geq 0, \quad \sum_{n=1}^{N} f_n \leq 1, \quad f_A = 1 - \sum_{n=1}^{N} f_n \]where:\( f_n \) is the volume fraction of martensite variant n
\( f_A \) is the austenite volume fraction
The total martensite fraction is \( \xi = \sum_{n=1}^{N} f_n \)
Transformation Strain:
The macroscopic transformation strain is the volume-weighted sum over all variants:
\[\boldsymbol{\varepsilon}^{tr} = \sum_{n=1}^{N} f_n \boldsymbol{\varepsilon}^{tr}_n \]where \( \boldsymbol{\varepsilon}^{tr}_n \) is the crystallographic transformation strain tensor of variant n, computed from the lattice correspondence.Thermodynamic Driving Force:
For each variant n, the driving force for transformation is:
\[F_n = \boldsymbol{\sigma} : \boldsymbol{\varepsilon}^{tr}_n - \Delta G^{chem}(T) - \sum_{m=1}^{N} H_{nm} f_m \]where:\( \boldsymbol{\sigma} : \boldsymbol{\varepsilon}^{tr}_n \) is the mechanical driving force
\( \Delta G^{chem}(T) \) is the chemical free energy difference (temperature-dependent)
\( H_{nm} \) is the interaction matrix describing variant-variant hardening
Transformation Criteria:
**Forward Transformation ( \(A \to M_n\)):**
\[\Phi_n^{fwd} = F_n - F_c^{fwd} \leq 0, \quad \dot{f}_n \geq 0 \]**Reverse Transformation ( \(M_n \to A\)):**
\[\Phi_n^{rev} = -F_n - F_c^{rev} \leq 0, \quad \dot{f}_n \leq 0 \]where \( F_c^{fwd} \) and \( F_c^{rev} \) are critical driving forces for forward and reverse transformations.
Interaction Matrix:
The hardening matrix \( H_{nm} \) captures:
Self-hardening ( \( H_{nn} \)): resistance to growth of variant n
Latent hardening ( \( H_{nm}, n \neq m \)): interaction between different variants
Variant Selection:
Under applied stress, variants with favorable orientation (high resolved stress on transformation system) are preferentially activated. This leads to:
Single variant formation under uniaxial loading along specific orientations
Multi-variant microstructures under complex loading
Texture-dependent macroscopic response
Number of Variants:
Common crystallographic systems:
Cubic \(\to\) Orthorhombic: N = 6 variants
Cubic \(\to\) Monoclinic (NiTi): N = 12 or 24 variants
Cubic \(\to\) Tetragonal: N = 3 variants
Material Parameters (props):
The props vector layout depends on the elastic symmetry (umat_name):
SMAMO (Isotropic): 16 parameters
Index
Symbol
Description
props[0]
E
Young’s modulus
props[1]
nu
Poisson’s ratio
props[2]
alpha_iso
Coefficient of thermal expansion
props[3]
b
Slope parameter
props[4]
g
Shear strain magnitude
props[5]
Ms
Martensite start temperature
props[6]
Af
Austenite finish temperature
props[7]
nvariants
Number of martensite variants
props[8-15]
c_lambda0, p0_lambda0, …
Lagrange multiplier parameters
SMAMC (Cubic): 17 parameters
Index
Symbol
Description
props[0]
C11
Elastic constant C11
props[1]
C12
Elastic constant C12
props[2]
C44
Elastic constant C44
props[3]
alpha_iso
Coefficient of thermal expansion
props[4]
b
Slope parameter
props[5]
g
Shear strain magnitude
props[6]
Ms
Martensite start temperature
props[7]
Af
Austenite finish temperature
props[8]
nvariants
Number of martensite variants
props[9-16]
c_lambda0, p0_lambda0, …
Lagrange multiplier parameters
The 8 Lagrange parameters are \( (c, p_0, n, \alpha) \) of the per-variant penalty \( \lambda_0(f_n) \), then of the total-fraction penalty \( \lambda_1(\xi) \).
**Crystallography (props, after the parameters above, offset \( o \) = 16 for SMAMO, 17 for SMAMC):**
Index
Description
\( o + 6i \) .. \( o + 6i + 2 \)
habit plane normal \( \mathbf{n}_i \) of variant \( i \)
\( o + 6i + 3 \) .. \( o + 6i + 5 \)
transformation direction \( \mathbf{m}_i \) of variant \( i \)
\( o + 6N + iN + j \)
interaction matrix \( H_{ij} \), \( N \times N \), row by row
Nothing is read from a file; a shorter props vector throws
std::invalid_argument.State Variables (statev):
Total state variables required: \( n_{statev} = 1 + N + 7 \) (for N variants)
Index
Symbol
Description
Units
statev[0]
\( T_{init} \)
Initial/reference temperature
Temperature
statev[1]
\( f_1 \)
Volume fraction of martensite variant 1
-
statev[2]
\( f_2 \)
Volume fraction of martensite variant 2
-
…
…
…
…
statev[N]
\( f_N \)
Volume fraction of martensite variant N
-
statev[N+1:N+6]
\( \varepsilon^{tr} \)
Macroscopic transformation strain (Voigt)
Strain
statev[N+7]
\( \xi \)
Total martensite volume fraction
-
The macroscopic transformation strain is computed as: \( \boldsymbol{\varepsilon}^{tr} = \sum_{n=1}^{N} f_n \boldsymbol{\varepsilon}^{tr}_n \)
References:
Patoor, E., Eberhardt, A., & Berveiller, M. (1996). “Micromechanical modelling of
superelasticity in shape memory alloys.”
Journal de Physique IV, 6(C1), 277-292.Patoor, E., Lagoudas, D. C., Entchev, P. B., Brinson, L. C., & Gao, X. (2006). “Shape memory alloys, Part I: General properties and modeling of single crystals.” Mechanics of Materials, 38(5-6), 391-429.
Gall, K., & Sehitoglu, H. (1999). “The role of texture in tension-compression
asymmetry in polycrystalline NiTi.”
International Journal of Plasticity, 15(1), 69-92.
See also
L_iso() for isotropic stiffness tensor (SMAMO)
See also
L_cubic() for cubic stiffness tensor (SMAMC)
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
This model is specifically for single crystal SMA behavior
Note
For polycrystalline SMAs, use this model within a homogenization scheme
Note
The number of variants N depends on the crystallographic transformation system
Note
Variant transformation strains must be provided based on crystallographic data
- Parameters:
umat_name – Name of the constitutive model (SMAMO or SMAMC)
Etot – Total strain tensor at beginning of increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment tensor (Voigt notation: \(6 \times 1\) vector)
stress – Cauchy stress tensor (Voigt notation: \(6 \times 1\) vector) [output]
Lt – Consistent tangent modulus ( \(6 \times 6\) matrix) [output]
L – Elastic stiffness tensor ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (layout depends on umat_name)
nstatev – Number of state variables (includes N variant volume fractions)
statev – State variables vector containing variant fractions [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work stored in transformation [output]
Wm_d – Dissipated work (hysteresis) [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
-
void umat_sma_unified_T(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Unified phenomenological SMA model with phase transformation.
This function implements the unified phenomenological model for shape memory alloys based on Chatziathanasiou’s framework. The model describes the macroscopic thermomechanical behavior through a single scalar internal variable (martensitic volume fraction \( \xi \)) and a tensorial transformation strain \( \boldsymbol{\varepsilon}^{tr} \).
Elastic Symmetry and Criteria Selection:
The elastic behavior and transformation criteria are determined by the umat_name parameter:
umat_name
Elasticity
Criteria
Number of props
SMADI
Isotropic
Drucker
28
SMADC
Cubic
Drucker
30
SMAAI
Isotropic
Anisotropic Drucker (DFA)
35
SMAAC
Cubic
Anisotropic Drucker (DFA)
37
Effective Properties:
The effective compliance is obtained via a Reuss mixing rule:
\[\mathbf{M}_{eff} = \xi \mathbf{M}_M + (1 - \xi) \mathbf{M}_A \]and the effective CTE is similarly interpolated.Current Maximum Transformation Strain:
The maximum transformation strain magnitude \( H^{cur} \) evolves with stress:
\[H^{cur}(\bar{\sigma}) = H_{min} + (H_{max} - H_{min})\left(1 - e^{-k_1 \langle \bar{\sigma} - \sigma_{crit} \rangle}\right),\qquad \langle x \rangle = \max(x, 0) \]Material Parameters (props):
SMADI (Isotropic elasticity, Drucker criteria) — 28 props:
Index
Symbol
Description
Units
0
flagT
0: the given transformation temperatures are those of the measured curve, converted to the model’s with n1..n4; 1: used as given
-
1
\( E_A \)
Young’s modulus of Austenite
MPa
2
\( E_M \)
Young’s modulus of Martensite
MPa
3
\( \nu_A \)
Poisson’s ratio of Austenite
-
4
\( \nu_M \)
Poisson’s ratio of Martensite
-
5
\( \alpha_A \)
CTE of Austenite
1/K
6
\( \alpha_M \)
CTE of Martensite
1/K
7
\( H_{min} \)
Minimal transformation strain magnitude
-
8
\( H_{max} \)
Maximal transformation strain magnitude
-
9
\( k_1 \)
Exponential evolution parameter for \( H^{cur} \)
1/MPa
10
\( \sigma_{crit} \)
Von Mises stress below which \( H^{cur} = H_{min} \)
MPa
11
\( C_A \)
Clausius-Clapeyron slope (M \( \rightarrow \) A)
MPa/K
12
\( C_M \)
Clausius-Clapeyron slope (A \( \rightarrow \) M)
MPa/K
13
\( M_{s0} \)
Martensite start temperature at zero stress
K
14
\( M_{f0} \)
Martensite finish temperature at zero stress
K
15
\( A_{s0} \)
Austenite start temperature at zero stress
K
16
\( A_{f0} \)
Austenite finish temperature at zero stress
K
17
\( n_1 \)
Martensite start smooth exponent
-
18
\( n_2 \)
Martensite finish smooth exponent
-
19
\( n_3 \)
Austenite start smooth exponent
-
20
\( n_4 \)
Austenite finish smooth exponent
-
21
\( \sigma_{caliber} \)
Calibration stress for \( C_A \) / \( C_M \)
MPa
22
\( b \)
Tension-compression asymmetry parameter (Prager)
-
23
\( n \)
Tension-compression asymmetry exponent (Prager)
-
24
\( c_\lambda \)
Penalty function exponent start point
-
25
\( p_{0\lambda} \)
Penalty function limit value
-
26
\( n_\lambda \)
Penalty function power law exponent
-
27
\( \alpha_\lambda \)
Penalty function power law parameter
-
SMADC (Cubic elasticity, Drucker criteria) — 30 props:
Index
Symbol
Description
Units
0
flagT
0: the given transformation temperatures are those of the measured curve, converted to the model’s with n1..n4; 1: used as given
-
1
\( E_A \)
Young’s modulus of Austenite ([100] direction)
MPa
2
\( E_M \)
Young’s modulus of Martensite ([100] direction)
MPa
3
\( \nu_A \)
Poisson’s ratio of Austenite
-
4
\( \nu_M \)
Poisson’s ratio of Martensite
-
5
\( G_A \)
Shear modulus of Austenite
MPa
6
\( G_M \)
Shear modulus of Martensite
MPa
7–29
Same as SMADI props[5–27] (common SMA parameters)
SMAAI (Isotropic elasticity, anisotropic Drucker criteria) — 35 props:
Same as SMADI (props[0–27]) followed by 7 DFA parameters:
Index
Symbol
Description
28
\( F_{dfa} \)
F parameter of DFA criteria
29
\( G_{dfa} \)
G parameter of DFA criteria
30
\( H_{dfa} \)
H parameter of DFA criteria
31
\( L_{dfa} \)
L parameter of DFA criteria
32
\( M_{dfa} \)
M parameter of DFA criteria
33
\( N_{dfa} \)
N parameter of DFA criteria
34
\( K_{dfa} \)
K parameter of DFA criteria
SMAAC (Cubic elasticity, anisotropic Drucker criteria) — 37 props:
Same as SMADC (props[0–29]) followed by 7 DFA parameters (props[30–36]).
State Variables (statev) — 17 variables:
Index
Symbol
Description
Units
0
\( T_{init} \)
Initial/reference temperature
K
1
\( \xi \)
Martensitic volume fraction
-
2
\( \varepsilon^{tr}_{11} \)
Transformation strain component 11
-
3
\( \varepsilon^{tr}_{22} \)
Transformation strain component 22
-
4
\( \varepsilon^{tr}_{33} \)
Transformation strain component 33
-
5
\( \gamma^{tr}_{12} \)
Transformation strain component 12 (engineering)
-
6
\( \gamma^{tr}_{13} \)
Transformation strain component 13 (engineering)
-
7
\( \gamma^{tr}_{23} \)
Transformation strain component 23 (engineering)
-
8
\( \xi_F \)
Cumulated forward transformation, non-decreasing ( \( \xi = \xi_F - \xi_R \))
-
9
\( \xi_R \)
Cumulated reverse transformation, non-decreasing
-
10
\( \rho \Delta s_0 \)
Entropy difference between phases (M - A)
MPa/K
11
\( \rho \Delta E_0 \)
Internal energy difference between phases (M - A)
MPa
12
\( D \)
Stress dependence parameter for transformation limits
-
13
\( a_1 \)
Forward hardening parameter
MPa
14
\( a_2 \)
Reverse hardening parameter
MPa
15
\( a_3 \)
Equilibrium hardening parameter
MPa
16
\( Y_{0t} \)
Initial transformation critical value
MPa
References:
Chatziathanasiou, D. (2016). Ph.D. Thesis — Phenomenological constitutive modeling of shape memory alloys.
Chemisky, Y., Chatziathanasiou, D., Kumar, P., & Lagoudas, D. C. (2014). “A constitutive model for cyclic actuation of high-temperature shape memory alloys.” Mechanics of Materials, 68, 120-136.
See also
L_iso() for isotropic stiffness tensor (SMADI, SMAAI)
See also
L_cubic() for cubic stiffness tensor (SMADC, SMAAC)
See also
umat_sma_mono() for the micromechanical monocrystal SMA model
Note
Elastic convention: isotropic uses “Enu”, cubic uses “EnuG” for L_iso / L_cubic
Note
flagT = 0 converts the given Ms, Mf, As, Af (read on the measured curve) into the model’s temperatures through the smoothing exponents n1..n4; flagT = 1 uses them as given
Note
The pre-2.0 aliases SMAUT and SMANI were removed in 2.0: use SMADI and SMAAI.
Note
Convergence measure. The local Fischer-Burmeister solve reports \( \sum_j |FB_j| / Y^{crit}_j \), so each \( Y^{crit}_j \) must be a positive scale of its criterion. The signed thresholds \( Y^t_F = Y_0^t + D\,H^{cur}\,\bar{\sigma} \) and \( Y^t_R = Y_0^t + D\,\boldsymbol{\sigma}:\bar{\boldsymbol{\varepsilon}}^{T} \) are not: with a calibrated \( D < 0 \) they cross zero along a loading path (at \( \bar{\sigma} = Y_0^t / (-D\,H^{cur}) \), about 1.2 GPa for NiTi-like parameters), and a residual at the floating-point floor of \( \xi \) then reads as a non-convergence: the kernel requests step cuts no sub-increment can satisfy and the solver crawls at its minimal increment. The scales are therefore the magnitudes of the terms, \( Y^{crit}_F = |Y_0^t| + |D\,H^{cur}\,\bar{\sigma}| \) and \( Y^{crit}_R = |Y_0^t| + |D\,\boldsymbol{\sigma}:\bar{\boldsymbol{\varepsilon}}^{T}| \), identical to the thresholds wherever \( D \ge 0 \). Shared by the thermomechanical twin and by umat_sma_unified_TR.
Note
Reverse row of the local Jacobian. With \( \bar{\boldsymbol{\varepsilon}}^{T} = \mathrm{dev}(\boldsymbol{\varepsilon}^{T})/\xi \) (ETMean), the direct partials \( \partial \Phi_R / \partial \xi \) and \( \partial \Phi_R / \partial \boldsymbol{\varepsilon}^{T} : \boldsymbol{\Lambda}^F \) carry \( \pm(1+D)\,\boldsymbol{\sigma}:\bar{\boldsymbol{\varepsilon}}^{T}/\xi \) terms that cancel analytically but lose about 12 digits at \( \xi \approx 10^{-12} \). The row is therefore built through \( \bar{\boldsymbol{\varepsilon}}^{T} \) as intermediate variable:
\[K_{Rj} = \frac{\partial \Phi_R}{\partial \bar{\boldsymbol{\varepsilon}}^{T}} : \boldsymbol{\Lambda}_{\bar{\varepsilon}}^{j} + \left.\frac{\partial \Phi_R}{\partial \xi_j}\right|_{finite}, \qquad \frac{\partial \Phi_R}{\partial \bar{\boldsymbol{\varepsilon}}^{T}} = -(1+D)\,\boldsymbol{\sigma}, \]\[\boldsymbol{\Lambda}_{\bar{\varepsilon}}^{F} = \frac{\boldsymbol{\Lambda}^{F} - \bar{\boldsymbol{\varepsilon}}^{T}}{\xi}, \qquad \boldsymbol{\Lambda}_{\bar{\varepsilon}}^{R} = \mathbf{0}, \qquad \left.\frac{\partial \Phi_R}{\partial \xi_{F}}\right|_{finite} = H_f^{R\prime} - \lambda_0^{\prime}, \quad \left.\frac{\partial \Phi_R}{\partial \xi_{R}}\right|_{finite} = -H_f^{R\prime} + \lambda_0^{\prime}, \](reverse transformation removes martensite proportionally, so the mean is unchanged; \( \boldsymbol{\Lambda}_{\bar{\varepsilon}}^{F} = \mathbf{0} \) when the fallback \( \bar{\boldsymbol{\varepsilon}}^{T} = \boldsymbol{\Lambda}^{F} \) is active).Note
Closest-point mode (
tangent_mode = tangent_closest_point). The closest-point projection replaces the cutting-plane loop, with \( \mathbf{L}(\xi) \) and \( \boldsymbol{\alpha}(\xi) \) frozen at \( \xi_n \). Since the Reuss mixture \( \mathbf{M}(\xi) \) and \( \boldsymbol{\alpha}(\xi) \) are linear in \( \xi \), the effective flows\[\boldsymbol{\Lambda}^{F}_{eff} = \boldsymbol{\Lambda}^{F} + \Delta\mathbf{M}\,\boldsymbol{\sigma} + \Delta\boldsymbol{\alpha}\,(T+\Delta T-T_{init}), \qquad \boldsymbol{\Lambda}^{R}_{eff} = -\bar{\boldsymbol{\varepsilon}}^{T} - \Delta\mathbf{M}\,\boldsymbol{\sigma} - \Delta\boldsymbol{\alpha}\,(T+\Delta T-T_{init}) \]make the frozen- \( \mathbf{L} \) residual the exact discrete system. The state is rebuilt from the start values at every iterate, with \( \bar{\boldsymbol{\varepsilon}}^{T} \) in closed form (the fixed-point sweep diverges when \( \Delta\xi_R > \xi \)):\[\bar{\boldsymbol{\varepsilon}}^{T}\,(\xi + \Delta\xi_R) = \mathrm{dev}(\boldsymbol{\varepsilon}^{T}_n) + \Delta\xi_F\,\mathrm{dev}(\boldsymbol{\Lambda}^{F}), \]so that \( \partial\bar{\boldsymbol{\varepsilon}}^{T}/\partial\boldsymbol{\sigma} = \frac{\Delta\xi_F}{\xi_n+\Delta\xi_F}\,\mathrm{dev}(\partial\boldsymbol{\Lambda}^{F}/\partial\boldsymbol{\sigma}) \), \( \partial\bar{\boldsymbol{\varepsilon}}^{T}/\partial\Delta\xi_F = (\mathrm{dev}(\boldsymbol{\Lambda}^{F}) - \bar{\boldsymbol{\varepsilon}}^{T})/(\xi_n+\Delta\xi_F) \), with \( \boldsymbol{\Lambda}^{F} = H^{cur}\,\mathbf{g} \), \( \partial\boldsymbol{\Lambda}^{F}/\partial\boldsymbol{\sigma} = \mathbf{g}\otimes\partial H^{cur}/\partial\boldsymbol{\sigma} + H^{cur}\,\partial\mathbf{g}/\partial\boldsymbol{\sigma} \) ( \( \mathbf{g} \) the Drucker gradient). The callbacks return the analytic total derivatives of this composed map; the flux chain of the forward row is \( \mathbf{c}_F = -\Delta\xi_R\,\partial\bar{\boldsymbol{\varepsilon}}^{T}/\partial\Delta\xi_F \). The hardening functions are evaluated at \( \xi \) clamped to \( [0,1] \) (fractional powers are NaN outside), and the FB scales are floored at \( 0.1\max(Y_0^t + D\,H_{max}\,\sigma_{caliber},\,10^{-2}) \) since both thresholds vanish in virgin states. A non-converged projection requests a step cut (tnew_dt = 0.5), never a cutting-plane fallback. The output \( \mathbf{L} \) is the mixture at the converged \( \xi \); the tangent uses the frozen one.Note
tangent_algorithmicis clamped to the continuum tangent: its finite-difference flow Hessian makes the local system near-singular on the transformation plateau (rcond \( \sim 10^{-17} \)).- Parameters:
umat_name – Model variant (SMADI, SMADC, SMAAI, SMAAC)
Etot – Total strain tensor at beginning of increment (Voigt notation: 6x1)
DEtot – Strain increment tensor (Voigt notation: 6x1)
stress – Cauchy stress tensor (Voigt notation: 6x1) [output]
Lt – Consistent tangent modulus (6x6) [output]
L – Elastic stiffness tensor (6x6) [output]
DR – Rotation increment matrix (3x3) for objective integration
nprops – Number of material properties
props – Material properties vector (layout depends on umat_name)
nstatev – Number of state variables (17)
statev – State variables vector [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work stored in transformation [output]
Wm_d – Dissipated work (hysteresis) [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
tnew_dt – Suggested new time step ratio for adaptive time stepping [output]
-
void umat_sma_unified_TR(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Unified phenomenological SMA model with phase transformation and reorientation.
Extends umat_sma_unified_T with a third leading mechanism: martensite reorientation. The macroscopic state is the martensitic volume fraction \( \xi = \xi^F - \xi^R \), where the cumulated forward and reverse transformations \( \xi^F, \xi^R \) (non-decreasing: their increments are the non-negative multipliers of the two mechanisms) are kept apart so that both can be active in the same increment, the transformation strain \( \boldsymbol{\varepsilon}^{tr} \), the reorientation strain accumulator \( \mathbf{E}^{Reo} \) and its cumulative multiplier \( p^{TR} \), and a single back-strain \( \mathbf{v}^{re} \), which grows with the reorientation increments only.
Variants:
umat_name
Elasticity
Criteria
nprops
SMRDI
Isotropic
Drucker
35
SMRDC
Cubic
Drucker
37
SMRAI
Isotropic
Anisotropic Drucker (DFA)
42
SMRAC
Cubic
Anisotropic Drucker (DFA)
44
Effective back-stress and saturation-coupled reorientation surface (Form B):
\[\mathbf{X} = H^{Reo} \, (\mathbf{v}^{re} \odot \mathbf{I}_{r05}) \]\[\Phi^{Reo} = \mathrm{Prager}\!\bigl( \boldsymbol{\sigma} - (1+\lambda_{1}^{Reo}) \, \mathbf{X} \bigr) - Y^{Reo} \]where \( \lambda_{1}^{Reo} = \mathrm{lagrange}_{\mathrm{pow}_1}(\|\mathbf{v}^{re}\|/E_{T}^{Reo,max}, \ldots) \) is the saturation penalty on the intrinsic (per-unit-martensite) back-strain \( \mathbf{v}^{re} \).
Property layout for SMRDI (28 + 7 = 35 props):
Index
Symbol
Description
0..27
–
Same as SMADI (flagT, EA, EM, nuA, nuM, alphaA, alphaM, Hmin, Hmax, k1, sigmacrit, C_A, C_M, Ms0, Mf0, As0, Af0, n1..n4, sigmacaliber, prager_b, prager_n, c_lambda, p0_lambda, n_lambda, alpha_lambda)
28
\( Y^{Reo} \)
Stress limit for onset of reorientation
29
\( H^{Reo} \)
Reorientation kinematic hardening coefficient
30
\( E_{T}^{Reo,max} \)
Maximum reorientation back-strain magnitude
31
\( c_{\lambda Reo} \)
Reorientation penalty exponent start point
32
\( p_{0\lambda Reo} \)
Reorientation penalty limit value
33
\( n_{\lambda Reo} \)
Reorientation penalty power exponent
34
\( \alpha_{\lambda Reo} \)
Reorientation penalty power parameter
For SMRDC, SMRAI, SMRAC the same 7 reorientation parameters are appended after the SMADC / SMAAI / SMAAC property block.
State variables (statev) — 30 entries:
Per Chatziathanasiou §4.3, the internal variables of the model are \( \{\boldsymbol\sigma, T, \boldsymbol\varepsilon^F, \boldsymbol\varepsilon^R, \boldsymbol\varepsilon^{re}, \mathbf{v}^{re}, \xi^F, \xi^R\} \). There is only one back-strain in the entire model — \( \mathbf{v}^{re} \) — associated with the reorientation channel. Forward and reverse transformation use isotropic hardening only and do not carry back-strains.
Index
Description
0
\( T_{init} \) : initial temperature
1
\( \xi \) : martensitic volume fraction
2..7
\( \boldsymbol{\varepsilon}^{tr} \) : transformation strain
8
\( \xi^F \) : cumulated forward transformation, non-decreasing ( \( \xi = \xi^F - \xi^R \))
9
\( \xi^R \) : cumulated reverse transformation, non-decreasing, kept apart from \( \xi^F \) so that both can be active in the same increment
10..16
calibrated constants, as in umat_sma_unified_T: \( \rho\Delta s_0, \rho\Delta E_0, D, a_1, a_2, a_3, Y_0^t \)
17
\( p^{TR} \) : cumulative reorientation multiplier \( \sum \Delta s^{Reo} \)
18..23
\( \mathbf{v}^{re} \) : reorientation back-strain (Voigt, strain convention with engineering shears)
24..29
\( \mathbf{E}^{Reo} \) : macroscopic reorientation strain accumulator
References:
Chatziathanasiou, D. (2016). Ph.D. Thesis.
Chatziathanasiou, Chemisky, Meraghni, Echchorfi, Patoor (2015). Smart Materials and Structures.
See also
umat_sma_unified_T for the transformation-only base model.
See also
assemble_continuum_tangent for the shared 3-mechanism tangent operator.
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
SMRDI/SMRDC/SMRAI/SMRACroute through umat_sma_unified_TR.Note
Internal vectorial state variables are rotated as strain by
DR.Note
Active set. The local system couples the three mechanisms in one Fischer-Burmeister solve. The reorientation row has purely kinematic hardening, \( B_{22} \simeq -(1+\lambda_1^{Reo})\,H^{Reo}\,\boldsymbol{\eta}^{Reo}:\boldsymbol{\eta}^{Reo} \), and at the apex of the Drucker cone ( \( \boldsymbol{\sigma}_{eff} = 0 \): a thermal step at zero stress; or \( \xi = 0 \) with \( H^{Reo} = 0 \)) the direction \( \boldsymbol{\eta}^{Reo} \) is undefined and both the stress-flow and the back-strain terms of the row vanish, so \( B_{22} = 0 \) and the row \( -|B_{22}|\,\Delta s^{Reo} = 0 \) is singular. The transformation rows keep the isotropic term \( \partial \Phi / \partial \xi \) on their diagonal and never degenerate. A mechanism with \( \Phi_j < 0 \) and \( B_{jj} = 0 \) is therefore dropped from the iteration, \( \Delta s_j = 0 \), and the reduced system is solved: the row of an inactive mechanism with a finite diagonal decouples and gives \( \Delta s_j = 0 \) exactly, so the reduced solve returns the same increments as the full one wherever the full one is solvable.
Note
Convergence measure: same magnitude scales \( Y^{crit}_j \) as umat_sma_unified_T (see its note); \( Y^{crit}_{Reo} = Y^{Reo} \).
Note
When \( \Delta s^{Reo} = 0 \), the result is bit-identical to umat_sma_unified_T (same elastic mixing, same forward/reverse equations).
Note
Reorientation flows (thesis §4, eq. 503). Reorientation only re-orients the martensite present at the start of the increment, \( \xi_{start} \) (new martensite forms already aligned with \( \boldsymbol{\sigma} \)), so with \( \bar{\boldsymbol{\Lambda}}^{re} = \partial\,\mathrm{Prager}/\partial\boldsymbol{\sigma}\,(\boldsymbol{\sigma}_{eff}) \):
\[\boldsymbol{\Lambda}_{\varepsilon}^{re} = \xi_{start}\,\bar{\boldsymbol{\Lambda}}^{re}, \qquad \dot{\mathbf{v}}^{re} = \dot{p}^{re}\,\bar{\boldsymbol{\Lambda}}^{re}, \qquad \frac{\partial \Phi^{Reo}}{\partial \boldsymbol{\sigma}} = \bar{\boldsymbol{\Lambda}}^{re}. \]The criterion and the back-strain flow are per unit martensite (not \( \xi \)-scaled), which keeps \( B_{22} \) finite at \( \xi = 0 \) through the back-strain term of \( K_{22} \). The saturation argument is the intrinsic ratio \( \|\mathbf{v}^{re}\| / E_T^{Reo,max} \): dividing by \( \xi \) would blow the penalty up as \( \xi \to 0 \). Hence \( K_{2F} = K_{2R} = 0 \) and\[K_{22} = \frac{\partial \Phi^{Reo}}{\partial \mathbf{v}^{re}} : \bar{\boldsymbol{\Lambda}}^{re}, \qquad \frac{\partial \Phi^{Reo}}{\partial \mathbf{v}^{re}} = -(1+\lambda_1^{Reo})\,H^{Reo}\,(\boldsymbol{\eta}^{Reo}\odot\mathbf{I}_{r05}) - (\boldsymbol{\eta}^{Reo}:\mathbf{X})\,\frac{\partial \lambda_1^{Reo}}{\partial \mathbf{v}^{re}}. \]The reverse row uses the same ETMean chain rule as umat_sma_unified_T, with \( \boldsymbol{\Lambda}_{\bar{\varepsilon}}^{re} = \bar{\boldsymbol{\Lambda}}^{re} \) ( \( \xi \) unchanged by reorientation).Note
Closest-point mode (
tangent_closest_point): same frozen-mixture construction as umat_sma_unified_T, with \( \boldsymbol{\Lambda}^{re} = \xi_{start}\,\mathbf{r} \), \( \mathbf{r} = \bar{\boldsymbol{\Lambda}}^{re}(\boldsymbol{\sigma}_{eff}) \). The back-strain is solved by Newton on its backward-Euler equation \( \mathbf{R}(\mathbf{v}) = \mathbf{v} - \mathbf{v}_n - \Delta s^{re}\,\mathbf{r}(\boldsymbol{\sigma}_{eff}(\mathbf{v})) = \mathbf{0} \), Jacobian \( \mathbf{J} = \mathbf{I} - \Delta s^{re}\,\mathbf{G}\,\mathbf{A} \) with \( \mathbf{G} = \partial\mathbf{r}/\partial\boldsymbol{\sigma}_{eff} \) and \( \mathbf{A} = \partial\boldsymbol{\sigma}_{eff}/\partial\mathbf{v} \) (a fixed-point sweep only contracts while \( \Delta s^{re} H^{Reo}(1+\lambda_1^{Reo})/\bar{\sigma}_{eff} < 1 \)); no root within the budget rejects the trial. Then\[\frac{\partial\mathbf{v}}{\partial\boldsymbol{\sigma}} = \mathbf{J}^{-1}\Delta s^{re}\,\mathbf{G}, \quad \frac{\partial\mathbf{v}}{\partial\Delta s^{re}} = \mathbf{J}^{-1}\mathbf{r}, \quad \frac{\partial\boldsymbol{\sigma}_{eff}}{\partial\boldsymbol{\sigma}} = \mathbf{I} + \mathbf{A}\,\frac{\partial\mathbf{v}}{\partial\boldsymbol{\sigma}}, \quad \frac{\partial\boldsymbol{\sigma}_{eff}}{\partial\Delta s^{re}} = \mathbf{A}\,\frac{\partial\mathbf{v}}{\partial\Delta s^{re}}, \]and \( \bar{\boldsymbol{\varepsilon}}^{T}(\xi_n + \Delta\xi_F) = \mathrm{dev}(\boldsymbol{\varepsilon}^{T}_n) + \Delta\xi_F\,\mathrm{dev}(\boldsymbol{\Lambda}^F) + \Delta s^{re}\,\mathrm{dev}(\boldsymbol{\Lambda}^{re}) \).Note
Energy. \( W_m^{ir} = 0 \): the back-strain is a kinematic history variable that shifts the reorientation criterion and stores no free energy (no \( \mathbf{X}:\Delta\mathbf{v} \) term); the reorientation strain increment enters \( W_m^{r} \) and \( W_m^{d} \) like the transformation strain.
Note
tangent_algorithmicis clamped to the continuum tangent (see umat_sma_unified_T).
-
void umat_prony_Nfast(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Generalized Maxwell (Prony series) linear viscoelastic model with N branches (
PRONK).Isotropic, rate-dependent, linear viscoelastic model with thermal expansion: an equilibrium spring in parallel with \( N \) Maxwell branches, each a spring \( \mathbf{L}_i \) in series with a dashpot \( \mathbf{H}_i \).
Rheological representation:
L_inf = L_0 - sum_i L_i (equilibrium spring) ─────────────────────/\/\/\───────────────────── │ │ ├──── L_1 /\/\/\──[ H_1 ]──────────┤ branch 1 │ │ │ ... │ │ │ └──── L_N /\/\/\──[ H_N ]──────────┘ branch NConstitutive equations (Voigt notation, engineering shear strains):
The instantaneous stiffness acts on the elastic part of the strain,
\[ \boldsymbol{\sigma} = \mathbf{L}_0 : \left( \boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,(T - T_{init}) - \tilde{\boldsymbol{\varepsilon}}^{v} \right), \qquad \tilde{\boldsymbol{\varepsilon}}^{v} = \sum_{i=1}^N \mathbf{M}_0 : \mathbf{L}_i : \boldsymbol{\varepsilon}^{v}_i , \]with \( \mathbf{L}_0 = \mathbf{L}_{iso}(E_0, \nu_0) \), \( \mathbf{M}_0 = \mathbf{L}_0^{-1} \) and \( \mathbf{L}_i = \mathbf{L}_{iso}(E_i, \nu_i) \); this is the parallel assembly \( \boldsymbol{\sigma} = \mathbf{L}_0 : (\boldsymbol{\varepsilon} - \boldsymbol{\varepsilon}^{th}) - \sum_i \mathbf{L}_i : \boldsymbol{\varepsilon}^{v}_i \). The dashpot of branch \( i \) carries the branch stress \( \mathbf{A}_i = \mathbf{L}_i : (\boldsymbol{\varepsilon} - \boldsymbol{\varepsilon}^{v}_i) \) and flows as\[ \dot{\boldsymbol{\varepsilon}}^{v}_i = \mathbf{H}_i^{-1} : \mathbf{L}_i : \left( \boldsymbol{\varepsilon} - \boldsymbol{\varepsilon}^{v}_i \right), \qquad \mathbf{H}_i = 3\,\eta_{B,i}\,\mathbf{I}_{vol} + 2\,\eta_{S,i}\,\mathbf{I}_{dev} , \]so each branch has a bulk and a shear relaxation time \( \tau_{B,i} = \eta_{B,i} / K_i \) and \( \tau_{S,i} = \eta_{S,i} / \mu_i \), with \( K_i = E_i / (3 (1 - 2\nu_i)) \) and \( \mu_i = E_i / (2 (1 + \nu_i)) \).Instantaneous versus long-term stiffness (convention):
\( (E_0, \nu_0) \) define the instantaneous (glassy) stiffness: at \( t = 0 \) every \( \boldsymbol{\varepsilon}^{v}_i \) vanishes and \( \boldsymbol{\sigma} = \mathbf{L}_0 : \boldsymbol{\varepsilon} \). As \( t \to \infty \) each \( \boldsymbol{\varepsilon}^{v}_i \) tends to \( \boldsymbol{\varepsilon} \) and the response relaxes to
\[ \mathbf{L}_\infty = \mathbf{L}_0 - \sum_{i=1}^N \mathbf{L}_i , \]i.e. the uniaxial relaxation modulus is the Prony series \( E(t) = E_\infty + \sum_i E_i\, e^{-t/\tau_i} \) written with \( E(0) = E_0 = E_\infty + \sum_i E_i \). The branch moduli must satisfy \( \sum_i \mathbf{L}_i < \mathbf{L}_0 \) ( \( \sum_i E_i < E_0 \) for equal Poisson ratios); nothing validates it, and a violation gives a negative long-term stiffness (the stress crosses zero during a hold). A calibration that provides the long-term modulus must pass \( E_0 = E_\infty + \sum_i E_i \).Integration:
Backward Euler, solved in closed form (maxwell_parallel_step, linear_viscoelastic.hpp): the branches decouple, \( \boldsymbol{\varepsilon}^v_i = \mathbf{B}_i^{-1}\boldsymbol{\varepsilon}^v_{i,n} + \mathbf{C}_i\mathbf{L}_i\boldsymbol{\varepsilon}^e \) with \( \mathbf{C}_i = \Delta t\,(\mathbf{H}_i + \Delta t\,\mathbf{L}_i)^{-1} \), and the consistent tangent is
\[ \mathbf{L}_t = \mathbf{L}_0 - \sum_{i=1}^N \mathbf{L}_i \mathbf{C}_i \mathbf{L}_i \](exact, whatevertangent_modebuttangent_none, which returns \( \mathbf{L}_0 \)). The multipliers \( v_i \) accumulate \( \| \Delta\boldsymbol{\varepsilon}^v_i \| \). When \( \Delta t \le \)iotathe branches are inactive ( \( \mathbf{C}_i = \mathbf{0} \)): the solver probes the tangent with a zero time increment at every block start and commits that answer, so a kernel returning its stationary condition there would relax one branch per block boundary.**Material parameters (props), \( n_{props} = 4 + 4N \):**
Index
Symbol
Description
Units
props[0]
\( E_0 \)
Instantaneous Young’s modulus
Stress
props[1]
\( \nu_0 \)
Instantaneous Poisson’s ratio
-
props[2]
\( \alpha \)
Isotropic thermal expansion coefficient
1/Temperature
props[3]
\( N \)
Number of Maxwell branches
-
props[4+4(i-1)]
\( E_i \)
Young’s modulus of branch i
Stress
props[5+4(i-1)]
\( \nu_i \)
Poisson’s ratio of branch i
-
props[6+4(i-1)]
\( \eta_{B,i} \)
Bulk viscosity of branch i
Stress x Time
props[7+4(i-1)]
\( \eta_{S,i} \)
Shear viscosity of branch i
Stress x Time
**State variables (statev), \( n_{statev} = 7 + 7N \):**
Index
Symbol
Description
Units
statev[0]
\( T_{init} \)
Initial temperature
Temperature
statev[1:6]
\( \tilde{\boldsymbol{\varepsilon}}^{v} \)
Total viscous strain \( \sum_i \mathbf{M}_0 : \mathbf{L}_i : \boldsymbol{\varepsilon}^{v}_i \) (Voigt)
-
statev[7+7(i-1)]
\( v_i \)
Accumulated flow length of branch i
-
statev[8+7(i-1):13+7(i-1)]
\( \boldsymbol{\varepsilon}^{v}_i \)
Viscous strain of branch i (Voigt)
-
// One Maxwell branch: E_0 = 3000 MPa, nu_0 = 0.35, no thermal expansion, // E_1 = 1500 MPa, nu_1 = 0.35, etaB_1 = 3000 MPa.s, etaS_1 = 1200 MPa.s // (long-term modulus E_0 - E_1 = 1500 MPa). vec props = {3000., 0.35, 0., 1., 1500., 0.35, 3000., 1200.}; vec statev = zeros(7 + 7*1);
See also
umat_prony_Nfast_T() thermomechanical twin (props prefixed by \( \rho, c_p \))
See also
umat_zener_Nfast() same props layout, different rheology
See also
ViscoelasticMechanism the modular (
MODUL) twin of this kernelSee also
H_iso() for the bulk/shear viscosity tensor
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
Not equivalent to umat_zener_Nfast(): identical props layout, but that kernel is a generalized Kelvin chain (branches in series with the spring), not a generalized Maxwell model
Note
The thermal strain enters the stress, not the branch flow: branch i is driven by \( \boldsymbol{\varepsilon} - \boldsymbol{\varepsilon}^{v}_i \)
Note
Relaxation times should span the loading time scales; the time step should stay small against the shortest one for accuracy
- Parameters:
umat_name – Name of the constitutive law (unused)
Etot – Total strain at the beginning of the increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment (Voigt notation: \(6 \times 1\) vector)
stress – Stress (Voigt notation: \(6 \times 1\) vector) [input/output]
Lt – Consistent tangent modulus ( \(6 \times 6\) matrix) [output]
L – Instantaneous elastic stiffness \( \mathbf{L}_0 \) ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (see table above)
nstatev – Number of state variables
statev – State variables vector (see table above) [input/output]
T – Temperature at the beginning of the increment
DT – Temperature increment
Time – Time at the beginning of the increment
DTime – Time increment
Wm – Total mechanical work [input/output, cumulative]
Wm_r – Recoverable (stored) work [input/output, cumulative]
Wm_ir – Irrecoverable stored work, always 0 for this model [input/output]
Wm_d – Dissipated (viscous) work [input/output, cumulative]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating the first increment (true) or a continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
tangent_mode – Tangent operator selection (see parameter.hpp)
-
void umat_zener_fast(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Standard linear solid in its Poynting–Thomson (Kelvin) form (
ZENER): a spring \( \mathbf{L}_0 \) in series with one Kelvin–Voigt unit \( (\mathbf{L}_1, \mathbf{H}_1) \).The instantaneous spring and the Kelvin unit carry the same stress:
\[\boldsymbol{\sigma} = \mathbf{L}_0 : \left( \boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,(T - T_{init}) - \boldsymbol{\varepsilon}^{v} \right) = \mathbf{L}_1 : \boldsymbol{\varepsilon}^{v} + \mathbf{H}_1 : \dot{\boldsymbol{\varepsilon}}^{v}, \]with \( \mathbf{L}_0 = \mathbf{L}_{iso}(E_0, \nu_0) \), \( \mathbf{L}_1 = \mathbf{L}_{iso}(E_1, \nu_1) \) and the viscosity tensor \( \mathbf{H}_1 = 3\eta_{B,1}\,\mathbf{I}_{vol} + 2\eta_{S,1}\,\mathbf{I}_{dev} \) (H_iso).ZENNK(umat_zener_Nfast()) chains \( N \) such units in series.One-dimensional response. With the dashpot viscosity \( \eta_1 \):
\[\sigma + \tau_r\,\dot{\sigma} = E_\infty\,\varepsilon + E_0\,\tau_r\,\dot{\varepsilon},\qquad J(t) = \frac{1}{E_0} + \frac{1}{E_1}\left(1 - e^{-t/\tau_c}\right),\qquad E(t) = E_\infty + (E_0 - E_\infty)\,e^{-t/\tau_r}, \]with the retardation time \( \tau_c = \eta_1 / E_1 \), the relaxation time \( \tau_r = \eta_1 / (E_0 + E_1) \) and the relaxed modulus \( E_\infty = E_0 E_1 / (E_0 + E_1) \). The same solid in its Zener (Maxwell) form, a spring \( E_\infty \) in parallel with a Maxwell branch \( (E_M, \eta_M) \), has \( E_M = E_0^2 / (E_0 + E_1) \) and \( \eta_M = \eta_1 E_0^2 / (E_0 + E_1)^2 \). In 3D the props of the two forms do not map one to one (each branch has its own Poisson ratio and bulk and shear viscosities): this law is not the one-branch umat_prony_Nfast() (PRONK, generalized Maxwell).Discrete update. Backward Euler on \( \boldsymbol{\varepsilon}^{v} \), solved in closed form (kelvin_series_step, linear_viscoelastic.hpp); the tangent is the exact derivative of that update ( \( \mathbf{L}_0 \) under tangent_none).
Work split. \( \Delta W_d = \tfrac{1}{2}\left(\mathbf{A}^{v}_n + \mathbf{A}^{v}_{n+1}\right) : \Delta\boldsymbol{\varepsilon}^{v} \) with \( \mathbf{A}^{v} = \boldsymbol{\sigma} - \mathbf{L}_1 : \boldsymbol{\varepsilon}^{v} \), \( W_r = W - W_d \), \( W_{ir} = 0 \).
Material properties (7; MPa, MPa.s):
Index
Symbol
Description
props[0]
\( E_0 \)
Young modulus of the instantaneous spring
props[1]
\( \nu_0 \)
Poisson ratio of the instantaneous spring
props[2]
\( \alpha \)
isotropic thermal expansion coefficient
props[3]
\( E_1 \)
Young modulus of the Kelvin unit
props[4]
\( \nu_1 \)
Poisson ratio of the Kelvin unit
props[5]
\( \eta_{B,1} \)
bulk viscosity of the Kelvin unit
props[6]
\( \eta_{S,1} \)
shear viscosity of the Kelvin unit
State variables (8; Voigt order [11, 22, 33, 12, 13, 23], engineering shear strains):
Index
Symbol
Description
statev[0]
\( T_{init} \)
initial temperature
statev[1]
\( v \)
accumulated viscous strain \( \sum \|\Delta\boldsymbol{\varepsilon}^{v}\| \)
statev[2..7]
\( \boldsymbol{\varepsilon}^{v} \)
viscous strain of the Kelvin unit
References:
Zener, C. (1948). Elasticity and Anelasticity of Metals. University of Chicago Press.
Tschoegl, N. W. (1989). The Phenomenological Theory of Linear Viscoelastic Behavior. Springer.
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).- Parameters:
Etot – Total strain tensor at beginning of increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment tensor (Voigt notation: \(6 \times 1\) vector)
stress – Stress tensor (Voigt notation: \(6 \times 1\) vector) [output]
Lt – Consistent tangent modulus ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (see table above)
nstatev – Number of state variables
statev – State variables vector (see table above) [input/output]
T – Temperature at beginning of increment
DT – Temperature increment
Time – Time at beginning of increment
DTime – Time increment
Wm – Total mechanical work [output]
Wm_r – Recoverable (elastic) work [output]
Wm_ir – Irrecoverable work stored in viscous elements [output]
Wm_d – Dissipated (viscous) work [output]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating first increment (true) or continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
-
void umat_zener_Nfast(const std::string &umat_name, const arma::vec &Etot, const arma::vec &DEtot, arma::vec &stress, arma::mat &Lt, arma::mat &L, const arma::mat &DR, const int &nprops, const arma::vec &props, const int &nstatev, arma::vec &statev, const double &T, const double &DT, const double &Time, const double &DTime, double &Wm, double &Wm_r, double &Wm_ir, double &Wm_d, const int &ndi, const int &nshr, const bool &start, double &tnew_dt, const int &tangent_mode = tangent_default)
Generalized Kelvin chain (Zener) linear viscoelastic model with N units (
ZENNK).Isotropic, rate-dependent, linear viscoelastic model with thermal expansion: an instantaneous spring \( \mathbf{L}_0 \) in series with \( N \) Kelvin–Voigt units, each a spring \( \mathbf{L}_i \) in parallel with a dashpot \( \mathbf{H}_i \) (generalized Kelvin chain; \( N = 1 \) is the Poynting–Thomson / Zener solid).
Rheological representation:
┌── L_1 /\/\/\──┐ ┌── L_N /\/\/\──┐ ────/\/\/\──────────┤ ├──────┤ ├──── L_0 └──[ H_1 ]──────┘ ... └──[ H_N ]──────┘ (instantaneous) unit 1 unit NConstitutive equations (Voigt notation, engineering shear strains):
The instantaneous spring carries the whole stress on the elastic part of the strain,
\[ \boldsymbol{\sigma} = \mathbf{L}_0 : \left( \boldsymbol{\varepsilon} - \boldsymbol{\alpha}\,(T - T_{init}) - \boldsymbol{\varepsilon}^{v} \right), \qquad \boldsymbol{\varepsilon}^{v} = \sum_{i=1}^N \boldsymbol{\varepsilon}^{v}_i , \]with \( \mathbf{L}_0 = \mathbf{L}_{iso}(E_0, \nu_0) \) and \( \mathbf{L}_i = \mathbf{L}_{iso}(E_i, \nu_i) \). Each Kelvin unit sees that same stress and its dashpot carries what its spring does not,\[ \dot{\boldsymbol{\varepsilon}}^{v}_i = \mathbf{H}_i^{-1} : \left( \boldsymbol{\sigma} - \mathbf{L}_i : \boldsymbol{\varepsilon}^{v}_i \right), \qquad \mathbf{H}_i = 3\,\eta_{B,i}\,\mathbf{I}_{vol} + 2\,\eta_{S,i}\,\mathbf{I}_{dev} , \]so each unit has a bulk and a shear retardation time \( \tau_{B,i} = \eta_{B,i} / K_i \) and \( \tau_{S,i} = \eta_{S,i} / \mu_i \), with \( K_i = E_i / (3 (1 - 2\nu_i)) \) and \( \mu_i = E_i / (2 (1 + \nu_i)) \).Instantaneous versus long-term response:
\( (E_0, \nu_0) \) define the instantaneous stiffness (every \( \boldsymbol{\varepsilon}^{v}_i \) vanishes at \( t = 0 \)). Under a constant stress each unit creeps to \( \boldsymbol{\varepsilon}^{v}_i = \mathbf{M}_i : \boldsymbol{\sigma} \), so the long-term response is the series compliance
\[ \mathbf{M}_\infty = \mathbf{M}_0 + \sum_{i=1}^N \mathbf{M}_i , \qquad \mathbf{M}_i = \mathbf{L}_i^{-1} , \]i.e. the uniaxial creep compliance is \( J(t) = 1/E_0 + \sum_i (1 - e^{-t/\tau_i}) / E_i \). There is no admissibility constraint between the unit moduli and \( E_0 \) (a chain only gets more compliant), unlike the generalized Maxwell model of umat_prony_Nfast().Integration:
Backward Euler, solved in closed form (kelvin_series_step, linear_viscoelastic.hpp): with \( \mathbf{C}_i = \Delta t\,(\mathbf{H}_i + \Delta t\,\mathbf{L}_i)^{-1} \) the implicit step is the linear system \( (\mathbf{I} + \mathbf{L}_0 \sum_i \mathbf{C}_i)\,\boldsymbol{\sigma} = \mathbf{L}_0 (\boldsymbol{\varepsilon}^e - \sum_i \mathbf{B}_i^{-1} \boldsymbol{\varepsilon}^v_{i,n}) \), and the consistent tangent is \( \mathbf{L}_t = (\mathbf{M}_0 + \sum_i \mathbf{C}_i)^{-1} \) (exact, whatever
tangent_modebuttangent_none, which returns \( \mathbf{L}_0 \)). The multipliers \( v_i \) accumulate \( \| \Delta\boldsymbol{\varepsilon}^v_i \| \). When \( \Delta t \le \)iotathe branches are inactive ( \( \mathbf{C}_i = \mathbf{0} \)): the solver probes the tangent with a zero time increment at every block start and commits that answer, so a kernel returning its stationary condition there would relax one branch per block boundary.**Material parameters (props), \( n_{props} = 4 + 4N \):**
Index
Symbol
Description
Units
props[0]
\( E_0 \)
Instantaneous Young’s modulus
Stress
props[1]
\( \nu_0 \)
Instantaneous Poisson’s ratio
-
props[2]
\( \alpha \)
Isotropic thermal expansion coefficient
1/Temperature
props[3]
\( N \)
Number of Kelvin units
-
props[4+4(i-1)]
\( E_i \)
Young’s modulus of branch i
Stress
props[5+4(i-1)]
\( \nu_i \)
Poisson’s ratio of branch i
-
props[6+4(i-1)]
\( \eta_{B,i} \)
Bulk viscosity of branch i
Stress x Time
props[7+4(i-1)]
\( \eta_{S,i} \)
Shear viscosity of branch i
Stress x Time
**State variables (statev), \( n_{statev} = 7 + 7N \):**
Index
Symbol
Description
Units
statev[0]
\( T_{init} \)
Initial temperature
Temperature
statev[1:6]
\( \boldsymbol{\varepsilon}^{v} \)
Total viscous strain \( \sum_i \boldsymbol{\varepsilon}^{v}_i \) (Voigt)
-
statev[7+7(i-1)]
\( v_i \)
Accumulated flow length of branch i
-
statev[8+7(i-1):13+7(i-1)]
\( \boldsymbol{\varepsilon}^{v}_i \)
Viscous strain of branch i (Voigt)
-
// One Kelvin unit: E_0 = 3000 MPa, nu_0 = 0.35, no thermal expansion, // E_1 = 1500 MPa, nu_1 = 0.35, etaB_1 = 3000 MPa.s, etaS_1 = 1200 MPa.s // (long-term modulus 1/(1/E_0 + 1/E_1) = 1000 MPa). vec props = {3000., 0.35, 0., 1., 1500., 0.35, 3000., 1200.}; vec statev = zeros(7 + 7*1);
See also
umat_zener_Nfast_T() thermomechanical twin (props prefixed by \( \rho, c_p \))
See also
umat_prony_Nfast() same props layout, different rheology
See also
umat_zener_fast() the single-unit version (
ZENER: no N slot, \( n_{statev} = 8 \))See also
H_iso() for the bulk/shear viscosity tensor
Note
Stress measure. The stress returned by this model (the
stressargument, written \( \boldsymbol{\sigma} \) in the relations above) is the Cauchy stress under infinitesimal strain; under finite strain the update runs in a corotational frame, so it is the rotated Kirchhoff stress \( \hat{\boldsymbol{\tau}} = \boldsymbol{Q}^{T}\boldsymbol{\tau}\,\boldsymbol{Q} \) on the frame fixed by the chosen objective rate ( \( \boldsymbol{Q} = \boldsymbol{R} \) for Green–Naghdi and \( \log_R \), the logarithmic frame for the XBM/log rate, \( \boldsymbol{F} \) for \( \log_F \)).Note
Not equivalent to umat_prony_Nfast(): identical props layout, but a generalized Kelvin chain (units in series) instead of a generalized Maxwell model (branches in parallel); the measured response difference for the same numbers is of order 1
Note
Retardation times should span the loading time scales; the time step should stay small against the shortest one for accuracy
- Parameters:
umat_name – Name of the constitutive law (unused)
Etot – Total strain at the beginning of the increment (Voigt notation: \(6 \times 1\) vector)
DEtot – Strain increment (Voigt notation: \(6 \times 1\) vector)
stress – Stress (Voigt notation: \(6 \times 1\) vector) [input/output]
Lt – Consistent tangent modulus ( \(6 \times 6\) matrix) [output]
L – Instantaneous elastic stiffness \( \mathbf{L}_0 \) ( \(6 \times 6\) matrix) [output]
DR – Rotation increment matrix ( \(3 \times 3\)) for objective integration
nprops – Number of material properties
props – Material properties vector (see table above)
nstatev – Number of state variables
statev – State variables vector (see table above) [input/output]
T – Temperature at the beginning of the increment
DT – Temperature increment
Time – Time at the beginning of the increment
DTime – Time increment
Wm – Total mechanical work [input/output, cumulative]
Wm_r – Recoverable (stored) work [input/output, cumulative]
Wm_ir – Irrecoverable stored work, always 0 for this model [input/output]
Wm_d – Dissipated (viscous) work [input/output, cumulative]
ndi – Number of direct stress components (typically 3)
nshr – Number of shear stress components (typically 3)
start – Flag indicating the first increment (true) or a continuation (false)
tnew_dt – Suggested new time step size for adaptive time stepping [output]
tangent_mode – Tangent operator selection (see parameter.hpp)
-
void get_L_elastic(phase_characteristics&)
-
struct fea_components
- #include <fea_transfer.hpp>
Correspondence between the components of an FE code and simcoon’s Voigt order.
FE entry i is simcoon component K[i] (simcoon order [11, 22, 33, 12, 13, 23]); the others are absent from the element (zero strain in 3D, stress-free in a condensed state).
Public Functions
-
inline int operator()(const int &i) const
-
inline int operator()(const int &i) const