Installation Guide

Table of Contents

• Prerequisites
• Dependencies
  • Required dependencies
  • Optional dependencies
• Build and install
  • C++ backend
  • Python package
• Build customization
• CMake integration
• Testing
  • C++ backend
  • Python package

Prerequisites

Compiling the NEML2 core library requires

• A C++ compiler with C++17 support
• CMake >= 3.28

Dependencies

Required dependencies

• PyTorch, version 2.2.2.

Other PyTorch releases with a few minor versions around are likely to be compatible. In the PyTorch official download page, several download options are provided: conda, pip, libTorch, and source distribution.

• Recommended: If you choose to download PyTorch using conda or pip, the NEML2 CMake script can automatically detect and use the PyTorch installation.
• If you choose to download libTorch or build PyTorch from source, you will need to set LIBTORCH_DIR to be the location of libTorch when using CMake to configure NEML2.

Note

The libTorch distributions from the official website come with two flavors: "Pre-cxx11 ABI" and "cxx11 ABI". Both variants are supported by NEML2. If you are unsure, we recommend the one with "cxx11 ABI".

If no PyTorch installation can be detected and LIBTORCH_DIR is not set at configure time, the NEML2 CMake script will automatically download and use the libTorch obtained from the official website. Note, however, that this method only works on Linux and Mac systems.

Optional dependencies

Note

No action is needed to manually obtain the optional dependencies. The compatible optional dependencies will be automatically downloaded and configured by CMake depending on the build customization.

• HIT for input file parsing.
• WASP as the lexing and parsing backend for HIT.
• Catch2 for unit and regression testing.
• gperftools for profiling.
• Doxygen for building the documentation.
• Doxygen Awesome the documentation theme.
• argparse for command-line argument parsing.
• pybind11 for building Python bindings.
• Python packages
  • pytest for testing Pythin bindings
  • PyYAML for extracting syntax documentation
  • pybind11-stubgen for extracting stubs from Python bindings

Build and install

Note

NEML2 is available both as a C++ library and as a Python package. Instructions for building and installing each variant are provided below. If you only need one of them, the other can be skipped.

C++ backend

First, obtain the NEML2 source code.

git clone https://github.com/reverendbedford/neml2.git
cd neml2
git checkout main

Then, configure NEML2. See build customization for possible configuration options.

cmake -B build .

Finally, compile NEML2.

cmake --build build -j N

where N is the number of cores to use for parallel compilation.

The compiled NEML2 can be installed as a system library.

cmake --install build

For more fine-grained control over the configure, build, and install commands, please refer to the CMake documentation.

Python package

NEML2 also provides an experimental Python package which provides bindings for the primitive tensors and parsers for deserializing and running material models. Package source distributions are available on PyPI, but package wheels are currently not built and uploaded to PyPI.

To install the NEML2 Python package, run the following command at the repository's root. Note that unlike the C++ backend, we do not expose any interface for customizing the build. The default configuration is already optimized for building the Python package.

pip install -v .

The command installs a package named neml2 to the site-packages directory, and so it can be imported in Python scripts using

import neml2

For security reasons, static analysis tools and IDEs for Python usually refuse to extract function signature, type hints, etc. from binary extensions such as the NEML2 Python bindings. As a workaround, NEML2 automatically generates "stubs" using pybind11-stubgen immediately after Python bindings are built to make them less opaque. Refer to the pybind11-stubgen documentation for more information.

Build customization

Additional configuration options can be passed via command line using the -DOPTION or -DOPTION=ON format. For example,

cmake -DNEML2_PYBIND=ON -B build .

turns on the NEML2_PYBIND option, and additional targets for building the Python bindings will be created. Note that this would also download additional optional dependencies, e.g., pybind11, that are required to build the Python bindings.

Commonly used configuration options are summarized below. Default options are underlined.

Option	Values (default)	Description
CMAKE_BUILD_TYPE	Debug, Release, MinSizeRel, RelWithDebInfo, Coverage	CMake Reference
CMAKE_INSTALL_PREFIX		CMake Reference
CMAKE_UNITY_BUILD		CMake Reference
NEML2_TESTS	ON, OFF	Master knob for including/excluding all tests
NEML2_UNIT	ON, OFF	Create the unit testing target
NEML2_REGRESSION	ON, OFF	Create the regression testing target
NEML2_VERIFICATION	ON, OFF	Create the verification testing target
NEML2_RUNNER	ON, OFF	Create a simple runner
NEML2_RUNNER_AS_PROFILER	ON, OFF	Make the runner a profiler by linking against gperftools
NEML2_DOC	ON, OFF	Create the documentation target
NEML2_PYBIND	ON, OFF	Create the Python bindings target
NEML2_CLANG_TIDY	ON, OFF	Run clang-tidy linting diagnostics
NEML2_CLANG_TIDY_PATH	"clang-tidy"	Path to clang-tidy executable

Visual Studio Code users are encouraged to use the predefined CMake variants in cmake-variants.yaml to configure the build.

CMake integration

Integrating NEML2 into a project that already uses CMake is fairly straightforward. The following CMakeLists.txt snippet links NEML2 into the target executable called foo:

add_subdirectory(neml2)
 
add_executable(foo main.cxx)
target_link_libraries(foo neml2)

The above snippet assumes NEML2 is checked out to the directory neml2, i.e., as a git submodule. Alternatively, you may use CMake's FetchContent module to integrate NEML2 into your project:

FetchContent_Declare(
  neml2
  GIT_REPOSITORY https://github.com/reverendbedford/neml2.git
  GIT_TAG v1.4.0
)
FetchContent_MakeAvailable(neml2)
 
add_executable(foo main.cxx)
target_link_libraries(foo neml2)

Testing

C++ backend

By default when NEML2_TESTS is set to ON, three test suites are built under the specified build directory:

• tests/unit/unit_tests: Collection of tests to ensure individual objects are working correctly.
• tests/regression/regression_tests: Collection of tests to avoid regression.
• tests/verification/verification_tests: Collection of verification problems.

The tests assume the working directory to be the tests directory relative to the repository root. For Visual Studio Code users, the C++ TestMate extension can be used to automatically discover and run tests. In the extension settings, the "Working Directory" variable should be modified to ${workspaceFolder}/tests. The settings.json file shall contain the following entry:

{
  "testMate.cpp.test.workingDirectory": "${workspaceFolder}/tests",
}

Python package

A collection of tests are available under python/tests to ensure the NEML2 Python package is working correctly. For Visual Studio Code users, the Python extension can be used to automatically discover and run tests. In the extension settings, the "Pytest Enabled" variable shall be set to true. In addition, "pytestArgs" shall provide the location of tests, i.e. "${workspaceFolder}/python/tests". The settings.json file shall contain the following entries:

{
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": [
    "${workspaceFolder}/python/tests"
  ],
}

If the Python bindings are built (with NEML2_PYBIND set to ON) but are not installed to the site-packages directory, pytest will not be able to import the neml2 package unless the environment variable PYTHONPATH is modified according to the specified build directory. For Visual Studio Code users, create a .env file in the repository's root and include an entry PYTHONPATH=build/python (assuming the build directory is build), and the Python extension will be able to import the NEML2 Python package.