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 _R of abaqus_kinematic_form(). EPICP_closed_R names the law EPICP_closed in its rate form; the _closed suffix 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 _closed carries 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 _R asks 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). ndi is 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 (cs active) 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 from kin_statev under 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_mode is not used. L returns 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 backstress

See 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 stress argument, 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 stress argument, 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_umat off the surface sets tnew_dt to 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_mode

  • L – 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 stress argument, 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_algorithmic is 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 stress argument, 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/SMRAC route 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_algorithmic is 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 N

Constitutive 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, whatever tangent_mode but tangent_none, which returns \( \mathbf{L}_0 \)). The multipliers \( v_i \) accumulate \( \| \Delta\boldsymbol{\varepsilon}^v_i \| \). When \( \Delta t \le \) iota the 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 kernel

See also

H_iso() for the bulk/shear viscosity tensor

Note

Stress measure. The stress returned by this model (the stress argument, 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 stress argument, 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 N

Constitutive 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_mode but tangent_none, which returns \( \mathbf{L}_0 \)). The multipliers \( v_i \) accumulate \( \| \Delta\boldsymbol{\varepsilon}^v_i \| \). When \( \Delta t \le \) iota the 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 stress argument, 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

Public Members

int ntens

number of components of the element

int K[6]

simcoon index of each FE component