Consistent initialization

A DAE solve starts from a state that satisfies its algebraic equations. See consistent initialization.

diff_soup.problem.implicit.consistent_init.consistent_initial_state

consistent_initial_state(problem, t0, y0, theta, control=None, *, ydot0=None, plan=None, init_plan: Optional[ConsistentInitPlan] = None, tol: float = 1e-12, max_iters: int = 30, chord_iters: int = 8, backend='auto', analysis=None, route: str = 'auto') -> ConsistentInitResult

Solve for a consistent initial state of a DAE at t0.

It holds the differential values of y0 and solves for the algebraic values and the differential slopes with Newton's method. The result is differentiable with respect to y0 and theta.

Parameters:

Name	Type	Description	Default
problem		The problem from spec.build(), or a MassProblem or ImplicitProblem.	required
t0		The initial time.	required
y0		The initial state, whose algebraic entries are the starting guess.	required
theta		The parameters, or None for the problem's defaults.	required
control		The control values, or None.	None
ydot0		A guess for the slopes, zeros by default.	None
plan		A prebuilt linearization plan, or None to build one.	None
init_plan	Optional[ConsistentInitPlan]	A prebuilt ConsistentInitPlan, which overrides every setting below it.	None
tol	float	The residual 2-norm at which Newton's method stops.	1e-12
max_iters	int	The total Newton iteration budget.	30
chord_iters	int	The first iterations, which reuse one factorization before each later iteration refactors.	8
backend		The linear backend, a name as on linear= or a ds.linear object.	'auto'
analysis		A prebuilt linear analysis of the Newton matrix, or None.	None
route	str	"reduced" solves the algebraic block alone and needs a diagonal mass, "joint" the full system, and "auto" picks.	'auto'

Returns:

Type	Description
ConsistentInitResult	A ConsistentInitResult.

diff_soup.problem.implicit.consistent_init.check_consistent_init

check_consistent_init(problem, t0, y0, theta, control=None, *, ydot0=None, plan=None, init_plan: Optional[ConsistentInitPlan] = None, tol: float = 1e-12, max_iters: int = 30) -> ConsistentInitResult

Solve for a consistent initial state, and raise with a diagnosis when there is none.

It runs the joint route with a dense linear solve and then checks the rank of the joint matrix at the result. It runs on concrete arrays, outside jax.jit.

Parameters:

Name	Type	Description	Default
problem		The problem from spec.build(), or a MassProblem or ImplicitProblem.	required
t0		The initial time.	required
y0		The initial state, whose algebraic entries are the starting guess.	required
theta		The parameters, or None for the problem's defaults.	required
control		The control values, or None.	None
ydot0		A guess for the slopes, zeros by default.	None
plan		A prebuilt linearization plan, or None to build one.	None
init_plan	Optional[ConsistentInitPlan]	A prebuilt ConsistentInitPlan, which overrides every setting below it.	None
tol	float	The residual 2-norm at which Newton's method stops.	1e-12
max_iters	int	The total Newton iteration budget.	30

Returns:

Type	Description
ConsistentInitResult	A converged ConsistentInitResult.

Raises:

Type	Description
ValueError	When the joint matrix is singular, naming the unknowns and rows involved, or when Newton's method does not converge.

diff_soup.problem.implicit.consistent_init.ConsistentInitResult

The result of a consistent initialization.

Attributes:

Name	Type	Description
y	Array	The consistent state.
ydot	Array	The consistent derivative, zero on algebraic rows.
residual_norm	Array	The residual 2-norm at y and ydot.
iterations	Array	The Newton iterations used.
converged	Array	Whether residual_norm reached tol.

---

Algebraic projection

project_algebraic solves the algebraic entries of a state assembled or edited outside a solve.

diff_soup.project_algebraic

project_algebraic(problem, *, t, state, seed, state_dot=None, theta=None, control=None, options: Optional[AlgebraicProjectionOptions] = None) -> AlgebraicProjectionResult

Solve the algebraic entries of a state at one time, keeping its differential entries fixed.

Use it on a state assembled or edited outside a solve. The result is differentiable in t, state, state_dot, theta and control, and its derivative in seed is zero.

Parameters:

Name	Type	Description	Default
problem		A MassProblem, an ImplicitProblem, or a problem with a solver_problem() method such as a LoweredProblem.	required
t		Time at which the residual is evaluated.	required
state		Full state vector, fields then globals, whose differential entries are kept.	required
seed		Full vector whose algebraic entries start the Newton iteration, with its other entries ignored.	required
state_dot		Full time derivative, required for an ImplicitProblem or when an algebraic row reads a derivative, zero otherwise.	None
theta		Parameters, or None for the problem's default_theta().	None
control		Control values or an operating ControlState, as in a solve.	None
options	Optional[AlgebraicProjectionOptions]	Solver settings, or None for the defaults of AlgebraicProjectionOptions.	None

Returns:

Type	Description
AlgebraicProjectionResult	An AlgebraicProjectionResult.

Raises:

Type	Description
ConfigurationError	If a vector has the wrong length, or state_dot is missing where it is required.

diff_soup.AlgebraicProjectionOptions dataclass

Settings of the Newton solve in project_algebraic.

Every field is checked on construction, and an out-of-range value raises ValueError.

Attributes:

Name	Type	Description
rtol	float	Relative tolerance of the convergence test, positive.
atol	float	Absolute tolerance of the convergence test, positive.
max_steps	int	Maximum number of Newton iterations, at least 1.
linear_solver	str	Linear solver of each Newton step, one of "auto", "dense", "klu", "superlu", "cudss".
ad_mode	str	"forward" differentiates in forward and reverse mode, "reverse" in reverse mode only.

diff_soup.AlgebraicProjectionResult

Result of project_algebraic.

A failed projection does not raise. Branch on status in traced code, or call require_success() on a concrete result, which raises AlgebraicProjectionError on failure.

Attributes:

Name	Type	Description
state	Array	Full state with the differential entries kept and the algebraic entries solved.
status	Array	Integer AlgebraicProjectionStatus code.
iterations	Array	Number of Newton iterations taken.
residual_norm	Array	Norm of the final Newton residual.

diff_soup.AlgebraicProjectionStatus

Outcome code of project_algebraic, one per state when batched with vmap.

Attributes:

Name	Type	Description
SUCCESS		The Newton iteration converged.
MAX_ITERATIONS		The iteration did not converge within max_steps.
SINGULAR_JACOBIAN		The inputs were finite but the solve produced a non-finite value.
NONFINITE		The time, the kept state entries, the algebraic seed, or state_dot was non-finite.

diff_soup.AlgebraicProjectionError

Raised by AlgebraicProjectionResult.require_success() when a projection did not succeed.

Attributes:

Name	Type	Description
status		The AlgebraicProjectionStatus codes, as a NumPy array.
iterations		Newton iterations taken, as a NumPy array.
residual_norm		Final residual norm, as a NumPy array.