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.5.tar.gz (2.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.5-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.5-cp314-cp314-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

neml2-3.0.5-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.5-cp313-cp313-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

neml2-3.0.5-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.5-cp312-cp312-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

neml2-3.0.5-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.5-cp311-cp311-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

neml2-3.0.5-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.5-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.5.tar.gz.

File metadata

  • Download URL: neml2-3.0.5.tar.gz
  • Upload date:
  • Size: 2.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.5.tar.gz
Algorithm Hash digest
SHA256 c904e528710c9f158827e3b13c79c52e4850c3c2077151ee878f7516e98d1564
MD5 c8135aeda33fd80c4a5b9d2ebb34b04a
BLAKE2b-256 f6488f82fe461dc588f348dae5e677b73288e558332f8731a6af54a4f42ce868

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6d8f362e1fe4d4edc73dbc62633bc4e9c1adecc9bd592790d633af0c67edbaea
MD5 ead541602f66deec5499c525a17378aa
BLAKE2b-256 c8688c1353c8fa96261853f14e06a10035c8e1f4f649550befb836651cd33110

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1b47000669a45b50dca152abc19464883dfd1d2761714debc3b8aa21ca681e64
MD5 6558a0595d2f35cf9f17f0688d6b92d9
BLAKE2b-256 7404d84c92bf7d756c4148a4ff1fdec1b8b2c63a2e9a43da4d58aa4bd92a24d9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bd6de39bc96af85252f12195bebc247225b47b34adcf1a7766d0aa95ed6f3a87
MD5 f97bd2219e0d4d5f78829e72e8c09e1a
BLAKE2b-256 ef2d68b4d4b06e9088293e89e3fa69b19cb8e0ad487f6a71dd4823e09cdcde32

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b36fec57cdc48100089ea0e4ddd7fb408f23a85b4576ac390536d23d3ea1eb4b
MD5 fa656ca67ca28b68638e5963c877ba5a
BLAKE2b-256 b933ae6267e7432ceb035eec86d94a6518fe36f9ec5a2c9ca9274d7789774e03

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a4271d0d71a4fa98ad83ecdbe0c99f69a172861687f066ba9e3012008af14967
MD5 13fbee2621799c18cad492153fe5b634
BLAKE2b-256 b554a12367ab49e87e8e03fe2549372910bfec99ba48782c7b39ea4b1d75132c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 416bc6f4002be1fa1fe513633ffb357e48570d8fdf4de9ed0bc81348308b581f
MD5 c55bd55a3062f538b87b7a32750bdc19
BLAKE2b-256 345d395d831c658f4bbe7213419c64f4f66ab4294ffe16fd7519708e17b1da77

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 714481dd3e07e65f5e2461db5dca07b300feb3295c9fb40032338001cb1128d6
MD5 2931c21d0196deaf88f319aa7c00407b
BLAKE2b-256 8fc30ea67cbca72ef9832795731553e1902067ade595e80f54b6aee39cac69d6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7559eebbc17f6864699864081a3638ae87ced1ef3dce1decd31d67924db3a28a
MD5 c4c598dfbb3eab71af4e75d1d830ab5d
BLAKE2b-256 25557c2958fb9f2ebf79ca551a638a07b90593680f56e21a7729b2f2b911f371

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e55480adb75a53a96032742e776573a36bee04c8b170894087b7c17f3682316f
MD5 25ccf60e2c70b0aa0277f00d8c102558
BLAKE2b-256 5c0a2a587b5c87a453c001f006ba514b94df0ac12784e13caa583b34171e9c6f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.5-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8609010fec32758b505933778b77b2511033749c73e694962ec8ac7052c6ded1
MD5 d07f80accec9dd454836405e0d81c1d9
BLAKE2b-256 a4b0970f7c82149660119dd48328647140d7f29a1cca4e19f3e37e5822c99ce3

See more details on using hashes here.

Provenance

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