Utilities

check_petsc_wrappers_version(petsclib=nothing)

Load the generated petsc_wrappers_version.jl (if present) and compare the declared wrapper version PETSC_WRAPPERS_VERSION with the installed PETSc version obtained from LibPETSc.PetscGetVersionNumber for petsclib.

Arguments

• petsclib: optional PetscLibType or path string. If nothing, the first available PETSc.petsclibs[1] is used.

Returns a named tuple: (:wrappers_version, :installed_version, :match). match is true when versions are equal, false when they differ, and nothing if either side could not be determined.

finalize(petsclib)

Finalize the petsclib, if no petsclib is given then all PETSc.petsclibs will be finalized.

External Links

• PETSc Manual: Sys/PetscFinalize

finalized(petsclib)

Check if petsclib is finalized

External Links

• PETSc Manual: Sys/PetscFinalized

initialize([petsclib]; log_view = false, options = String[])

Initialize the petsclib. If no petsclib is given, all PETSc.petsclibs will be initialized.

Additionally:

• This will initialize MPI if it has not already been initialized.

• It will disable the PETSc signal handler (via Sys/PetscPopSignalHandler

• Add an atexit hook to call PETSc.finalize.

Arguments

• log_view::Bool = false: Enable PETSc's -log_view performance logging. When enabled, PETSc will output performance statistics at finalization.
• options::Vector{String} = String[]: Additional PETSc command-line options. These are passed via the PETSC_OPTIONS environment variable.

Examples

# Basic initialization
PETSc.initialize(petsclib)

# Enable performance logging to stdout
PETSc.initialize(petsclib; log_view = true)

# Write log to a file
PETSc.initialize(petsclib; log_view = true, options = [":logfile.txt"])

# Enable memory logging
PETSc.initialize(petsclib; log_view = true, options = [":logfile.txt", "-log_view_memory"])

# Pass custom PETSc options without logging
PETSc.initialize(petsclib; options = ["-malloc_debug", "-on_error_abort"])

External Links

• PETSc Manual: Sys/PetscInitializeNoArguments

initialized(petsclib)

Check if petsclib is initialized

External Links

• PETSc Manual: Sys/PetscInitialized

inttype(petsclib::PetscLibType)

return the int type for the associated petsclib

library_info()

Print the current PETSc library configuration: which library is in use, how it was configured (preference or default JLL), and the scalar/integer types.

scalartype(petsclib::PetscLibType)

return the scalar type for the associated petsclib

set_library!(path; PetscScalar=Float64, PetscInt=Int64)

Persistently configure PETSc.jl to use a custom PETSc shared library.

The path and type configuration are stored in LocalPreferences.toml (per-project, git-ignorable) and take effect on the next Julia session. Recompilation is triggered automatically — no environment variables are needed.

To revert to the default PETSc_jll libraries, call unset_library!.

Arguments

• path: path to the PETSc shared library (e.g. "/path/to/libpetsc.so")
• PetscScalar: scalar type the library was built with (Float64, Float32, Complex{Float64}, Complex{Float32}). Default: Float64
• PetscInt: integer type the library was built with (Int64 or Int32). Default: Int64

Examples

PETSc.set_library!(
    "/project/petsc/lib/libpetsc.so";
    PetscScalar = Float64,
    PetscInt    = Int64,
)
# Restart Julia — the new library is used automatically from here on.

See Also

• unset_library!: remove the preference and revert to PETSc_jll
• set_petsclib: load a custom library for the current session only

set_petsclib(library_path::String; PetscScalar=Float64, PetscInt=Int64)

Create a custom PETSc library instance from a user-specified shared library path.

This function allows you to use a custom-compiled PETSc library instead of the pre-built libraries provided by PETSc_jll. The custom library must be compiled as a shared/dynamic library (not static), built with the matching scalar type and integer size, and linked against the same MPI installation that MPI.jl uses.

On HPC systems, set JULIA_PETSC_SKIP_JLL=1 before starting Julia to prevent PETSc_jll from being precompiled (its MPI stack is typically incompatible with cluster MPI). Then call this function in your script to load the cluster library.

Arguments

• library_path::String: Path to the PETSc shared library (e.g. "/path/to/libpetsc.so")
• PetscScalar::Type: Scalar type the library was built with. One of Float64, Float32, Complex{Float64}, Complex{Float32}. Default: Float64
• PetscInt::Type: Integer type the library was built with. Int32 or Int64. Default: Int64

Returns

A PetscLibType instance for use with initialize, finalize, and all PETSc.jl functions.

Environment-variable alternative

Instead of calling set_petsclib, you can configure everything before Julia starts:

JULIA_PETSC_LIBRARY=/path/to/libpetsc.so   # also suppresses PETSc_jll
JULIA_PETSC_SCALAR=Float64                  # Float32 | ComplexFloat64 | ComplexFloat32
JULIA_PETSC_INT=Int64                       # Int32

With these set, PETSc.getlib(; PetscScalar=Float64, PetscInt=Int64) returns the custom library directly.

Examples

# Double-precision real, 64-bit indices (typical HPC build)
petsclib = PETSc.set_petsclib("/path/to/libpetsc.so";
                              PetscScalar=Float64, PetscInt=Int64)
PETSc.initialize(petsclib)
# ... your code ...
PETSc.finalize(petsclib)

# Single-precision complex, 32-bit indices
petsclib = PETSc.set_petsclib("/opt/petsc/lib/libpetsc.so";
                              PetscScalar=Complex{Float32}, PetscInt=Int32)

See Also

• initialize: Initialize a PETSc library
• finalize: Finalize a PETSc library

unset_library!()

Remove the persistent custom-library preference set by set_library!, reverting to the default PETSc_jll binaries on the next Julia session.

Options(petsclib; kwargs...)

Create a PETSc options database for the given petsclib.

Keyword arguments are converted to PETSc options:

• Options with value nothing or true are set without a value (flags)
• Options with value false are not set
• Other values are converted to strings

Examples

julia> using PETSc

julia> petsclib = PETSc.petsclibs[1];

julia> PETSc.initialize(petsclib)

julia> opt = PETSc.Options(
                         petsclib,
                         ksp_monitor = nothing,
                         ksp_view = true,
                         pc_type = "mg",
                         pc_mg_levels = 1,
                         false_opt = false,
                     )
#PETSc Option Table entries:
-ksp_monitor
-ksp_view
-pc_mg_levels 1
-pc_type mg
#End of PETSc Option Table entries


julia> opt["ksp_monitor"]
""

julia> opt["pc_type"]
"mg"

julia> opt["pc_type"] = "ilu"
"ilu"

julia> opt["pc_type"]
"ilu"

julia> opt["false_opt"]
ERROR: KeyError: key "bad_key" not found

julia> opt["bad_key"]
ERROR: KeyError: key "bad_key" not found

External Links

• PETSc Manual: Sys/PetscOptionsCreate

parse_options(args::Vector{String})

Parse the args vector into a NamedTuple that can be used as the options for the PETSc solvers.

julia --project file.jl -ksp_monitor -pc_type mg -ksp_view -da_refine=1

typedget(opt::NamedTuple, key::Symbol, default::T)

Parse opt similar to Base.get but ensures that the returned value is the same type as the default value. When T <: NTuple keys that result in a single value will be filled into an NTuple of the same length as T; in the case of strings it is parsed using Base.split with comma delimiter

Examples

julia> opt = (tup = (1, 2, 3), string_tup = "1,2,3", string_int = "4", int = 4)
(tup = (1, 2, 3), string_tup = "1,2,3", string_int = "4", int = 4)

julia> typedget(opt, :int, 7)
4

julia> typedget(opt, :bad_key, 7)
7

julia> typedget(opt, :tup, (1, 1, 1))
(1, 2, 3)

julia> typedget(opt, :string_tup, (1, 1, 1))
tokens = SubString{String}["1", "2", "3"]
(1, 2, 3)

julia> typedget(opt, :string_int, (1, 1, 1))
tokens = SubString{String}["4"]
(4, 4, 4)

julia> typedget(opt, :int, (1, 1, 1))
(4, 4, 4)

julia> typedget(opt, :int, (1., 1., 1.))
(4.0, 4.0, 4.0)

comm = function getcomm(
                        obj::Union{
                            PetscVec{PetscLib},
                            PetscMat{PetscLib},
                            PetscKSP{PetscLib},
                            #PetscSNES{PetscLib},
                            #PetscDM{PetscLib},
                        },
                    ) where {PetscLib}

Gets the MPI communicator for any of the objects above

audit_petsc_file(path::AbstractString)

Scan a PETSc.jl source file and report PETSc object creations and destroys.

This utility reads path, looks for common PETSc object creation patterns (KSP(...), SNES(...), DMDA(...), DMStag(...), as well as VecCreate..., VecDuplicate..., Vec...WithArray(...) and corresponding Mat... creators via either PETSc. or LibPETSc.), plus common DM/Vec/Mat allocators like DMGlobalVec, DMLocalVec, DMGetCoordinateDM, DMStagCreateCompatibleDMStag, and DMCreateMatrix; and for explicit destroy(x) calls (optionally prefixed with PETSc.).

It prints three sections:

• CREATION statements: line numbers and variables assigned to created objects
• DESTROY calls: line numbers and variables destroyed
• POSSIBLY UNDESTROYED objects: variables that appear in creations but have no matching destroy call
  • FINALIZE calls: presence of PETSc.finalize(petsclib); suggests adding it if missing

Notes:

• Heuristic only: matches common constructors and LibPETSc creation routines; it does not follow control flow or scopes.
• Creations without assignment cannot be cross-checked against destroys.
• Objects produced via helpers (e.g., similar(...)) are not detected unless they use known creation patterns.

Returns nothing.