diff --git a/src/SciMLBase.jl b/src/SciMLBase.jl index 96ec757a2..1ab2a0173 100644 --- a/src/SciMLBase.jl +++ b/src/SciMLBase.jl @@ -345,17 +345,78 @@ $(TYPEDEF) abstract type DAEInitializationAlgorithm <: AbstractSciMLAlgorithm end """ -$(TYPEDEF) + struct NoInit <: DAEInitializationAlgorithm + +An initialization algorithm that completely skips the initialization phase. The solver +will use the provided initial conditions directly without any consistency checks or +modifications. + +⚠️ **Warning**: Using `NoInit()` with inconsistent initial conditions will likely cause +solver failures or incorrect results. Only use this when you are absolutely certain +your initial conditions satisfy all DAE constraints. + +This is useful when: +- You know your initial conditions are already perfectly consistent +- You want to avoid the computational cost of initialization +- You are debugging solver issues and want to isolate initialization from integration + +## Example +```julia +prob = DAEProblem(f, du0_consistent, u0_consistent, tspan) +sol = solve(prob, IDA(), initializealg = NoInit()) +``` """ struct NoInit <: DAEInitializationAlgorithm end """ -$(TYPEDEF) + struct CheckInit <: DAEInitializationAlgorithm + +An initialization algorithm that only checks if the initial conditions are consistent +with the DAE constraints, without attempting to modify them. If the conditions are not +consistent within the solver's tolerance, an error will be thrown. + +This is useful when: +- You have already computed consistent initial conditions +- You want to verify the consistency of your initial guess +- You want to ensure no automatic modifications are made to your initial conditions + +## Example +```julia +prob = DAEProblem(f, du0, u0, tspan) +sol = solve(prob, IDA(), initializealg = CheckInit()) +``` """ struct CheckInit <: DAEInitializationAlgorithm end """ -$(TYPEDEF) + struct OverrideInit <: DAEInitializationAlgorithm + +An initialization algorithm that uses a separate initialization problem to find +consistent initial conditions. This is typically used with ModelingToolkit.jl +which can generate specialized initialization problems based on the model structure. + +When using `OverrideInit`, the problem must have `initialization_data` that contains +an `initializeprob` field with the initialization problem to solve. + +This algorithm is particularly useful for: +- High-index DAEs that have been index-reduced +- Systems with complex initialization requirements +- ModelingToolkit models with custom initialization equations + +## Fields +- `abstol`: Absolute tolerance for the initialization solver +- `reltol`: Relative tolerance for the initialization solver +- `nlsolve`: Nonlinear solver to use for initialization + +## Example +```julia +# Typically used automatically with ModelingToolkit +@named sys = ODESystem(eqs, t, vars, params) +sys = structural_simplify(sys) +prob = DAEProblem(sys, [], (0.0, 1.0), []) +# Will automatically use OverrideInit if initialization_data exists +sol = solve(prob, IDA()) +``` """ struct OverrideInit{T1, T2, F} <: DAEInitializationAlgorithm abstol::T1