Ansys Integration
This guide explains how to use simcoon’s built-in constitutive models within Ansys MAPDL on Linux systems.
Note
Ansys USERMAT integration is more complex than Abaqus due to differences in the interface design.
Simcoon provides software/usermat_singleM.cpp as the Ansys equivalent of umat_singleM.cpp.
Overview
The Ansys USERMAT subroutine interface differs from Abaqus in several ways:
Voigt notation: Ansys uses (11, 22, 33, 12, 23, 13) vs simcoon’s (11, 22, 33, 12, 13, 23)
Finite strain handling: Ansys integrates the law in its own corotated frame (in practice the Green-Naghdi one), passes Cauchy stress and logarithmic strain already rotated, and defines
dsdePlas \(\partial \Delta\boldsymbol{\sigma} / \partial \Delta\boldsymbol{\varepsilon}\) in that frame, with no \(J\) factor: the kernel tangent is passed as is (unlike Abaqus, see Abaqus Integration). Every variable, the state variables included, is defined and updated in that frame, so the bridge applies no rotation of its own (therotateMslot is reserved and unused by Ansys)Time step control: limited to a cutback request (
keycut = 1), raised when the law asks for a smaller increment or the trial state fails numericallyState variable initialization: Cannot set non-zero initial values
Model selection: Uses numeric model code in props[0] instead of material name (the code maps to the same 5-character names — see Constitutive model (UMAT) catalog for the complete per-name reference)
Prerequisites
Linux System Requirements
# Required packages (Ubuntu/Debian)
sudo apt-get install build-essential cmake
sudo apt-get install libarmadillo-dev liblapack-dev libblas-dev
# Required packages (RHEL/CentOS)
sudo yum groupinstall "Development Tools"
sudo yum install cmake armadillo-devel lapack-devel blas-devel
simcoon Installation
Ensure simcoon is built and installed using the provided install script:
cd simcoon
sh Install.sh -n 4
# The script will:
# - Build simcoon with CMake/Ninja
# - Install to $CONDA_PREFIX (your conda environment)
# - Install the Python package
# - Optionally run tests
# To skip tests:
sh Install.sh -t -n 4
Using usermat_singleM.cpp
The software/usermat_singleM.cpp file provides the same functionality as the Abaqus bridge, but adapted for Ansys.
Step 1: Compile the USERMAT
cd simcoon/software
# Compile to shared library (using conda environment)
g++ -shared -fPIC -std=c++17 -O2 -o libusermat_simcoon.so usermat_singleM.cpp \
-I$CONDA_PREFIX/include \
-L$CONDA_PREFIX/lib -lsimcoon \
-larmadillo -llapack -lblas
Step 2: Set up library path
Ansys searches for libraries in directories specified by ANS_USER_PATH:
export ANS_USER_PATH=/path/to/your/usermat/directory
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$ANS_USER_PATH:$LD_LIBRARY_PATH
Step 3: Define material in MAPDL
Unlike Abaqus where the model is selected by material name, Ansys uses a model code as the first material property:
! EPICP model example (model code 5)
! Properties: code, E, nu, alpha, sigma_y, H
TB,USER,1,1,6
TBDATA,1,5 ! Model code for EPICP
TBDATA,2,210000 ! E
TBDATA,3,0.3 ! nu
TBDATA,4,0.0 ! alpha
TBDATA,5,200 ! sigma_y
TBDATA,6,1000 ! H
! Define state variables (nstatev_smart + 4 + nC; nC = 0 in 3D)
TB,STATE,1,,12
Model Codes
Code |
Name |
Model |
Additional Properties |
|---|---|---|---|
2 |
ELISO |
Isotropic elasticity |
\(E, \nu, \alpha\) |
3 |
ELIST |
Transversely isotropic elasticity |
axis, \(E_L, E_T, \nu_{TL}, \nu_{TT}, G_{LT}, \alpha_L, \alpha_T\) |
4 |
ELORT |
Orthotropic elasticity |
\(E_1, E_2, E_3, \nu_{12}, \nu_{13}, \nu_{23}, G_{12}, G_{13}, G_{23}, \alpha_1, \alpha_2, \alpha_3\) |
5 |
EPICP |
Von Mises plasticity, power-law isotropic hardening |
\(E, \nu, \alpha, \sigma_Y, k, m\) |
6 |
EPKCP |
Von Mises, power-law isotropic + Prager kinematic |
\(E, \nu, \alpha, \sigma_Y, k, m, k_X\) |
7 |
EPCHA |
Von Mises + Voce + 2× Armstrong-Frederick |
\(E, \nu, \alpha, \sigma_Y, Q, b, C_1, D_1, C_2, D_2\) |
29 |
EPJCK |
Von Mises + Johnson-Cook yield stress (rate and temperature dependent) |
\(E, \nu, \alpha, A, B, n, C, \dot{\varepsilon}_0, m, T_{\mathrm{ref}}, T_{\mathrm{melt}}\) |
8 |
SMADI |
SMA unified model |
See SMA documentation |
9 |
SMAAI |
SMA unified model, anisotropic criterion |
See SMA documentation |
10 |
LLDM0 |
Ladevèze-Le Dantec ply damage with effective-stress plasticity |
18 props, 10 statev (see the header documentation) |
11 |
ZENER |
Kelvin viscoelastic (single branch) |
\(E_0, \nu_0, \alpha, E_1, \nu_1, \eta_{B1}, \eta_{S1}\) |
12 |
ZENNK |
Kelvin viscoelastic (N branches) |
\(E_0, \nu_0, \alpha, N\), per branch: \(E_i, \nu_i, \eta_{Bi}, \eta_{Si}\) |
13 |
PRONK |
Prony series viscoelastic (generalized Maxwell) |
\(E_0, \nu_0, \alpha, N\), per branch: \(E_i, \nu_i, \eta_{Bi}, \eta_{Si}\) |
14 |
EPTRI |
Tresca-family plasticity (Hill layout) |
\(E, \nu, \alpha, \sigma_Y, k, m, F, G, H, L, M, N\) |
15 |
SMADC |
SMA unified model, cubic elasticity |
See SMA documentation |
16 |
SMAAC |
SMA unified model, cubic + anisotropic criterion |
See SMA documentation |
17 |
EPHIL |
Hill yield + power-law isotropic hardening |
\(E, \nu, \alpha, \sigma_Y, k, m, F, G, H, L, M, N\) |
18 |
EPHAC |
Cubic elasticity + Hill + Voce + 2× AF |
\(E, \nu, G, \alpha, \sigma_Y, Q, b, C_1, D_1, C_2, D_2, F, G, H, L, M, N\) |
25–28 |
SMRDI / SMRDC / SMRAI / SMRAC |
SMA unified transformation + reorientation (iso/cubic × iso/aniso) |
See SMA documentation |
200 |
MODUL |
Modular composition (props encode the mechanisms) |
See the modular UMAT documentation |
How It Works
Architecture
┌───────────────────────────────────────────────────────────────┐
│ Ansys MAPDL │
│ │ │
│ ▼ │
│ calls extern "C" usermat_() │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ usermat_singleM.cpp (bridge) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ansys2smart_M() (fea_transfer.hpp) │ │
│ │ - Converts stress, strain, dstrain → Armadillo │ │
│ │ - Remaps Voigt indices (swaps 4 ↔ 5 for 3D) │ │
│ │ - Reads Wm, the stored stress-free strain, the law │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ select_umat_M(rve, ...) │ │
│ │ - Model name from the code in props[0] (5 → "EPICP") │ │
│ │ - Plane stress, 1D: solves the stress-free components │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ smart2ansys_M() (fea_transfer.hpp) │ │
│ │ - Converts sigma, Lt → stress, dsdePl arrays │ │
│ │ - Remaps Voigt indices back to Ansys convention │ │
│ │ - Writes Wm, the stress-free strain, the law │ │
│ └─────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Ansys MAPDL │
│ (continues with updated stress/tangent) │
└───────────────────────────────────────────────────────────────┘
Voigt Notation
simcoon and Abaqus use the same Voigt notation, but Ansys differs in the shear component ordering:
Index |
Component |
simcoon / Abaqus |
Ansys |
|---|---|---|---|
0 |
Normal 11 |
\(\sigma_{11}, \varepsilon_{11}\) |
\(\sigma_{11}, \varepsilon_{11}\) |
1 |
Normal 22 |
\(\sigma_{22}, \varepsilon_{22}\) |
\(\sigma_{22}, \varepsilon_{22}\) |
2 |
Normal 33 |
\(\sigma_{33}, \varepsilon_{33}\) |
\(\sigma_{33}, \varepsilon_{33}\) |
3 |
Shear 12 |
\(\sigma_{12}, \gamma_{12}\) |
\(\sigma_{12}, \gamma_{12}\) |
4 |
Shear 13/23 |
\(\sigma_{13}, \gamma_{13}\) |
\(\sigma_{23}, \gamma_{23}\) |
5 |
Shear 23/13 |
\(\sigma_{23}, \gamma_{23}\) |
\(\sigma_{13}, \gamma_{13}\) |
The usermat_singleM.cpp bridge automatically swaps indices 4 and 5 during conversion.
State Variables Layout
Same as Abaqus - simcoon uses a specific layout for state variables:
ustatev[0:3] - Work quantities (Wm, Wm_r, Wm_ir, Wm_d)
ustatev[4:4+nC] - Stress-free strain components (plane stress, 1D)
ustatev[4+nC:nStatev-1] - Model-specific state variables
The energy outputs sedEl and sedPl, which Ansys uses for output only, get the
recoverable work Wm_r and the non-recoverable one Wm_ir + Wm_d.
Set the number of state variables in MAPDL with TB,STATE,mat_id,,nstatev, with
nstatev = nstatev_smart + 4 + nC: nC = 0 in 3D, plane strain and axisymmetry, 3 in
plane stress (33, 13, 23), 5 in 1D. The material point solves those components so that
their stress vanishes, around the 3D law, and keeps them to start the next increment from
them; dsdePl is the tangent condensed on the element’s components. Other layouts
(beams, nDirect = 1 with shears) are refused.
What happens when the USERMAT fails
As for Abaqus (Abaqus Integration), the bridge never lets a C++ error reach Ansys. It
prints the cause, prefixed by simcoon USERMAT:, and then:
the increment is too large (a trial state the model cannot handle): it sets
keycut = 1and Ansys bisects the substep (message ending withcutback requested);the input is wrong (an unknown model code in
props[0], aTB,STATEcount below4 + nC, an unsupported element layout): the job stops at once (message ending withthe analysis stops); fix the input and resubmit.
Thermomechanical coupling
The Ansys bridge is mechanical only. The heat a simcoon law produces, \(r = \Delta\gamma_{loc} - \theta\,\Delta\eta\) with its exact derivatives, is not passed to Ansys: USERMAT has no documented way to return a heat source.
Warning
Do not use MP,QRATE with a simcoon material. QRATE converts a fixed fraction
\(\beta\) of the plastic work \(\boldsymbol{\sigma}:\dot{\boldsymbol{\varepsilon}}^p\)
into heat (a Taylor-Quinney coefficient). That heats the stored part of the work
(Wm_ir) as well as the dissipated one (Wm_d), and ignores the thermoelastic
coupling. The bridge leaves epsPl at zero on purpose, so a QRATE heating built on
it stays zero; do not fill it in to “restore” that heating.
For a coupled thermomechanical analysis, use the Abaqus thermomechanical bridge
(umat_singleT.cpp, which returns RPL, DRPLDE and DRPLDT, see Abaqus Integration) or
the simcoon solver with thermomechanical blocks (Use the solver).
Limitations and Workarounds
Based on MFront’s experience with Ansys:
No external state variables: Temperature must be passed through material properties if needed beyond the standard interface.
No non-zero initial state variables: If your model requires non-zero initial values, consider:
Initializing in the first increment based on material properties
Using a separate initialization step
Limited time step control: Unlike Abaqus where
pnewdtsets the ratio of the next step, Ansys USERMAT only requests a cutback (keycut = 1). Use sufficiently small increments for nonlinear problems.Modelling hypothesis ambiguity: Plane strain and axisymmetric cases have identical tensor dimensions. If your model treats them differently, consider using a material property flag to distinguish them.
Troubleshooting
Compilation errors
# Check include paths
ls $SIMCOON_DIR/include/simcoon/
# Check library exists
ls $SIMCOON_DIR/lib/libsimcoon.*
Runtime library errors
# Check library path
echo $LD_LIBRARY_PATH
echo $ANS_USER_PATH
# Check dependencies of your USERMAT
ldd libusermat_simcoon.so
# Look for missing libraries
ldd libusermat_simcoon.so | grep "not found"
Symbol not found errors
# Verify usermat_ symbol is exported
nm -D libusermat_simcoon.so | grep usermat_
# Should show: T usermat_
Convergence issues
Check that
TB,STATEcount matchesnstatev_smart + 4 + nCVerify material properties are in correct units
Start with small load increments
The first property must be the model code
References
Ansys MAPDL User Material Subroutine Guide
Belytschko, T. Nonlinear Finite Elements for Continua and Structures. Wiley, 2000.