Skip to content

Commit 776a23d

Browse files
Add comprehensive docstrings for DAE initialization algorithms
- Document NoInit with strong warnings about usage risks - Document CheckInit as the verification-only algorithm - Document OverrideInit for ModelingToolkit integration - Include examples and use cases for each algorithm - Add field documentation for OverrideInit
1 parent 16de2a7 commit 776a23d

File tree

1 file changed

+64
-3
lines changed

1 file changed

+64
-3
lines changed

src/SciMLBase.jl

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -345,17 +345,78 @@ $(TYPEDEF)
345345
abstract type DAEInitializationAlgorithm <: AbstractSciMLAlgorithm end
346346

347347
"""
348-
$(TYPEDEF)
348+
struct NoInit <: DAEInitializationAlgorithm
349+
350+
An initialization algorithm that completely skips the initialization phase. The solver
351+
will use the provided initial conditions directly without any consistency checks or
352+
modifications.
353+
354+
⚠️ **Warning**: Using `NoInit()` with inconsistent initial conditions will likely cause
355+
solver failures or incorrect results. Only use this when you are absolutely certain
356+
your initial conditions satisfy all DAE constraints.
357+
358+
This is useful when:
359+
- You know your initial conditions are already perfectly consistent
360+
- You want to avoid the computational cost of initialization
361+
- You are debugging solver issues and want to isolate initialization from integration
362+
363+
## Example
364+
```julia
365+
prob = DAEProblem(f, du0_consistent, u0_consistent, tspan)
366+
sol = solve(prob, IDA(), initializealg = NoInit())
367+
```
349368
"""
350369
struct NoInit <: DAEInitializationAlgorithm end
351370

352371
"""
353-
$(TYPEDEF)
372+
struct CheckInit <: DAEInitializationAlgorithm
373+
374+
An initialization algorithm that only checks if the initial conditions are consistent
375+
with the DAE constraints, without attempting to modify them. If the conditions are not
376+
consistent within the solver's tolerance, an error will be thrown.
377+
378+
This is useful when:
379+
- You have already computed consistent initial conditions
380+
- You want to verify the consistency of your initial guess
381+
- You want to ensure no automatic modifications are made to your initial conditions
382+
383+
## Example
384+
```julia
385+
prob = DAEProblem(f, du0, u0, tspan)
386+
sol = solve(prob, IDA(), initializealg = CheckInit())
387+
```
354388
"""
355389
struct CheckInit <: DAEInitializationAlgorithm end
356390

357391
"""
358-
$(TYPEDEF)
392+
struct OverrideInit <: DAEInitializationAlgorithm
393+
394+
An initialization algorithm that uses a separate initialization problem to find
395+
consistent initial conditions. This is typically used with ModelingToolkit.jl
396+
which can generate specialized initialization problems based on the model structure.
397+
398+
When using `OverrideInit`, the problem must have `initialization_data` that contains
399+
an `initializeprob` field with the initialization problem to solve.
400+
401+
This algorithm is particularly useful for:
402+
- High-index DAEs that have been index-reduced
403+
- Systems with complex initialization requirements
404+
- ModelingToolkit models with custom initialization equations
405+
406+
## Fields
407+
- `abstol`: Absolute tolerance for the initialization solver
408+
- `reltol`: Relative tolerance for the initialization solver
409+
- `nlsolve`: Nonlinear solver to use for initialization
410+
411+
## Example
412+
```julia
413+
# Typically used automatically with ModelingToolkit
414+
@named sys = ODESystem(eqs, t, vars, params)
415+
sys = structural_simplify(sys)
416+
prob = DAEProblem(sys, [], (0.0, 1.0), [])
417+
# Will automatically use OverrideInit if initialization_data exists
418+
sol = solve(prob, IDA())
419+
```
359420
"""
360421
struct OverrideInit{T1, T2, F} <: DAEInitializationAlgorithm
361422
abstol::T1

0 commit comments

Comments
 (0)