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 dsdePl as \(\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 (the rotateM slot 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 numerically

  • State 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

Ansys 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:

Voigt Index Comparison

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 = 1 and Ansys bisects the substep (message ending with cutback requested);

  • the input is wrong (an unknown model code in props[0], a TB,STATE count below 4 + nC, an unsupported element layout): the job stops at once (message ending with the 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:

  1. No external state variables: Temperature must be passed through material properties if needed beyond the standard interface.

  2. 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

  3. Limited time step control: Unlike Abaqus where pnewdt sets the ratio of the next step, Ansys USERMAT only requests a cutback (keycut = 1). Use sufficiently small increments for nonlinear problems.

  4. 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,STATE count matches nstatev_smart + 4 + nC

  • Verify material properties are in correct units

  • Start with small load increments

  • The first property must be the model code

References