Migrating from v2.0.0 to v2.1.0

Table of Contents

• Input file changes
  • New top-level sections
  • Migration to EquationSystems (NonlinearSystem)
  • Nonlinear solvers now reference a linear solver
  • Optional scheduler hookup in drivers
  • Settings defaults/keys changed
• Binary utility changes
• Installation and integration changes
  • Build system and configuration
  • Installation layout/components
  • Integration options
  • Python packaging

Input file changes

New top-level sections

• [Schedulers] is now a recognized top-level section.
• [EquationSystems] is now a recognized top-level section.

Migration to EquationSystems (NonlinearSystem)

The biggest implicit-model migration is that nonlinear systems are now first-class objects under [EquationSystems].

In v2.0.0, ImplicitUpdate referenced a model directly:

[Models]
  [model]
    type = ImplicitUpdate
    implicit_model = 'system'
    solver = 'newton'
  []
[]

In v2.1.0, define the nonlinear system explicitly and reference it from ImplicitUpdate:

[EquationSystems]
  [eq_sys]
    type = NonlinearSystem
    model = 'system'
  []
[]
 
[Models]
  [model]
    type = ImplicitUpdate
    equation_system = 'eq_sys'
    solver = 'newton'
  []
[]

So the migration is:

• implicit_model (on ImplicitUpdate) -> move that model reference into a dedicated [EquationSystems] block.
• ImplicitUpdate now points to equation_system.

type = NonlinearSystem currently resolves to the model-backed nonlinear system implementation (ModelNonlinearSystem), which interprets:

• input state as unknowns,
• output residual as residual equations,
• (residual, state) derivatives as the Jacobian.

Nonlinear solvers now reference a linear solver

In v2.1.0, nonlinear solvers own a linear solver and require linear_solver in their options.

[Solvers]
  [newton]
    type = Newton
    abs_tol = 1e-10
    rel_tol = 1e-8
    max_its = 50
    linear_solver = 'lu'
  []
  [lu]
    type = DenseLU
  []
[]

This new linear_solver link controls how each nonlinear iteration solves the linearized system, which was previously internal to the nonlinear solver implementation.

Optional scheduler hookup in drivers

When work dispatching is enabled, drivers can now reference schedulers directly:

• scheduler = <name under [Schedulers]>
• async_dispatch = true|false

Settings defaults/keys changed

[Settings] changed substantially:

• buffer_name_separator default changed from "." to "_".
• parameter_name_separator default changed from "." to "_".
• New options:
  • require_double_precision
  • additional_libraries
  • disable_jit
• Removed from [Settings] input options:
  • default_floating_point_type
  • default_integer_type
  • default_device
  • machine_precision
  • tolerance
  • tighter_tolerance
  • interop_threads
  • intraop_threads

Binary utility changes

runner was replaced by dedicated tools.

v2.0.0 command	v2.1.0 replacement
runner input.i driver	neml2-run input.i driver
runner input.i driver --diagnose	neml2-diagnose input.i --driver driver
runner input.i driver --time	neml2-time input.i driver

Additional tool in v2.1.0:

• neml2-inspect input.i model

Other utility tools:

• neml2-syntax

Python package CLI wrappers now expose:

• neml2-run
• neml2-diagnose
• neml2-time
• neml2-inspect
• neml2-syntax
• neml2-stub

Installation and integration changes

Build system and configuration

• CMake minimum changed from 3.28 to 3.26.
• cmake-variants.yaml workflow was replaced by CMakePresets.json.
• Main build toggle rename:
  • NEML2_RUNNER -> NEML2_TOOLS
• New commonly used toggles:
  • NEML2_WORK_DISPATCHER
  • NEML2_JSON
  • NEML2_CSV
• Legacy toggles no longer used as before:
  • NEML2_PYBIND
  • NEML2_DOC
  • NEML2_CLANG_TIDY / NEML2_CLANG_TIDY_PATH

Installation layout/components

• Installable components are now separated:
  • libneml2: core libraries and headers
  • libneml2-bin: utility binaries
• Benchmarks used by tools are installed under share/neml2/benchmark.

Integration options

• pkg-config integration is now supported.
  • Package file name is config-dependent:
    • Release: neml2.pc
    • Other build types: neml2_<CONFIG>.pc (for example neml2_Debug.pc)
• CMake config-package integration is available via:
  • find_package(neml2 CONFIG)
  • link target neml2::neml2

Python packaging

• Python build backend moved from setuptools+custom setup.py flow to scikit-build-core.
• CLI wrappers are declared in pyproject.toml.
• The neml2-stub helper remains available for local source installs.