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.

Developer source build (only when contributing to the bundled C++ AOTI runtime):

git clone -b main https://github.com/applied-material-modeling/neml2.git
cd neml2
pip install -e ".[dev]"

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}
}

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.0.7)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for reverend_bedford from gravatar.com reverend_bedford

Credits

Author: Mark Messner

Requires

Python >=3.10

Provides Extra

dev

Report project as malware

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.6.tar.gz (3.5 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.6-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

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

neml2-3.0.6-cp314-cp314-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

neml2-3.0.6-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

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

neml2-3.0.6-cp313-cp313-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

neml2-3.0.6-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

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

neml2-3.0.6-cp312-cp312-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

neml2-3.0.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

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

neml2-3.0.6-cp311-cp311-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

neml2-3.0.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (1.5 MB view details)

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

neml2-3.0.6-cp310-cp310-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

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

File metadata

  • Download URL: neml2-3.0.6.tar.gz
  • Upload date:
  • Size: 3.5 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.6.tar.gz
Algorithm Hash digest
SHA256 03376c346a2e6f36728327b15df74fe0d6558c0985bdd9f8b28d40ec1b3b7590
MD5 e7293b1a389ade8a55f76bcab346a7ad
BLAKE2b-256 7655ccf82961d5fc2cc8efa90bab51d4ec85b83ce7e44fda8ac23069dc41cc3b

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6.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.6-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cdd2444b201dffc6ce342bcdfbeb645b572ffb456ebf4647f463d53acae5753a
MD5 fb237f2e552776f73df17556bf1ed372
BLAKE2b-256 e7ca03a50ee0757e0a4222997971bf44a2540c924b531e4b7ea459db5291f2ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f08a410715fd81c99b2bd100eeb87bb5f5dd805557890beee43dd48939343660
MD5 c30fc4f6321257a539f3c790f8c031f9
BLAKE2b-256 ee701922ebedcf231b1366948da90ed75498b6cee76e9f8ca5f0ed3dd6d2f0ec

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7c74b6d8a55b3b6b8cc9b16062725266e7eba815ce27d106ffebec52e19b6ec0
MD5 d807b89ba21a76261a7dc1e946ca5772
BLAKE2b-256 aa0207448392f1cd4b1db269166530f3b3929c7d678f94a619b111fc3b0e5ae1

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 20fd4be86636e4ba2fad9b77ee99e6b77c48bc16d2aa046b7af8ddd832ca272e
MD5 187d7add4b0ba5122fb2175cf942a01a
BLAKE2b-256 5ea1d58cf4451f3683152407abdd63f33fae5d35dcd714ef1bc3997453cd414f

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 22c0f593076d5625cf42aea2c269cb3afb4e9281b3f416ce0b25bbd63ffd48cf
MD5 ce43e5b0a0d8da5b3b88a28f1ec63775
BLAKE2b-256 5819838380bf69bea0877b104bd2bba065fbfce10fea18e0fcdfe42c2b1bce86

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b52a5ffcff384457fbeb417aefdd0ccc70c8836d8be0ec655366c79203417500
MD5 1266596032cb88c63c3fa9fe43fdd6fb
BLAKE2b-256 465b8bf2b2d96060a3f5bf74018ee6cf5b3b6396173f025b2878ad3a3a83de56

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6e8d5678b83c9cdb9e2e52e409dfa56f2121d2251c0be35069ea8c31d3197a52
MD5 6e3e43a300c03c6cb1f6ee6d6c7b7b94
BLAKE2b-256 b44062f87813f8841be39bb7b6d39612bece1c19541065a84818b11b7fb87cd6

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 14cb1c0ece66ee580a2391da7e6996ebaad6685604bce4d43bd18cc716a1697b
MD5 a0ae6a1f8ea116bddbee4bf73c6c04da
BLAKE2b-256 e184ada30a7e361f753cefbd0da5a4f8fa89f9f4d63c6b7f66fa1ada56d852ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d59825c37d97e594ff11b9234a327fb77bef3fd354a675b1556ad0a652017053
MD5 95382c1e635169cded3460127f573c05
BLAKE2b-256 d598dca06969e14eb5263a6fdae3c125dcc79a55396af2ef56b64dac27bce6f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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.6-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for neml2-3.0.6-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 32d5acc7d326161b158b7e0078447c9311da2add684186468c91842008f034f4
MD5 c6523b3edc17173ba70a9758f73c850f
BLAKE2b-256 97e8f66e66c9704fa7ecffaddcd824623857648ba81e708bb153074fb44ebc96

See more details on using hashes here.

Provenance

The following attestation bundles were made for neml2-3.0.6-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