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: Built-in Jaumann framework for rate-form behaviours
No time step control: Cannot request smaller time steps from within USERMAT
State variable initialization: Cannot set non-zero initial values
Model selection: Uses numeric model code in props[0] instead of material name
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)
TB,STATE,1,,12
Model Codes
Code |
Name |
Model |
Additional Properties |
|---|---|---|---|
2 |
ELISO |
Isotropic elasticity |
E, ν, α |
3 |
ELIST |
Transversely isotropic elasticity |
E₁, E₂, ν₁₂, ν₂₃, G₁₂, α₁, α₂ |
4 |
ELORT |
Orthotropic elasticity |
E₁, E₂, E₃, ν₁₂, ν₁₃, ν₂₃, G₁₂, G₁₃, G₂₃, α₁, α₂, α₃ |
5 |
EPICP |
Isotropic plasticity (isotropic hardening) |
E, ν, α, σ_y, H |
6 |
EPKCP |
Kinematic + isotropic hardening |
E, ν, α, σ_y, H, C, γ |
7 |
EPCHA |
Chaboche cyclic plasticity |
E, ν, α, σ_y, Q, b, C₁, γ₁, … |
8 |
SMAUT |
SMA unified model |
See SMA documentation |
10 |
LLDM0 |
Lemaitre-Chaboche damage |
E, ν, α, σ_y, H, S, s, D_c |
11 |
ZENER |
Zener viscoelastic (single branch) |
E₀, E₁, η |
12 |
ZENNK |
Zener viscoelastic (N branches) |
E₀, E₁, η₁, E₂, η₂, … |
13 |
PRONK |
Prony series viscoelastic |
G₀, K₀, g₁, τ₁, k₁, τ’₁, … |
17 |
EPHIL |
Hill anisotropic plasticity |
E, ν, α, σ_y, H, F, G, H, L, M, N |
18 |
EPHAC |
Hill + Chaboche |
E, ν, α, σ_y, Q, b, C₁, γ₁, F, G, H, L, M, N |
How It Works
Architecture
┌───────────────────────────────────────────────────────────────┐
│ Ansys MAPDL │
│ │ │
│ ▼ │
│ calls extern "C" usermat_() │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ usermat_singleM.cpp (bridge) │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ ansys2smart_M() │ │
│ │ - Converts stress, dsdePl, strain, dstrain → Armadillo │ │
│ │ - Remaps Voigt indices (swaps 4 ↔ 5 for 3D) │ │
│ │ - Extracts model code from props[0] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ select_umat_M(rve, ...) │ │
│ │ - Looks up model name from code (e.g., 5 → "EPICP") │ │
│ │ - Dispatches to appropriate model │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ smart2ansys_M() │ │
│ │ - Converts sigma, Lt → stress, dsdePl arrays │ │
│ │ - Remaps Voigt indices back to Ansys convention │ │
│ └─────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 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 |
σ₁₁, ε₁₁ |
σ₁₁, ε₁₁ |
1 |
Normal 22 |
σ₂₂, ε₂₂ |
σ₂₂, ε₂₂ |
2 |
Normal 33 |
σ₃₃, ε₃₃ |
σ₃₃, ε₃₃ |
3 |
Shear 12 |
σ₁₂, γ₁₂ |
σ₁₂, γ₁₂ |
4 |
Shear 13/23 |
σ₁₃, γ₁₃ |
σ₂₃, γ₂₃ |
5 |
Shear 23/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:nStatev-1] - Model-specific state variables
Set the number of state variables in MAPDL with TB,STATE,mat_id,,nstatev.
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
No time step control: Unlike Abaqus where
pnewdtcan request smaller steps, Ansys USERMAT cannot control the time step. 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 + 4Verify 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.