A Chrono YAML MBS solver file defines the parameters needed to run a Chrono simulation. It consists of the following main objects:

[required] The Chrono version (chrono-version) that is compatible with the YAML model specification. This is a string of the form M.m (major.minor) or M.m.p (major-minor-patch), although only the two fields are verified for compatibility.
[required] The contact_method specifying the formulation for contact force generation.
[optional] The integrator object specifying the type and settings for the time integrator. If omitted, an EULER_IMPLICIT_LINEARIZED integrator with a time step of 1e-3 is used.
[optional] The solver object specifying the type and settings for the (linear or DVI) solver. If omitted, a BARZILAI_BORWEIN solver with default settings is used.

Note that a solver file specifies neither output nor run-time visualization settings; those belong in the MBS simulation file.

Contact formulation

Property	Description	Type	Available Values	Required	Default
`contact_method`	Contact method for collision detection and response	string	`SMC`,`NSC`	Yes	–

Integrator types and parameters

Each integrator can support the following settings depending on the integrator type:

Property	Description	Type	Available Values	Required	Default
`type`	Integrator type	enum	`EULER_IMPLICIT_LINEARIZED`, `EULER_IMPLICIT_PROJECTED`, `EULER_IMPLICIT`, `HHT`	Yes	–
`rel_tolerance`	Relative tolerance (HHT and implicit Euler)	double	–	No	1e-4
`time_step`	Integration timestep in seconds	double	–	Yes	–

Both type and time_step are required if the integrator object is present. | abs_tolerance_states | Absolute tolerance for state variables (HHT and implicit Euler) | double | – | No | 1e-4 | | abs_tolerance_multipliers | Absolute tolerance for Lagrange multipliers (HHT and implicit Euler) | double | – | No | 1e2 | | max_iterations | Maximum number of non-linear iterations for implicit integrators | integer | – | No | 50 | | use_stepsize_control | Whether to use internal step-size control (HHT) | boolean | – | No | false | | use_modified_newton | Whether to use a modified Newton iteration (HHT) | boolean | – | No | false |

Solver types and parameters

Each solver supports different configuration parameters depending on the solver type:

Property	Description	Type	Available Values	Required	Default
`type`	(DVI or linear) solver type	enum	`BARZILAI_BORWEIN`, `PSOR`, `APGD`, `MINRES`, `GMRES`, `BICGSTAB`, `PARDISO`, `MUMPS`, `SPARSE_LU`, `SPARSE_QR`	Yes	–

type is required if the solver object is present. The PARDISO and MUMPS solvers require the corresponding optional Chrono module to be enabled.

Iterative DVI Solvers (BARZILAI_BORWEIN, APGD, PSOR)

Property	Description	Type	Available Values	Required	Default
`max_iterations`	Maximum number of iterations	integer	–	No	100
`overrelaxation_factor`	Overrelaxation factor for improved convergence	double	–	No	1.0
`sharpness_factor`	Sharpness factor for solver response tuning	double	–	No	1.0
`enable_diagonal_preconditioner`	Enable diagonal preconditioner to accelerate convergence	boolean	–	No	false
`warm_start`	Warm start the solver from the previous solution	boolean	–	No	false

Iterative Krylov Linear Solvers (BICGSTAB, MINRES, GMRES)

Property	Description	Type	Available Values	Required	Default
`max_iterations`	Maximum number of iterations	integer	–	No	100
`tolerance`	Residual tolerance for convergence	double	–	No	0.0
`enable_diagonal_preconditioner`	Enable diagonal preconditioner to accelerate convergence	boolean	–	No	false
`warm_start`	Warm start the solver from the previous solution	boolean	–	No	false

Direct Sparse Linear Solvers (SPARSE_LU, SPARSE_QR, PARDISO, MUMPS)

Property	Description	Type	Available Values	Required	Default
`lock_sparsity_pattern`	Keep matrix sparsity pattern unchanged	boolean	–	No	false
`use_sparsity_pattern_learner`	Evaluate matrix sparsity pattern in a pre-processing stage (for `SPARSE_LU` and `SPARSE_QR` only)	boolean	–	No	true

Example

Below is an example of an MBS solver configuration:

chrono-version: 10.0
 
contact_method: SMC
  
integrator:
  type: Euler_implicit_linearized
  time_step: 1e-4
 
solver:
  type: Barzilai_Borwein
  max_iterations: 100
  overrelaxation_factor: 1.0
  sharpness_factor: 1.0

YAML schema

The YAML MBS solver specification file must follow the data/yaml/schema/mbs_solver.schema.yaml provided in the Chrono data directory:

# =============================================================================
# PROJECT CHRONO - http://projectchrono.org
#
# Copyright (c) 2025 projectchrono.org
# All rights reserved.
#
# Use of this source code is governed by a BSD-style license that can be found
# in the LICENSE file at the top level of the distribution and at
# http://projectchrono.org/license-chrono.txt.
# =============================================================================
#
# Schema for a Chrono YAML MBS solver specification file.
# The `chrono-version` must match the Chrono major and minor version numbers.
#
# =============================================================================
 
required: [chrono-version, contact_method]
 
chrono-version:
  type: string
  description: Chrono version compatible with this YAML specification (M.m or M.m.p)
 
contact_method:
  type: string
  description: Contact method for collision detection and response
  enum: [SMC, NSC]
 
integrator:
  type: object
  description: |
    Integrator type and parameters.
    If this object is omitted, an EULER_IMPLICIT_LINEARIZED integrator with a time step of 1e-3 is used.
  required: [type, time_step]
  properties:
      type:
          type: string
          description: Type of numerical integrator.
          enum: [EULER_IMPLICIT_LINEARIZED, EULER_IMPLICIT_PROJECTED, EULER_IMPLICIT, HHT]
      time_step:
          type: number
          description: Time step size in seconds.
          minimum: 0
      rel_tolerance:
          type: number
          description: Relative tolerance (HHT and implicit Euler)
          minimum: 0
          default: 1e-4
      abs_tolerance_states:
          type: number
          description: Absolute tolerance for state variables (HHT and implicit Euler)
          minimum: 0
          default: 1e-4
      abs_tolerance_multipliers:
          type: number
          description: Absolute tolerance for Lagrange multipliers (HHT and implicit Euler)
          minimum: 0
          default: 1e2
      max_iterations:
          type: number
          description: Maximum number of non-linear iteration for implicit integrators
          minimum: 0
          default: 50
      use_stepsize_control:
          type: boolean
          description: Whether to use internal step-size control (HHT)
          default: false
      use_modified_newton:
          type: boolean
          description: Whether to use a modified Newton iteration (HHT)
          default: false
    
solver:
  type: object
  description: |
    Solver type and parameters.
    If this object is omitted, a BARZILAI_BORWEIN solver with default settings is used.
  required: [type]
  properties:
      type:
          type: string
          description: Type of linear solver
          enum: [BARZILAI_BORWEIN, PSOR, APGD, MINRES, GMRES, BICGSTAB, PARDISO, MUMPS, SPARSE_LU, SPARSE_QR]
      max_iterations:
          type: number
          description: Maximum number of iteration for iterative DVI and linear solvers
          minimum: 0
          default: 100
      overrelaxation_factor:
          type: number
          description: Overrelaxation factor for iterative DVI solvers
          minimum: 0
          default: 1.0
      sharpness_factor:
          type: number
          description: Sharpness factor for iterative DVI solvers
          minimum: 0
          default: 1.0
      tolerance:
          type: number
          description: Tolerance for iterative Krylov linear solvers
          minimum: 0
          default: 0.0
      enable_diagonal_preconditioner:
          type: boolean
          description: Whether to use a diagonal preconditioner (iterative DVI and Krylov linear solvers)
          default: false
      warm_start:
          type: boolean
          description: Whether to warm start the solver from the previous solution (iterative DVI and Krylov linear solvers)
          default: false
      lock_sparsity_pattern:
          type: boolean
          description: Keep matrix sparsity pattern unchanged (direct sparse linear solvers, including PARDISO and MUMPS)
          default: false
      use_sparsity_pattern_learner:
          type: boolean
          description: Evaluate matrix sparsity pattern in a pre-processing stage (SPARSE_LU and SPARSE_QR only)
          default: true
  