Skip to main content
Logo Logo

Documentation C++ backend testing Python package testing codecov PyPI

docs - stable docs - dev

Overview

The New Engineering Material model Library, version 2

NEML2 is an offshoot of NEML, an earlier material modeling code developed at Argonne National Laboratory. Like its predecessor, NEML2 provides a flexible, modular way to build material models from smaller blocks. Unlike its predecessor, NEML2 vectorizes the material update on CPU and GPU using PyTorch as the tensor backend, with first-class support for automatic differentiation, operator fusion, lazy tensor evaluation, and inference mode.

NEML2 is provided as open source software under a MIT license.

Disclaimer

NEML2 is not a database of material models. There are many example material models in the library for testing and verification purposes. These models do not represent the response of any actual material.

Quick installation

Python package (recommended): Pre-built wheels are available on PyPI:

pip install neml2

The wheel ships everything a C++ consumer needs too — libneml2.so, the public headers, and the CMake config files all land under your site-packages/neml2/. See the installation guide for finer control over the torch variant (CPU / CUDA / ROCm) and the C++ integration guide for find_package(neml2) wiring.

Once NEML2 is installed, the deployment overview walks through the different ways to evaluate a model, and the tutorials cover the commonly used APIs.

Features and design philosophy

Vectorization

NEML2 models can be vectorized, meaning that a large batch of material models can be evaluated simultaneously. The vectorized models can be evaluated on either CPUs or GPUs/other accelerators. Moreover, NEML2 provides a unified implementation and user interface, for both developers and end users, that work on all supported devices.

The table below compares three approaches for solving the same problem: a crystal plasticity simulation using the Taylor method, with 50,000 grains and 250 load steps. The first approach is using NEML (the predecessor of NEML2) which is a CPU-only, fully threaded library. The second and the third approaches use NEML2, evaluating the same model on CPU and GPU (CUDA), respectively.

Device Wall time (s) Specs
NEML CPU 42,500 Intel Xeon Gold 6346 CPU with 32 threads
NEML2 CPU 15,000 Intel Xeon Gold 6346 CPU with 32 threads
NEML2 GPU 68 1 NVIDIA RTX A5000 GPUs
34 2 NVIDIA RTX A5000 GPUs

NEML2 is more than 2x faster than NEML on CPU, owing to more comprehensive threading and vectorization, and (for compiled workloads) AOT-Inductor codegen via neml2-compile. In this case, GPUs further speed up the calculation by more than 400 times.

Multiphysics coupling

NEML2 is not tied to any underlying problem physics. Current modules cover solid mechanics (including crystal plasticity), chemical reactions, phase-field fracture, porous flow, finite volume, and KWN-style precipitation kinetics, and the framework is set up to take on more. For coupled problems, NEML2 assembles the full Jacobian (via chain rule across composed models, or via automatic differentiation), which is what implicit solvers need to converge robustly. NEML2 can be used together with MOOSE, a Multiphysics finite element framework, to solve partial differential equations.

Modularity and flexibility

NEML2 material models are modular – they are built up from smaller pieces into a complete model. Each individual model only defines the forward operator (and optionally its derivative) with a given set of inputs and outputs. Users control how those models are composed and wired together; NEML2 detects the dependencies and resolves the evaluation order automatically.

Extensibility

Adding a new model usually means writing a small forward operator and (optionally) its partial derivatives. NEML2 composes these into the full Jacobian via chain rule across composed models, and falls back to automatic differentiation for any derivative you don't provide — so you can start with a minimal implementation and add hand-coded derivatives later for speed.

Friendly user interfaces

NEML2 is used from Python (the primary API), through the bundled CLI tools (neml2-run, neml2-inspect, neml2-syntax, neml2-compile), or from C++ via the AOTI runtime bundled in the wheel. In every interface, models are described by input files in the hierarchical HIT format. NEML2 models created in Python are fully interoperable with PyTorch tensors and modules, so they slot into PyTorch-based machine learning workflows directly.

Testing

NEML2 is verification-tested at three layers: unit tests for individual model leaves, regression tests that pin each scenario's output to a checked-in reference, and verification tests that compare against analytical or benchmark ground truth. The example models shipped in the library are for testing — they are not parameterized for any real material, so the project does not claim experimental validation.

Citing NEML2

@article{neml2_softwarex_2025,
  title = {NEML2: An efficient and modular multiphysics constitutive modeling library for hybrid computing environments},
  journal = {SoftwareX},
  volume = {31},
  pages = {102302},
  year = {2025},
  issn = {2352-7110},
  doi = {https://doi.org/10.1016/j.softx.2025.102302},
  url = {https://www.sciencedirect.com/science/article/pii/S2352711025002687},
  author = {Tianchen Hu and Mark C. Messner},
  keywords = {Constitutive model, GPU, Multiphysics}
}
@techreport{neml2osti2440430,
  author      = {Tianchen Hu and Mark C.  Messner and Daniel Schwen and Lynn B.  Munday and Dewen Yushu},
  title       = {NEML2: A High Performance Library for Constitutive Modeling},
  institution = {Argonne National Laboratory (ANL), Argonne, IL (United States); Idaho National Laboratory (INL), Idaho Falls, ID (United States)},
  doi         = {10.2172/2440430},
  url         = {https://www.osti.gov/biblio/2440430},
  place       = {United States},
  year        = {2024},
  month       = {09}
}
@misc{neml2osti1961125,
  author = {MESSNER, MARK and HU, TIANCHEN and US DOE NE-NEAMS},
  title  = {NEML2 - THE NEW ENGINEERING MATERIAL MODEL LIBRARY, VERSION 2},
  doi    = {10.11578/dc.20230314.1},
  url    = {https://www.osti.gov/biblio/1961125},
  place  = {United States},
  year   = {2023},
  month  = {01}
}

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neml2-3.0.7.tar.gz (3.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

neml2-3.0.7-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

neml2-3.0.7-cp314-cp314-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

neml2-3.0.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

neml2-3.0.7-cp313-cp313-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

neml2-3.0.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

neml2-3.0.7-cp312-cp312-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

neml2-3.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

neml2-3.0.7-cp311-cp311-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

neml2-3.0.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

neml2-3.0.7-cp310-cp310-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file neml2-3.0.7.tar.gz.

File metadata

  • Download URL: neml2-3.0.7.tar.gz
  • Upload date:
  • Size: 3.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for neml2-3.0.7.tar.gz
Algorithm Hash digest
SHA256 0c71ecd3ffeaae95acc78f9d46e39fa8d5b295c56937108317ef4b7042355160
MD5 1d998a1bb1730e504c0e5bffc272f66a
BLAKE2b-256 0902945a21351084d02336170e102bf06412078d1c876e20eba889795cc759ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7.tar.gz:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 74e674316dc1ede2615daeec70392dcfd5a87d8911146c082e0910b435349bba
MD5 e3238e6f9311eb056059371bc5a50575
BLAKE2b-256 1f6b9fc7605c56145ff72f92e4b978a727c1c28d6701b6362af6c6981557066f

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3a00820ab82d1b2c9998c4e75f9e8d7e956f018680cbe6f3b07378f6a23f7914
MD5 36338567f95ba2a719f22b9c9c2f3799
BLAKE2b-256 2eece571e362d945ccbaaa0c24cdd47534cb45fca5760c58b30a1ea4edf2c096

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 444ef4b4233c6c870e50b009f594356b9fe7c1c7c12b6d7a5130aca23e03a3a2
MD5 bc5111a69a86c6d074d970e09a4f4521
BLAKE2b-256 77637931ecb2920cf57b1459c31701f4d4e2306f797f95b54aa401680b48a82d

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 97e7b28a587da6496acf32bbab9a0b8b1cf10404744b523bbc8370e479c4d3fd
MD5 9f67be59cf61c692243946d1563ddfa6
BLAKE2b-256 2cc81ec702cabe2096983fa9351351ee29c78a94642081006942031aa80934b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5117e45e3e212d0a3b6166f3c88a8a03dc680113e7e37b6d84603127ab113b0c
MD5 ea483ad705ade7797c952adc425ad32e
BLAKE2b-256 7044307fa4bb7c7ee678c074cd4c47561287be1b11a05adf59b0d65d0de7d82b

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f579abb94f827f88ea5c183b8263c7b533548a41d477d730f70a918311c86fec
MD5 f14f993c0822dc541d92c64c3c0b7268
BLAKE2b-256 0c27e5bc3a4e9d2b0921111d43f7e0776e5bed1ae907c3aad38186c5a1d4b986

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 91878049a5dac1f6cd347327a56e658c1f6cb2a711d1bca720525bc0287f0446
MD5 a2c4070d3a0ab69a8e0b32142b9297d1
BLAKE2b-256 dbdcd32dd1c561ca93d9ea1d741c1b1bb8612fda5727cc4243a092b89b0f4b7d

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2d08699d24e8a842e203edbd17e1a571871ff04840f67ff9c73e59558929d755
MD5 76849274d345c3fec34fd4648caaa122
BLAKE2b-256 19731d0dbfd439efaa5bf2d135bc8a8fed00dc8dddd9296cf2223ee4e3ea262a

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bb22e1e01cfbb8ce8492797d6442275e02158b1781fc38ae0376427434c9f176
MD5 c9202fd70cd5256cda785f16e68ff1f8
BLAKE2b-256 4599342c359b185179044c3cecf2512c88084c076756961776ebcaec27aed70c

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file neml2-3.0.7-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.7-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 16db100a2af65c70476ef266e161c29440bafec1134ccbb47b794ede56754d58
MD5 fcb1214261dbc66d1f75572d3c7518ef
BLAKE2b-256 3f797acf2d53e5766afb3e1d6128d55acd39ab7c1a61708b86ddd25a972cfe69

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.7-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: python.yaml on applied-material-modeling/neml2

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page