<?xml version="1.0" encoding="UTF-8"?>
<userMaterialDocumentation version="1" library="IMPETUS example user material">
  <material command="MAT_USER_1" title="IMPETUS example user material" name="Example metal plasticity">
    <parameter name="mid" description="Material identification number."/>
    <parameter name="rho" description="Initial mass density."/>
    <parameter name="E" description="Young's modulus."/>
    <parameter name="nu" description="Poisson's ratio."/>
    <parameter name="did" description="Optional damage property id. Leave blank or set to 0 when unused."/>
    <parameter name="tid" description="Optional thermal property id. Leave blank or set to 0 when unused."/>
    <parameter name="eosid" description="Optional equation-of-state id. Leave blank or set to 0 when unused."/>
    <break/>
    <parameter name="idlc" description="Curve or function id for flow stress versus effective plastic strain."/>
    <parameter name="epsf" description="Effective plastic strain at failure. Set to 0 to disable this damage accumulation."/>
    <description>
      <text>
        Use [b]IMPETUS example user material[/b] as the optional title line. The GUI uses this title as the user material library name when it looks for the matching XML documentation file while the cursor is on a [b]*MAT_USER_X[/b] command. If the title does not match the DLL and XML base name, the editor manual may not show this documentation.
      </text>
      <text>
        The metal example is an isotropic elastic-plastic von Mises material. The elastic response is defined by E and nu. Plastic flow is driven by a user curve or function that returns the current flow stress as a function of effective plastic strain.
      </text>
      <equation><![CDATA[
        $\displaystyle K=\frac{E}{3(1-2\nu)}, \qquad G=\frac{E}{2(1+\nu)}$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle q=\sqrt{\frac{3}{2}\mathbf{s}:\mathbf{s}}, \qquad
        q \le \sigma_y(\bar{\varepsilon}_p)$
      ]]></equation>
      <text>
        Pressure is positive in compression and the Cauchy stress is assembled from deviatoric stress and pressure. The material records effective plastic strain, damage, current yield stress, temperature, and the latest plastic strain increment as history values.
      </text>
      <text>
        The optional failure strain epsf is a simple demonstration damage rule. When epsf is greater than zero, damage increases by the plastic strain increment divided by epsf.
      </text>
    </description>
    <example headline="Material card">
      <fixed><![CDATA[*MAT_USER_1
"IMPETUS example user material"
mid,rho,E,nu,did,tid,eosid
idlc,epsf]]></fixed>
    </example>
    <example headline="Simple SI example">
      <fixed><![CDATA[*MAT_USER_1
"IMPETUS example user material"
1, 7800.0, 210.0e9, 0.30
1, 0.15

*FUNCTION
"Flow stress vs effective plastic strain"
1
500.0e6 + 300.0e6*epsp^0.25]]></fixed>
    </example>
  </material>

  <material command="MAT_USER_2" title="IMPETUS example user material" name="Example concrete compaction and damage">
    <parameter name="mid" description="Material identification number."/>
    <parameter name="rho" description="Initial mass density."/>
    <parameter name="G" description="Shear modulus used by this example material."/>
    <parameter name="unused_cmat2" description="Reserved header value. Leave blank or set to 0."/>
    <parameter name="did" description="Optional damage property id. Leave blank or set to 0 when unused."/>
    <parameter name="tid" description="Optional thermal property id. Leave blank or set to 0 when unused."/>
    <parameter name="eosid" description="Optional equation-of-state id. Leave blank or set to 0 when unused."/>
    <break/>
    <parameter name="A" description="Normalized cohesive strength."/>
    <parameter name="B" description="Normalized pressure hardening coefficient."/>
    <parameter name="n" description="Pressure hardening exponent."/>
    <parameter name="f_c" description="Compressive strength scale."/>
    <parameter name="T" description="Tensile cut-off strength."/>
    <parameter name="epsf_min" description="Minimum failure strain."/>
    <parameter name="p_c" description="Crush pressure."/>
    <parameter name="p_l" description="Locking pressure."/>
    <break/>
    <parameter name="epsv_c_l" description="Volumetric compaction strain at locking."/>
    <parameter name="D1" description="Damage parameter D1."/>
    <parameter name="D2" description="Damage parameter D2."/>
    <parameter name="K" description="Bulk modulus."/>
    <description>
      <text>
        Use [b]IMPETUS example user material[/b] as the optional title line. The GUI uses this title as the user material library name when it looks for the matching XML documentation file while the cursor is on a [b]*MAT_USER_X[/b] command. If the title does not match the DLL and XML base name, the editor manual may not show this documentation.
      </text>
      <text>
        The concrete example is a compact pressure-dependent damage material inspired by Holmquist-Johnson-Cook concrete behavior. It demonstrates inelastic volumetric compaction, pressure hardening, tensile cut-off, and scalar damage.
      </text>
      <equation><![CDATA[
        $\displaystyle p=K(\varepsilon_v-\varepsilon^c_v), \qquad
        p_{flow}=(1-\xi)p_c+\xi p_l, \qquad
        \xi=\frac{\varepsilon^c_v}{\varepsilon^c_{v,l}}$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle \sigma_y =
        \begin{cases}
        f_c\left(A(1-D)+B(p/f_c)^n\right), & p>0 \\
        f_c A\left(1+p/T\right)(1-D), & p\le 0
        \end{cases}$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle \varepsilon_f=\max\left(\varepsilon_{f,min},D_1(p/f_c+T/f_c)^{D_2}\right)$
      ]]></equation>
      <text>
        Pressure is positive in compression. The model uses the G value from the first material line and K from the final custom value. Damage increases from deviatoric plastic flow and inelastic compaction. The history output contains effective plastic strain, inelastic compaction, and damage.
      </text>
      <text>
        This is an instructional model. Calibrations should be checked against single-element compression, tension, and confined compression cases before use in larger analyses.
      </text>
    </description>
    <example headline="Material card">
      <fixed><![CDATA[*MAT_USER_2
"IMPETUS example user material"
mid,rho,G
A,B,n,f_c,T,epsf_min,p_c,p_l
epsv_c_l,D1,D2,K]]></fixed>
    </example>
    <example headline="Simple SI example">
      <fixed><![CDATA[*MAT_USER_2
"IMPETUS example user material"
1, 2300.0, 12.5e9
0.10, 1.0, 1.0, 50.0e6, 5.0e6, 2.0e-3, 100.0e6, 500.0e6
0.05, 0.02, 0.5, 16.67e9]]></fixed>
    </example>
  </material>

  <material command="MAT_USER_3" title="IMPETUS example user material" name="Example Mooney-Rivlin rubber">
    <parameter name="mid" description="Material identification number."/>
    <parameter name="rho" description="Initial mass density."/>
    <parameter name="bulk" description="Bulk modulus for volumetric response."/>
    <parameter name="unused_cmat2" description="Reserved header value. Leave blank or set to 0."/>
    <parameter name="did" description="Optional damage property id. Leave blank or set to 0 when unused."/>
    <parameter name="tid" description="Optional thermal property id. Leave blank or set to 0 when unused."/>
    <parameter name="eosid" description="Optional equation-of-state id. Leave blank or set to 0 when unused."/>
    <break/>
    <parameter name="C1" description="First Mooney-Rivlin coefficient."/>
    <parameter name="C2" description="Second Mooney-Rivlin coefficient."/>
    <description>
      <text>
        Use [b]IMPETUS example user material[/b] as the optional title line. The GUI uses this title as the user material library name when it looks for the matching XML documentation file while the cursor is on a [b]*MAT_USER_X[/b] command. If the title does not match the DLL and XML base name, the editor manual may not show this documentation.
      </text>
      <text>
        The rubber example is a compressible Mooney-Rivlin hyperelastic material. It is intended for large elastic deformation demonstrations with a simple volumetric penalty controlled by the bulk modulus.
      </text>
      <equation><![CDATA[
        $\displaystyle W=C_1(I_1-3)+C_2(I_2-3)+W_{vol}(J)$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle p=-K\varepsilon_v, \qquad
        E_{small}=6(C_1+C_2)$
      ]]></equation>
      <text>
        The material calculates stresses from the principal stretches of the deformation. The history output stores the three principal stress values used for contour display.
      </text>
      <text>
        Choose a bulk modulus high enough for the intended compressibility, but avoid unrealistically high values that drive the stable time step too low.
      </text>
    </description>
    <example headline="Material card">
      <fixed><![CDATA[*MAT_USER_3
"IMPETUS example user material"
mid,rho,bulk
C1,C2]]></fixed>
    </example>
    <example headline="Simple SI example">
      <fixed><![CDATA[*MAT_USER_3
"IMPETUS example user material"
1, 1000.0, 1.0e8
1.0e6, 1.0e6]]></fixed>
    </example>
  </material>

  <material command="MAT_USER_4" title="IMPETUS example user material" name="Example orthotropic composite">
    <parameter name="mid" description="Material identification number."/>
    <parameter name="rho" description="Initial mass density."/>
    <parameter name="unused_cmat1" description="Reserved header value. Leave blank or set to 0."/>
    <parameter name="unused_cmat2" description="Reserved header value. Leave blank or set to 0."/>
    <parameter name="did" description="Optional damage property id. Leave blank or set to 0 when unused."/>
    <parameter name="tid" description="Optional thermal property id. Leave blank or set to 0 when unused."/>
    <parameter name="eosid" description="Optional equation-of-state id. Leave blank or set to 0 when unused."/>
    <break/>
    <parameter name="E1" description="Young's modulus in the first material direction."/>
    <parameter name="E2" description="Young's modulus in the transverse material directions."/>
    <parameter name="G12" description="In-plane shear modulus."/>
    <parameter name="pr12" description="Poisson's ratio in the 1-2 material plane."/>
    <parameter name="pr23" description="Poisson's ratio in the transverse plane."/>
    <parameter name="unused_cmat11" description="Reserved value. Leave blank or set to 0."/>
    <parameter name="unused_cmat12" description="Reserved value. Leave blank or set to 0."/>
    <parameter name="unused_cmat13" description="Reserved value. Leave blank or set to 0."/>
    <break/>
    <parameter name="c" description="Viscosity coefficient. Set to 0 to disable rate smoothing."/>
    <parameter name="cdec" description="Viscous decay time."/>
    <parameter name="Xt" description="Tensile strength in the first material direction. Set to 0 for a very large default strength."/>
    <parameter name="Xc" description="Compressive strength in the first material direction. Set to 0 for a very large default strength."/>
    <parameter name="Yt" description="Tensile strength in the transverse material direction. Set to 0 for a very large default strength."/>
    <parameter name="Yc" description="Compressive strength in the transverse material direction. Set to 0 for a very large default strength."/>
    <parameter name="beta" description="Failure interaction parameter for tensile modes with shear."/>
    <parameter name="S" description="Shear strength parameter. Set to 0 for a very large default strength."/>
    <break/>
    <parameter name="erode" description="Element erosion flag. 0 keeps failed material, 1 allows element erosion."/>
    <parameter name="residual" description="Residual stress multiplier after failure."/>
    <description>
      <text>
        Use [b]IMPETUS example user material[/b] as the optional title line. The GUI uses this title as the user material library name when it looks for the matching XML documentation file while the cursor is on a [b]*MAT_USER_X[/b] command. If the title does not match the DLL and XML base name, the editor manual may not show this documentation.
      </text>
      <text>
        The orthotropic example represents a directional elastic solid with simple composite-style failure checks. It requires a material direction definition in the input model so that the first material direction is known.
      </text>
      <equation><![CDATA[
        $\displaystyle
        \begin{bmatrix}\varepsilon_1\\ \varepsilon_2\\ \varepsilon_3\end{bmatrix}
        =
        \begin{bmatrix}
        1/E_1 & -\nu_{12}/E_1 & -\nu_{12}/E_1 \\
        -\nu_{12}/E_1 & 1/E_2 & -\nu_{23}/E_2 \\
        -\nu_{12}/E_1 & -\nu_{23}/E_2 & 1/E_2
        \end{bmatrix}
        \begin{bmatrix}\sigma_1\\ \sigma_2\\ \sigma_3\end{bmatrix}
      ]]></equation>
      <text>
        The model checks fiber tension, fiber compression, matrix tension, and matrix compression using the supplied strengths. Failed modes reduce the corresponding stress components by the residual multiplier. The history output contains the four damage mode indicators and the maximum damage.
      </text>
      <text>
        Use [b]*INITIAL_MATERIAL_DIRECTION_WRAP[/b] or another suitable material direction command to define the orthotropic axes before running this material.
      </text>
    </description>
    <example headline="Material card">
      <fixed><![CDATA[*MAT_USER_4
"IMPETUS example user material"
mid,rho
E1,E2,G12,pr12,pr23
c,cdec,Xt,Xc,Yt,Yc,beta,S
erode,residual]]></fixed>
    </example>
    <example headline="Simple SI example">
      <fixed><![CDATA[*MAT_USER_4
"IMPETUS example user material"
1, 1500.0
1.0e10, 1.0e8, 2.0e7, 0.20, 0.20
1.0e3, 1.0e-6, 6.0e8, 5.0e8, 5.0e7, 1.5e8, 0.5, 5.0e7
1, 0.05

*INITIAL_MATERIAL_DIRECTION_WRAP
1, P, 1
1.0, 0.0, 0.0,  0.0, 0.0, 1.0]]></fixed>
    </example>
  </material>

  <material command="MAT_USER_5" title="IMPETUS example user material" name="Example glass damage">
    <parameter name="mid" description="Material identification number."/>
    <parameter name="rho" description="Initial mass density."/>
    <parameter name="E" description="Young's modulus."/>
    <parameter name="nu" description="Poisson's ratio."/>
    <parameter name="did" description="Optional damage property id. Leave blank or set to 0 when unused."/>
    <parameter name="tid" description="Optional thermal property id. Leave blank or set to 0 when unused."/>
    <parameter name="eosid" description="Optional equation-of-state id. Leave blank or set to 0 when unused."/>
    <break/>
    <parameter name="c" description="Viscosity coefficient. Set to 0 to disable viscous stress."/>
    <parameter name="cdec" description="Viscous decay time."/>
    <parameter name="stress_c" description="Critical tensile stress for damage growth."/>
    <parameter name="k_c" description="Critical stress intensity for flaw-driven damage growth."/>
    <parameter name="t_c" description="Characteristic damage time."/>
    <parameter name="a_c" description="Damage growth exponent."/>
    <parameter name="unused_cmat12" description="Reserved value. Leave blank or set to 0."/>
    <parameter name="unused_cmat13" description="Reserved value. Leave blank or set to 0."/>
    <break/>
    <parameter name="flaw_dim" description="Flaw dimension selector. Use 0 unless flaw history values are initialized separately."/>
    <parameter name="surface_t1" description="Top surface normal component 1."/>
    <parameter name="surface_t2" description="Top surface normal component 2."/>
    <parameter name="surface_t3" description="Top surface normal component 3."/>
    <parameter name="surface_b1" description="Bottom surface normal component 1."/>
    <parameter name="surface_b2" description="Bottom surface normal component 2."/>
    <parameter name="surface_b3" description="Bottom surface normal component 3."/>
    <description>
      <text>
        Use [b]IMPETUS example user material[/b] as the optional title line. The GUI uses this title as the user material library name when it looks for the matching XML documentation file while the cursor is on a [b]*MAT_USER_X[/b] command. If the title does not match the DLL and XML base name, the editor manual may not show this documentation.
      </text>
      <text>
        The glass example is a CPU-only brittle damage material. It demonstrates elastic stress calculation, rate smoothing, tensile stress damage, and optional flaw-driven damage.
      </text>
      <equation><![CDATA[
        $\displaystyle p=-K\varepsilon_v, \qquad
        \mathbf{s}=2G\mathbf{e}_{dev}$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle \Delta D =
        \begin{cases}
        \frac{\Delta t}{t_c}\left(\sigma_{max}/\sigma_c\right)^{a_c}, & \sigma_{max}>\sigma_c \\
        0, & \sigma_{max}\le\sigma_c
        \end{cases}$
      ]]></equation>
      <equation><![CDATA[
        $\displaystyle K_I=Y\sigma_n\sqrt{\pi a}$
      ]]></equation>
      <text>
        Damage increases when the maximum principal tensile stress exceeds stress_c. If flaw history values have been initialized, damage can also increase when the stress intensity exceeds k_c. The history output contains damage, viscous stress terms, flaw data, and stress intensity data used by the example.
      </text>
      <text>
        The GPU support flag is false for this material. Run it on CPU, or use the other example materials when GPU execution is required.
      </text>
    </description>
    <example headline="Material card">
      <fixed><![CDATA[*MAT_USER_5
"IMPETUS example user material"
mid,rho,E,nu,did,tid,eosid
c,cdec,stress_c,k_c,t_c,a_c
flaw_dim,surface_t1,surface_t2,surface_t3,surface_b1,surface_b2,surface_b3]]></fixed>
    </example>
    <example headline="Simple SI example">
      <fixed><![CDATA[*MAT_USER_5
"IMPETUS example user material"
1, 2500.0, 70.0e9, 0.22
1.0e6, 1.0e-6, 50.0e6, 1.0e6, 1.0e-5, 2.0
0, 0.0, 0.0, 1.0, 0.0, 0.0, -1.0]]></fixed>
    </example>
  </material>
</userMaterialDocumentation>
