GitHub

API Reference

Linear-System Core

LinearSystem{T}

Mutable container for linear solves:

  • A::SparseMatrixCSC{T,Int}
  • b::Vector{T}
  • x::Vector{T}
  • cache
  • last_dt::Union{Nothing,T}

Constructors:

LinearSystem(A::SparseMatrixCSC{T,Int}, b::Vector{T}; x=nothing)
LinearSystem{T}(n::Int)

Assembly hooks:

assemble!(sys::LinearSystem, model, t, dt)
assemble_matrix!(sys::LinearSystem, model, t, dt, θ)
assemble_rhs!(sys::LinearSystem, model, uⁿ, t, dt, θ)

Solver entrypoints:

solve!(sys::LinearSystem; method::Symbol = :direct, reuse_factorization::Bool = true, kwargs...)
theta_step!(sys::LinearSystem, model, uⁿ, t, dt, θ; method=:direct, reuse_factorization=true, kwargs...)

Generic Block Coupling

Public Types

AbstractCouplingMode
OneWayCoupling(order)
TwoWayCoupling(order; maxiter, atol, rtol, relaxation, norm_fields, sweep, verbose)
CoupledBlock(name, model, state; cache=nothing, metadata=Dict())
CoupledBlock(name, model; init=nothing, cache=nothing, metadata=Dict())
CouplingMap(from, to, field; apply! = identity)
CoupledProblem(blocks, coupling_mode; maps=CouplingMap[])

Public Coupled Solve Entrypoints

solve_coupled!(problem::CoupledProblem; return_history=false, store_history=false, kwargs...)
step_coupled!(problem::CoupledProblem, t, dt; return_history=false, store_history=false, kwargs...)

Behavior:

  • OneWayCoupling: single ordered pass, with map transfers after each block solve.
  • TwoWayCoupling: outer Picard loop with residual convergence checks and optional per-block under-relaxation.

If return_history=true, both functions return (problem, history) where history is a CouplingHistory record of outer-iteration residuals.

Extension Hooks for Physics Packages

Implement these methods for your block/model types:

initialize_state(model, init)
advance_steady!(block::CoupledBlock; kwargs...)
advance_unsteady!(block::CoupledBlock, t, dt; kwargs...)
get_coupling_field(block::CoupledBlock, ::Val{field}) where field
set_coupling_field!(block::CoupledBlock, ::Val{field}, data) where field
copy_state(state)
coupling_residual(old_block::CoupledBlock, new_block::CoupledBlock, fields)
block_summary(block::CoupledBlock)

Fallback definitions throw MethodError so missing extensions are explicit.

Coupling History

CouplingHistory stores:

  • iterations::Vector{Int}
  • residuals::Vector{Float64}
  • block_residuals::Vector{Dict{Symbol,Float64}}

TwoWayCoupling convergence uses absolute and relative criteria:

global_residual <= atol + rtol * baseline

where baseline is the first outer residual.

Canonical Docstrings

PenguinSolverCore.OneWayCoupling — Type
OneWayCoupling(order)

Sequential, one-pass block orchestration. Blocks are advanced once in order without outer fixed-point iterations.

PenguinSolverCore.TwoWayCoupling — Type
TwoWayCoupling(order; maxiter, atol, rtol, relaxation, norm_fields, sweep, verbose)

Outer Picard fixed-point coupling with optional per-block under-relaxation.

PenguinSolverCore.CoupledBlock — Type
CoupledBlock(name, model, state; cache=nothing, metadata=Dict())
CoupledBlock(name, model; init=nothing, cache=nothing, metadata=Dict())

Container for one independently solvable block in a coupled orchestration.

PenguinSolverCore.CouplingMap — Type
CouplingMap(from, to, field; apply!=identity)

Directed coupling transfer from from block to to block for one named field. apply! can transform data before injection.

PenguinSolverCore.CoupledProblem — Type
CoupledProblem(blocks, coupling_mode; maps=CouplingMap[])

Bundle of coupled blocks, orchestration mode, and directed coupling maps.

PenguinSolverCore.initialize_state — Function
initialize_state(model, init)

Initialize a block state from a model and optional init payload. Physics packages should overload this when constructing CoupledBlock without an explicit state argument.

PenguinSolverCore.coupling_residual — Function
coupling_residual(old_block::CoupledBlock, new_block::CoupledBlock, fields)

Optional custom residual hook for outer coupling convergence checks.

PenguinSolverCore.solve_coupled! — Function
solve_coupled!(problem::CoupledProblem; return_history=false, store_history=false, kwargs...)

Run coupled steady orchestration.

  • OneWayCoupling: one ordered pass.
  • TwoWayCoupling: outer Picard iteration.
PenguinSolverCore.step_coupled! — Function
step_coupled!(problem::CoupledProblem, t, dt; return_history=false, store_history=false, kwargs...)

Run one coupled unsteady step.

  • OneWayCoupling: one ordered pass.
  • TwoWayCoupling: outer Picard iteration at (t, dt).
PenguinSolverCore.apply_coupling_maps! — Function
apply_coupling_maps!(problem; from=nothing, to=nothing)

Apply all coupling maps in problem, optionally filtered by source/target block name.