Logo Logo

Documentation C++ backend testing Python package testing codecov PyPI

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.4.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.4-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.4-cp314-cp314-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

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

Uploaded CPython 3.13macOS 11.0+ ARM64

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

Uploaded CPython 3.12macOS 11.0+ ARM64

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

Uploaded CPython 3.11macOS 11.0+ ARM64

neml2-3.0.4-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.4-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.4.tar.gz.

File metadata

  • Download URL: neml2-3.0.4.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.4.tar.gz
Algorithm Hash digest
SHA256 de9acd661bed5caff835f5591eee091b1503aea3c0e9ed1aeed7e0228c76e377
MD5 66fbf8515877cf27c5ebe8e454fc14f4
BLAKE2b-256 c6735f2a331ed4baeb075258f1c060e15dcd7cd8e681fca6e00a2b3cb9c9cf49

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 47fdf2b32c51d413701fd2e7c6456179e16df236c28035e47d848ffbc524ce8d
MD5 214af6c00547fc26e50633f77a503938
BLAKE2b-256 405f88ef233fb6664faa21e7a533fc072b5a18db2aae1c02a717cbd232d93d92

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 00df4a77649f382664ea3172563e1885053673cdccc4784b9ef44154d1445d10
MD5 cef95462f867c6cdb3c65f59643c2bfa
BLAKE2b-256 1e625b52bde79ff960b0750899f611d4b1b9bc5b879d8bbd793e457449ba4e51

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 639359c8c850c76d6883967b9d48293f44a78341d403aebac5cb4c03140a47fc
MD5 4baec8f0c2bf544f61cae6d8f94c2f79
BLAKE2b-256 4bb4056f3aac36c043d9b73252f715688e4a31fbaea63572a32703e7294e5005

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a1d1d3aaecfb6029553ce43367cfe2222995174ffd23b71fc3015ec98102fa85
MD5 f08a7f20e76e34d599f30a909795c50a
BLAKE2b-256 aaaec8f8d1437c8d564be83a7758d433a0e540e3b96dca4ce858e14508a7549b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f66940bced1d421bc277f137bea4d2ae1a5aafde641687d67dfed0c073aafb68
MD5 2118d3fc9cddcd21d587ffce8780f375
BLAKE2b-256 8331f636ec9a06ff0a0e8ac86505d277c4389c415f816bf5fa4c0ea7261435c9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4971891ec8e4c787a253356ce594df390f870cb5d6325daf2cc48990633ea5df
MD5 4395e222fcf114439f504662231dd8aa
BLAKE2b-256 7d49690b38e766ca9253db1b7f11a8a9e8ead90afcfd076bc0d7925ffd437284

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 31b728311ee1b8a7a68acc29b75493e91235cff8fe781691aba4eb1bba198d1d
MD5 30afcc7fa3210b5b1aea82b014f5b93c
BLAKE2b-256 bfb5e33bd966f394563478f61e23363640bff2dd14210782f92825c3f3f6cb36

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5a040a2ae4b9861b00d75c9cf29160338aed7bff9a57ef62178e55e691fc6251
MD5 bd173983410dcd5788bedcfed2bcf940
BLAKE2b-256 0f30b9eb522df1f7c65c12da5ef94f301c06e8fea9312003cced71b8d469c4ed

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 77cdf5736b3f6c78752cfae1444ac2eed81645dca3f00d5a365f11cc85a8ca1a
MD5 cba7810a50bce9851a5f0986e04cff0c
BLAKE2b-256 8708d88b2f9084dadd1a89b4069841a04f69c07826dfd46bb740788de27920b8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for neml2-3.0.4-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7e6ddd6be033436a74832cc8bc5c18a3e1d8fbadf57d8efbfa163bcbfe3f0f7e
MD5 a649d388269684e2e8a5f2f974b27d0d
BLAKE2b-256 4688b796a317222bf0590d88978919fcec61c27218d77f7714e88ea170252a32

See more details on using hashes here.

Provenance

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