TS (Time Stepping) - Low-level Interface

The TS (Time Stepping) component provides methods for solving time-dependent differential equations, including ordinary differential equations (ODEs), differential-algebraic equations (DAEs), and time-dependent partial differential equations (PDEs).

Overview

TS supports various time integration methods including:

Explicit methods: Forward Euler, Runge-Kutta methods (RK2, RK3, RK4, etc.)
Implicit methods: Backward Euler, Crank-Nicolson, BDF methods
IMEX methods: Implicit-Explicit combinations for stiff-nonstiff problems
Adaptive methods: Adaptive time stepping with error control
Specialized methods: Theta methods, Rosenbrock methods, SSP methods

The TS object manages the time integration loop, adaptive time stepping, event detection, and provides interfaces to various time stepping schemes.

Basic Usage

using PETSc, MPI

# Initialize MPI and PETSc
MPI.Init()
petsclib = PETSc.getlib()
PETSc.initialize(petsclib)

# Create a TS object
ts = LibPETSc.TSCreate(petsclib, LibPETSc.PETSC_COMM_SELF)

# Set the problem type (ODE or DAE)
LibPETSc.TSSetProblemType(petsclib, ts, LibPETSc.TS_NONLINEAR)

# Set the time stepping method (e.g., BDF, RK, Theta)
LibPETSc.TSSetType(petsclib, ts, "bdf")

# Set time span
LibPETSc.TSSetTime(petsclib, ts, 0.0)  # Initial time
LibPETSc.TSSetMaxTime(petsclib, ts, 1.0)  # Final time
LibPETSc.TSSetExactFinalTime(petsclib, ts, LibPETSc.TS_EXACTFINALTIME_STEPOVER)

# Set initial time step
LibPETSc.TSSetTimeStep(petsclib, ts, 0.01)

# Set the right-hand side function (for ODE: du/dt = f(t,u))
# LibPETSc.TSSetRHSFunction(petsclib, ts, C_NULL, rhs_function_ptr, C_NULL)

# Set options from command line/options database
LibPETSc.TSSetFromOptions(petsclib, ts)

# Set initial condition
# LibPETSc.TSSetSolution(petsclib, ts, initial_vec)

# Solve
# LibPETSc.TSSolve(petsclib, ts, solution_vec)

# Get solution time (returns value directly)
final_time = LibPETSc.TSGetSolveTime(petsclib, ts)

# Cleanup
LibPETSc.TSDestroy(petsclib, ts)

# Finalize PETSc and MPI
PETSc.finalize(petsclib)
MPI.Finalize()

Common Workflow

Create and configure TS: Use TSCreate, TSSetType, TSSetProblemType
Set time parameters: TSSetTime, TSSetMaxTime, TSSetTimeStep, TSSetMaxSteps
Define equations: TSSetRHSFunction, TSSetIFunction, TSSetIJacobian
Configure adaptivity: TSAdaptSetType, TSSetTolerances
Set initial condition: TSSetSolution
Solve: TSSolve
Retrieve solution: TSGetSolution, TSGetTime, TSGetStepNumber

Time Integration Schemes

Available through TSSetType:

TSEULER: Forward/Backward Euler
TSRK: Runge-Kutta methods (various orders)
TSBDF: Backward Differentiation Formulas
TSTHETA: Theta method (generalizes Euler, Crank-Nicolson)
TSROSW: Rosenbrock-W methods for stiff problems
TSARKIMEX: Additive Runge-Kutta IMEX methods
TSGLEE: Generalized Linear Evolution Equations
TSALPHA: Alpha methods for second-order systems
TSSSP: Strong Stability Preserving methods

Event Detection

TS supports event detection (zero-crossing of event functions) during time integration:

TSSetEventHandler: Configure events to detect
Events can trigger actions like termination, adaptation, or post-event processing

Adaptive Time Stepping

TS includes sophisticated adaptive time stepping:

TSAdaptChoose: Select time step based on error estimates
Various adapt types: TSADAPTBASIC, TSADAPTNONE, TSADAPTDSP
Tolerance control: TSSetTolerances for absolute/relative error

Function Reference

PETSc.LibPETSc.TS2GetSolution — Method

u::PetscVec,v::PetscVec = TS2GetSolution(petsclib::PetscLibType, ts::AbstractTS)

Returns the solution and time derivative at the present timestep for second order equations.

Not Collective

Input Parameter:

ts - the TS context obtained from TSCreate()

Output Parameters:

u - the vector containing the solution
v - the vector containing the time derivative

Level: intermediate

See also: TS, TS2SetSolution(), TSGetTimeStep(), TSGetTime()

External Links

PETSc Manual: TS/TS2GetSolution

source

PETSc.LibPETSc.TS2SetSolution — Method

TS2SetSolution(petsclib::PetscLibType, ts::AbstractTS, u::AbstractPetscVec, v::AbstractPetscVec)

Sets the initial solution and time derivative vectors for use by the TS routines handling second order equations.

Logically Collective

Input Parameters:

ts - the TS context obtained from TSCreate()
u - the solution vector
v - the time derivative vector

Level: beginner

See also: TS

External Links

PETSc Manual: TS/TS2SetSolution

source

PETSc.LibPETSc.TSARKIMEXFinalizePackage — Method

TSARKIMEXFinalizePackage(petsclib::PetscLibType)

This function destroys everything in the TSARKIMEX package. It is called from PetscFinalize().

Level: developer

See also: PetscFinalize(), TSARKIMEXInitializePackage()

External Links

PETSc Manual: TS/TSARKIMEXFinalizePackage

source

PETSc.LibPETSc.TSARKIMEXGetFastSlowSplit — Method

fastslow::PetscBool = TSARKIMEXGetFastSlowSplit(petsclib::PetscLibType, ts::AbstractTS)

Gets whether to use TSARKIMEX for a fast-slow system

Not Collective

Input Parameter:

ts - timestepping context

Output Parameter:

fastslow - PETSC_TRUE if TSARKIMEX will be used for solving a fast-slow system, PETSC_FALSE otherwise

Level: intermediate

See also: TSARKIMEX, TSARKIMEXSetFastSlowSplit()

External Links

PETSc Manual: TS/TSARKIMEXGetFastSlowSplit

source

PETSc.LibPETSc.TSARKIMEXGetFullyImplicit — Method

flg::PetscBool = TSARKIMEXGetFullyImplicit(petsclib::PetscLibType, ts::AbstractTS)

Inquires if both parts of the equation are solved implicitly

Logically Collective

Input Parameter:

ts - timestepping context

Output Parameter:

flg - PETSC_TRUE for fully implicit

Level: intermediate

See also: TSARKIMEXGetType(), TSARKIMEXSetFullyImplicit()

External Links

PETSc Manual: TS/TSARKIMEXGetFullyImplicit

source

PETSc.LibPETSc.TSARKIMEXGetType — Method

arktype::String = TSARKIMEXGetType(petsclib::PetscLibType, ts::AbstractTS)

Get the type of TSARKIMEX scheme

Logically Collective

Input Parameter:

ts - timestepping context

Output Parameter:

arktype - type of TSARKIMEX scheme

Level: intermediate

See also: TSSetIHessianProduct()

External Links

PETSc Manual: Sensitivity/TSComputeIHessianProductFunctionPP

source

PETSc.LibPETSc.TSComputeIHessianProductFunctionPU — Method

TSComputeIHessianProductFunctionPU(petsclib::PetscLibType, ts::AbstractTS, t::PetscReal, U::AbstractPetscVec, Vl::Vector{<:AbstractPetscVec}, Vr::AbstractPetscVec, VHV::Vector{<:AbstractPetscVec})

Runs the user-defined vector-Hessian-vector product function for Fpu.

Collective

Input Parameters:

ts - The TS context obtained from TSCreate()
t - the time
U - the solution at which to compute the Hessian product
Vl - the array of input vectors to be multiplied with the Hessian from the left
Vr - the input vector to be multiplied with the Hessian from the right

Output Parameter:

VHV - the array of output vectors that store the Hessian product

Level: developer

See also: TSSetIHessianProduct()

External Links

PETSc Manual: Sensitivity/TSComputeIHessianProductFunctionPU

source

PETSc.LibPETSc.TSComputeIHessianProductFunctionUP — Method

TSComputeIHessianProductFunctionUP(petsclib::PetscLibType, ts::AbstractTS, t::PetscReal, U::AbstractPetscVec, Vl::Vector{<:AbstractPetscVec}, Vr::AbstractPetscVec, VHV::Vector{<:AbstractPetscVec})

Runs the user-defined vector-Hessian-vector product function for Fup.

Collective

Input Parameters:

ts - The TS context obtained from TSCreate()
t - the time
U - the solution at which to compute the Hessian product
Vl - the array of input vectors to be multiplied with the Hessian from the left
Vr - the input vector to be multiplied with the Hessian from the right

Output Parameter:

VHV - the array of output vectors that store the Hessian product

Level: developer

See also: TSSetIHessianProduct()

External Links

PETSc Manual: Sensitivity/TSComputeIHessianProductFunctionUP

source

PETSc.LibPETSc.TSComputeIHessianProductFunctionUU — Method

TSComputeIHessianProductFunctionUU(petsclib::PetscLibType, ts::AbstractTS, t::PetscReal, U::AbstractPetscVec, Vl::Vector{<:AbstractPetscVec}, Vr::AbstractPetscVec, VHV::Vector{<:AbstractPetscVec})

Runs the user-defined vector-Hessian-vector product function for Fuu.

Collective

Input Parameters:

ts - The TS context obtained from TSCreate()
t - the time
U - the solution at which to compute the Hessian product
Vl - the array of input vectors to be multiplied with the Hessian from the left
Vr - the input vector to be multiplied with the Hessian from the right

Output Parameter:

VHV - the array of output vectors that store the Hessian product

Level: developer

See also: TSSetIHessianProduct()

External Links

PETSc Manual: Sensitivity/TSComputeIHessianProductFunctionUU

source

PETSc.LibPETSc.TSComputeIJacobian — Method

TSComputeIJacobian(petsclib::PetscLibType, ts::AbstractTS, t::PetscReal, U::AbstractPetscVec, Udot::AbstractPetscVec, shift::PetscReal, A::AbstractPetscMat, B::AbstractPetscMat, imex::PetscBool)

Evaluates the Jacobian of the DAE

Collective

Input Parameters:

ts - the TS context
t - current timestep
U - state vector
Udot - time derivative of state vector
shift - shift to apply, see note below
imex - flag indicates if the method is TSARKIMEX so that the RHSJacobian should be kept separate

Output Parameters:

A - Jacobian matrix
B - matrix from which the preconditioner is constructed; often the same as A

Level: developer

See also: TS

External Links

PETSc Manual: Sensitivity/TSForwardGetStages

source

PETSc.LibPETSc.TSForwardReset — Method

TSForwardReset(petsclib::PetscLibType, ts::AbstractTS)

Reset the internal data structures used by forward sensitivity analysis

Collective

Input Parameter:

ts - the TS context obtained from TSCreate()

Level: advanced

See also: TSCreate(), TSDestroy(), TSForwardSetUp()

External Links

PETSc Manual: Sensitivity/TSForwardReset

source

PETSc.LibPETSc.TSForwardSetInitialSensitivities — Method

TSForwardSetInitialSensitivities(petsclib::PetscLibType, ts::AbstractTS, didp::AbstractPetscMat)

Set initial values for tangent linear sensitivities

Collective

Input Parameters:

ts - the TS context obtained from TSCreate()
didp - parametric sensitivities of the initial condition

Level: intermediate

See also: TS, TSForwardSetSensitivities()

External Links

PETSc Manual: Sensitivity/TSForwardSetInitialSensitivities

source

PETSc.LibPETSc.TSForwardSetSensitivities — Method

TSForwardSetSensitivities(petsclib::PetscLibType, ts::AbstractTS, nump::PetscInt, Smat::AbstractPetscMat)

Sets the initial value of the trajectory sensitivities of solution w.r.t. the problem parameters and initial values.

Logically Collective

Input Parameters:

ts - the TS context obtained from TSCreate()
nump - number of parameters
Smat - sensitivities with respect to the parameters, the number of entries in these vectors is the same as the number of parameters

Level: beginner

See also: TSForwardGetSensitivities(), TSForwardSetIntegralGradients(), TSForwardGetIntegralGradients(), TSForwardStep()

External Links

PETSc Manual: Sensitivity/TSForwardSetSensitivities

source

PETSc.LibPETSc.TSForwardSetUp — Method

TSForwardSetUp(petsclib::PetscLibType, ts::AbstractTS)

Sets up the internal data structures for the later use of forward sensitivity analysis

Collective

Input Parameter:

ts - the TS context obtained from TSCreate()

Level: advanced

See also: TS, TSCreate(), TSDestroy(), TSSetUp()

External Links

PETSc Manual: Sensitivity/TSForwardSetUp

source

PETSc.LibPETSc.TSForwardStep — Method

TSForwardStep(petsclib::PetscLibType, ts::AbstractTS)

Compute the forward sensitivity for one time step.

Collective

Input Parameter:

ts - time stepping context

Level: advanced

See also: TSForwardSetSensitivities(), TSForwardGetSensitivities(), TSForwardSetIntegralGradients(), TSForwardGetIntegralGradients(), TSForwardSetUp()

External Links

PETSc Manual: Sensitivity/TSForwardStep

source

PETSc.LibPETSc.TSFunctionDomainError — Method

accept::PetscBool = TSFunctionDomainError(petsclib::PetscLibType, ts::AbstractTS, stagetime::PetscReal, Y::AbstractPetscVec)

Checks if the current state is valid

Collective

Input Parameters:

ts - the TS context
stagetime - time of the simulation
Y - state vector to check.

Output Parameter:

accept - Set to PETSC_FALSE if the current state vector is valid.

Level: developer

See also: TS, TSSetFunctionDomainError()

External Links

PETSc Manual: TS/TSFunctionDomainError

source

PETSc.LibPETSc.TSGLEEFinalizePackage — Method

TSGLEEFinalizePackage(petsclib::PetscLibType)

This function destroys everything in the TSGLEE package. It is called from PetscFinalize().

Level: developer

See also: TS

External Links

PETSc Manual: Sensitivity/TSSetIHessianProduct

source

PETSc.LibPETSc.TSSetIJacobian — Method

TSSetIJacobian(petsclib::PetscLibType, ts::AbstractTS, Amat::AbstractPetscMat, Pmat::AbstractPetscMat, f::Ptr{Cvoid}, ctx::Ptr{Cvoid})

Set the function to compute the matrix dF/dU + a*dF/dUt where F(t,U,Ut) is the function provided with TSSetIFunction().

Logically Collective

Input Parameters:

ts - the TS context obtained from TSCreate()
Amat - (approximate) matrix to store Jacobian entries computed by f
Pmat - matrix used to compute preconditioner (usually the same as Amat)
f - the Jacobian evaluation routine
ctx - user-defined context for private data for the Jacobian evaluation routine (may be NULL)

Level: beginner

See also: TS, TSIJacobianFn, TSSetIFunction(), TSSetRHSJacobian(), SNESComputeJacobianDefaultColor(), SNESComputeJacobianDefault(), TSSetRHSFunction()

External Links

PETSc Manual: TS/TSSetIJacobian

source

PETSc.LibPETSc.TSSetIJacobianP — Method

TSSetIJacobianP(petsclib::PetscLibType, ts::AbstractTS, Amat::AbstractPetscMat, func::external, ctx::Ptr{Cvoid})

Sets the function that computes the Jacobian of F w.r.t. the parameters p where F(Udot,U,p,t) = G(U,p,t), as well as the location to store the matrix.

Logically Collective

Input Parameters:

ts - TS context obtained from TSCreate()
Amat - JacobianP matrix
func - function
ctx - [optional] function context

Calling sequence of func:

ts - the TS context
t - current timestep
U - input vector (current ODE solution)
Udot - time derivative of state vector
shift - shift to apply, see the note in TSSetIJacobian()
A - output matrix
ctx - [optional] function context

Level: intermediate

See also: TS

External Links

PETSc Manual: TS/TSVISetVariableBounds

source

PETSc.LibPETSc.TSView — Method

TSView(petsclib::PetscLibType, ts::AbstractTS, viewer::PetscViewer)

Prints the TS data structure.

Collective

Input Parameters:

ts - the TS context obtained from TSCreate()
viewer - visualization context

Options Database Key:

-ts_view - calls TSView() at end of TSStep()

Level: beginner

See also: TS, PetscViewer, PetscViewerASCIIOpen()

External Links

PETSc Manual: TS/TSView

source

PETSc.LibPETSc.TSViewFromOptions — Method

TSViewFromOptions(petsclib::PetscLibType, ts::AbstractTS, obj, name::String)

View a TS based on values in the options database

Collective

Input Parameters:

ts - the TS context
obj - Optional object that provides the prefix for the options database keys
name - command line option string to be passed by user

Options Database Key:

-name [viewertype][:...] - option name and values. See PetscObjectViewFromOptions() for the possible arguments

Level: intermediate

See also: TS, TSView, PetscObjectViewFromOptions(), TSCreate()

External Links

PETSc Manual: TS/TSViewFromOptions

source

TS Add-ons

Additional TS utilities and helper functions:

PETSc.LibPETSc.TSAdaptCandidateAdd — Method

TSAdaptCandidateAdd(petsclib::PetscLibType, adapt::TSAdapt, name::String, order::PetscInt, stageorder::PetscInt, ccfl::PetscReal, cost::PetscReal, inuse::PetscBool)

add a candidate scheme for the adaptive controller to select from

Logically Collective; No Fortran Support

Input Parameters:

adapt - time step adaptivity context, obtained with TSGetAdapt() or TSAdaptCreate()
name - name of the candidate scheme to add
order - order of the candidate scheme
stageorder - stage order of the candidate scheme
ccfl - stability coefficient relative to explicit Euler, used for CFL constraints
cost - relative measure of the amount of work required for the candidate scheme
inuse - indicates that this scheme is the one currently in use, this flag can only be set for one scheme

Level: developer

See also: TSAdapt, TSAdaptCandidatesClear(), TSAdaptChoose()

External Links

PETSc Manual: TS/TSAdaptCandidateAdd

source

PETSc.LibPETSc.TSAdaptCandidatesClear — Method

TSAdaptCandidatesClear(petsclib::PetscLibType, adapt::TSAdapt)

clear any previously set candidate schemes

Logically Collective

Input Parameter:

adapt - adaptive controller

Level: developer

See also: TSAdapt, TSAdaptCreate(), TSAdaptCandidateAdd(), TSAdaptChoose()

External Links

PETSc Manual: TS/TSAdaptCandidatesClear

source

PETSc.LibPETSc.TSAdaptCandidatesGet — Method

n::PetscInt,order::Ptr{PetscInt},stageorder::Ptr{PetscInt},ccfl::Ptr{PetscReal},cost::Ptr{PetscReal} = TSAdaptCandidatesGet(petsclib::PetscLibType, adapt::TSAdapt)

Get the list of candidate orders of accuracy and cost

Not Collective

Input Parameter:

adapt - time step adaptivity context

Output Parameters:

n - number of candidate schemes, always at least 1
order - the order of each candidate scheme
stageorder - the stage order of each candidate scheme
ccfl - the CFL coefficient of each scheme
cost - the relative cost of each scheme

Level: developer

See also: TSAdapt, TSAdaptCandidatesClear(), TSAdaptCandidateAdd(), TSAdaptChoose()

External Links

PETSc Manual: TS/TSAdaptCandidatesGet

source

PETSc.LibPETSc.TSAdaptCheckStage — Method

accept::PetscBool = TSAdaptCheckStage(petsclib::PetscLibType, adapt::TSAdapt, ts::AbstractTS, t::PetscReal, Y::AbstractPetscVec)

checks whether to accept a stage, (e.g. reject and change time step size if nonlinear solve fails or solution vector is infeasible)

Collective

Input Parameters:

adapt - adaptive controller context
ts - time stepper
t - Current simulation time
Y - Current solution vector

Output Parameter:

accept - PETSC_TRUE to accept the stage, PETSC_FALSE to reject

Level: developer

Hand-written overloads

Some LibPETSc.TS* methods are written by hand in src/ts.jl rather than generated. They take a raw @cfunction pointer where the generated binding expects PETSc's own function-wrapper type, or they return a value the generated binding takes as an argument and overwrites (e.g., TSGetSolution, TSGetSNES and TSGetKSP).

Their docstrings are written inside the PETSc module, so they are listed with the rest of src/ts.jl on the high-level TS page.