//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../../_part_attributes.asciidoc[]

:leveloffset: -2

[[tools-cifsim-solver-chapter-options-root]]
== ODE solver root finder options

indexterm:[ODE,root finder options]
indexterm:[root finder options]
The <<tools-cifsim-solver-chapter-basics-root,root finder>> used by the ODE solver of the CIF simulator, can be configured using several options.

indexterm:[root finder options,maximum check interval]

[[tools-cifsim-solver-options-root-maxcheck]]
=== Maximum check interval

The _ODE solver root finder maximum check interval_ option (_ODE solver: ODE root finder_ category) is explained on a separate page.
See <<tools-cifsim-solver-chapter-root-problems>>.

indexterm:[root finder options,algorithm]
indexterm:[root finder options,Regula Falsi]
indexterm:[root finder options,false position]
indexterm:[root finder options,Illinois]
indexterm:[root finder options,Pegasus]

[[tools-cifsim-solver-options-root-algo]]
=== Root finding algorithm

The _ODE solver root finding algorithm_ option (_ODE solver: ODE root finder_ category) can be used to configure the root finding algorithm to use.
The following algorithms are available:

* Regula Falsi (link:https://en.wikipedia.org/wiki/False_position_method[False position]) method

* Illinois method

* Pegasus method (default)

The _Illinois_ and _Pegasus_ methods are modified _Regula Falsi_ methods.
The algorithms differ only in how they choose the middle point of the interval.
This influences their convergence speed.
The _Regula Falsi_ method in particular should be avoided in practice.

indexterm:[root finder options,tolerances]

[[tools-cifsim-solver-options-root-tol]]
=== Absolute and relative tolerance

The _ODE solver root finder absolute tolerance_ option (_ODE solver: ODE root finder_ category) and the _ODE solver root finder relative tolerance_ option (_ODE solver: ODE root finder_ category), can be used to configure how precise the results of the root finder should be.
The lower the tolerance (or error), the higher the precision of the results, but also the more computing time it costs to get to that precision.
The absolute precision is the difference between the prediction and the actual value, while the relative precision is that same difference, as a fraction of the actual value.
In the latter case, precision reduces with increasing values.

indexterm:[root finder options,maximum iterations]

[[tools-cifsim-solver-options-root-maxiter]]
=== Maximum iterations

The _ODE solver root finder maximum iterations_ option (_ODE solver: ODE root finder_ category) can be used to set the maximum number of iterations to use for root finding.
This value must be at least one.
If the root interval is larger than the tolerances allow, after the maximum number of iterations, root finding fails.

If it fails for your CIF specification, increase the value of this option.
If that does not help, your specification is most likely too complex (by nature), or has a modeling error that causes the specification to become too complex for the root finding algorithm to handle.
The problem however, may also be in one of the other root finder options, or in one of the <<tools-cifsim-solver-chapter-options,integrator options>>.
