Sys (Runtime, Memory, Strings, Errors) - Low-level Interface

PetscAbortErrorHandler(petsclib::PetscLibType, comm::MPI_Comm, line::Cint, fun::String, file::String, n::PetscErrorCode, p::PetscErrorType, mess::String, ctx::Ptr{Cvoid})

Error handler that calls abort on error. This routine is very useful when running in the debugger, because the user can look directly at the stack frames and the variables where the error occurred

Not Collective, No Fortran Support

Input Parameters:

• comm - communicator over which error occurred
• line - the line number of the error (usually indicated by __LINE__ in the calling routine)
• fun - the function name of the calling routine
• file - the file in which the error was detected (usually indicated by __FILE__ in the calling routine)
• mess - an error text string, usually this is just printed to the screen
• n - the generic error number
• p - PETSC_ERROR_INITIAL indicates this is the first time the error handler is being called while PETSC_ERROR_REPEAT indicates it was previously called
• ctx - error handler context

Options Database Keys:

• -on_error_abort - Activates aborting when an error is encountered
• -start_in_debugger [(noxterm)],[(lldb|gdb|...)] - Starts all processes in the debugger and uses PetscAbortErrorHandler(). By default on Linux the

debugger is gdb and on macOS it is lldb. On Linux it opens a new xterm and on macOS it opens a new Terminal for the debugger unless noxterm is given

• -display name - Uses the X-Windows display name to open the xterms

Level: developer

See also: PetscError(), PetscPushErrorHandler(), PetscPopErrorHander(), PetscTraceBackErrorHandler(), PetscAttachDebuggerErrorHandler(), PetscMPIAbortErrorHandler(), PetscReturnErrorHandler(), PetscEmacsClientErrorHandler(), PetscErrorType, PETSC_ERROR_INITIAL, PETSC_ERROR_REPEAT, PetscErrorCode

External Links

• PETSc Manual: Sys/PetscAbortErrorHandler

PetscAttachDebugger(petsclib::PetscLibType)

Attaches the debugger to the running process.

Not Collective

Options Database Keys:

• -start_in_debugger [(noxterm)],[(lldb|gdb|...)] - Set debugger debug_terminal xterm or Terminal (for Apple)
• -display name - XDisplay to open xterm in
• -debugger_ranks m,n - Which MPI ranks on which to start the debugger, defaults to all
• -stop_for_debugger - Print a message on how to attach the process with a debugger and then wait for the user to attach
• -debugger_pause secs - Wait secs before attaching the debugger. This is useful for slow connections

that take a long time for the Terminal window or xterm to start up.

Level: advanced

See also: PetscSetDebugger(), PetscSetDefaultDebugger(), PetscSetDebugTerminal(), PetscAttachDebuggerErrorHandler(), PetscStopForDebugger()

External Links

• PETSc Manual: Sys/PetscAttachDebugger

PetscAttachDebuggerErrorHandler(petsclib::PetscLibType, comm::MPI_Comm, line::Cint, fun::String, file::String, num::PetscErrorCode, p::PetscErrorType, mess::String, ctx::Ptr{Cvoid})

Error handler that attaches a debugger to a running process when an error is detected. This routine is useful for examining variables, etc.

Not Collective, No Fortran Support

Input Parameters:

• comm - communicator over which error occurred
• line - the line number of the error (usually indicated by __LINE__ in the calling routine)
• fun - the function name of the calling routine
• file - the file in which the error was detected (usually indicated by __FILE__ in the calling routine)
• mess - an error text string, usually just printed to the screen
• num - the generic error number
• p - PETSC_ERROR_INITIAL if error just detected, otherwise PETSC_ERROR_REPEAT
• ctx - error handler context

Level: developer

See also: PetscSetDebuggerFromString(), PetscSetDebugger(), PetscSetDefaultDebugger(), PetscError(), PetscPushErrorHandler(), PetscPopErrorHandler(), PetscTraceBackErrorHandler(), PetscAbortErrorHandler(), PetscMPIAbortErrorHandler(), PetscEmacsClientErrorHandler(), PetscReturnErrorHandler(), PetscSetDebugTerminal()

External Links

• PETSc Manual: Sys/PetscAttachDebuggerErrorHandler

nt::PetscInt = PetscBLASGetNumThreads(petsclib::PetscLibType)

get the number of threads for calls to BLAS to use

Output Parameter:

• nt - the number of threads

Level: intermediate

See also: PetscInitialize(), PetscBLASSetNumThreads()

External Links

• PETSc Manual: Sys/PetscBLASGetNumThreads

PetscBLASSetNumThreads(petsclib::PetscLibType, nt::PetscInt)

set the number of threads for calls to BLAS to use

Input Parameter:

• nt - the number of threads

Options Database Key:

• -blas_num_threads nt - set the number of threads when PETSc is initialized

Level: intermediate

See also: PetscInitialize(), PetscBLASGetNumThreads()

External Links

• PETSc Manual: Sys/PetscBLASSetNumThreads

PetscBTView(petsclib::PetscLibType, m::PetscCount, bt::PetscBT, viewer::PetscViewer)

View the contents of a PetscBT (bit array) on a PetscViewer, one line per bit

Collective on viewer; No Fortran Support

Input Parameters:

• m - the number of bits in the array to print
• bt - the PetscBT
• viewer - the PetscViewer to print to, or NULL to use PETSC_VIEWER_STDOUT_SELF

Level: developer

See also: PetscBT, PetscBTCreate(), PetscBTLookup(), PetscViewer

External Links

• PETSc Manual: Viewer/PetscBTView

PetscBarrier(petsclib::PetscLibType, obj)

Blocks until this routine is executed by all processors owning the object obj.

Input Parameter:

• obj - PETSc object (Mat, Vec, IS, SNES etc...)

Level: intermediate

See also: PetscObject, MPI_Comm, MPI_Barrier

External Links

• PETSc Manual: Sys/PetscBarrier

PetscBinaryClose(petsclib::PetscLibType, fd::Cint)

Closes a PETSc binary file.

Not Collective

Output Parameter:

• fd - the file

Level: advanced

See also: PetscBinaryRead(), PetscBinaryWrite(), PetscBinaryOpen(), PetscBinarySynchronizedWrite(), PetscBinarySynchronizedRead(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Sys/PetscBinaryClose

fd::Cint = PetscBinaryOpen(petsclib::PetscLibType, name::String, mode::PetscFileMode)

Opens a PETSc binary file.

Not Collective

Input Parameters:

• name - filename
• mode - open mode of binary file, one of FILE_MODE_READ, FILE_MODE_WRITE, FILE_MODE_APPEND

Output Parameter:

• fd - the file

Level: advanced

See also: PetscBinaryRead(), PetscBinaryWrite(), PetscFileMode, PetscViewerFileSetMode(), PetscViewerBinaryGetDescriptor(), PetscBinarySynchronizedWrite(), PetscBinarySynchronizedRead(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Sys/PetscBinaryOpen

data::Ptr{Cvoid},count::PetscInt = PetscBinaryRead(petsclib::PetscLibType, fd::Cint, num::PetscCount, type::PetscDataType)

Reads from a binary file.

Not Collective

Input Parameters:

• fd - the file descriptor
• num - the maximum number of items to read
• type - the type of items to read (PETSC_INT, PETSC_REAL, PETSC_SCALAR, etc.)

Output Parameters:

• data - the buffer, this is an array of the type that matches the value in type
• count - the number of items read, optional

Level: developer

See also: PetscBinaryWrite(), PetscBinaryOpen(), PetscBinaryClose(), PetscViewerBinaryGetDescriptor(), PetscBinarySynchronizedWrite(), PetscBinarySynchronizedRead(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Viewer/PetscBinaryRead

data::Ptr{Cvoid},count::PetscInt = PetscBinarySynchronizedRead(petsclib::PetscLibType, comm::MPI_Comm, fd::Cint, num::PetscInt, type::PetscDataType)

Reads from a binary file, all MPI processes get the same values

Collective, No Fortran Support

Input Parameters:

• comm - the MPI communicator
• fd - the file descriptor
• num - the maximum number of items to read
• type - the type of items to read (PETSC_INT, PETSC_REAL, PETSC_SCALAR, etc.)

Output Parameters:

• data - the buffer, an array of the type that matches the value in type
• count - the number of items read, optional

Level: developer

See also: PetscBinaryWrite(), PetscBinaryOpen(), PetscBinaryClose(), PetscBinaryRead(), PetscBinarySynchronizedWrite(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Sys/PetscBinarySynchronizedRead

PetscBinarySynchronizedWrite(petsclib::PetscLibType, comm::MPI_Comm, fd::Cint, p::Ptr{Cvoid}, n::PetscInt, type::PetscDataType)

writes to a binary file.

Collective, No Fortran Support

Input Parameters:

• comm - the MPI communicator
• fd - the file
• n - the number of items to write
• p - the buffer, an array of the type that matches the value in type
• type - the type of items to write (PETSC_INT, PETSC_REAL or PETSC_SCALAR)

Level: developer

See also: PetscBinaryWrite(), PetscBinaryOpen(), PetscBinaryClose(), PetscBinaryRead(), PetscBinarySynchronizedRead(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Sys/PetscBinarySynchronizedWrite

PetscBinaryWrite(petsclib::PetscLibType, fd::Cint, p::Ptr{Cvoid}, n::PetscCount, type::PetscDataType)

Writes to a binary file.

Not Collective

Input Parameters:

• fd - the file
• p - the buffer, an array of the type that matches the value in type
• n - the number of items to write
• type - the type of items to read (PETSC_INT, PETSC_REAL or PETSC_SCALAR)

Level: advanced

See also: PetscBinaryRead(), PetscBinaryOpen(), PetscBinaryClose(), PetscViewerBinaryGetDescriptor(), PetscBinarySynchronizedWrite(), PetscBinarySynchronizedRead(), PetscBinarySynchronizedSeek()

External Links

• PETSc Manual: Viewer/PetscBinaryWrite

PetscBoxAuthorize(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, refresh_token::String, tokensize::Csize_t)

Get authorization and refresh token for accessing Box drive from PETSc

Not Collective, only the first rank in MPI_Comm does anything

Input Parameters:

• comm - the MPI communicator
• tokensize - size of the token arrays

Output Parameters:

• access_token - can be used with PetscBoxUpload() for this one session
• refresh_token - can be used for ever to obtain new access_tokens with PetscBoxRefresh(),

guard this like a password it gives access to your Box Drive

Level: intermediate

See also: PetscBoxRefresh(), PetscBoxUpload()

External Links

• PETSc Manual: Sys/PetscBoxAuthorize

PetscBoxRefresh(petsclib::PetscLibType, comm::MPI_Comm, refresh_token::String, access_token::String, new_refresh_token::String, tokensize::Csize_t)

Get a new authorization token for accessing Box drive from PETSc from a refresh token

Not Collective, only the first process in the MPI_Comm does anything

Input Parameters:

• comm - MPI communicator
• refresh_token - obtained with PetscBoxAuthorize(), if NULL PETSc will first look for one in the options data

if not found it will call PetscBoxAuthorize()

• tokensize - size of the output string access_token

Output Parameters:

• access_token - token that can be passed to PetscBoxUpload()
• new_refresh_token - the old refresh token is no longer valid, not this is different than Google where the same refresh_token is used forever

Level: intermediate

See also: PetscBoxAuthorize(), PetscBoxUpload()

External Links

• PETSc Manual: Sys/PetscBoxRefresh

PetscBoxUpload(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, filename::String)

Loads a file to the Box Drive

This routine has not yet been written; it is just copied from Google Drive

Not collective, only the first process in the MPI_Comm uploads the file

Input Parameters:

• comm - MPI communicator
• access_token - obtained with PetscBoxRefresh(), pass NULL to have PETSc generate one
• filename - file to upload; if you upload multiple times it will have different names each time on Box Drive

Options Database Key:

• -box_refresh_token XXX - the token value

See also: PetscBoxAuthorize(), PetscBoxRefresh()

External Links

• PETSc Manual: Sys/PetscBoxUpload

PetscByteSwap(petsclib::PetscLibType, data::Ptr{Cvoid}, pdtype::PetscDataType, count::PetscCount)

Reverse the byte order of an array of values of a given PetscDataType, in place

Not Collective; No Fortran Support

Input Parameters:

• data - the array of values to byte-swap in place
• pdtype - the PetscDataType of the values (e.g. PETSC_INT, PETSC_REAL, PETSC_SCALAR)
• count - number of values in data

Level: developer

See also: PetscDataType, PetscViewerBinaryRead(), PetscViewerBinaryWrite()

External Links

• PETSc Manual: Sys/PetscByteSwap

PetscCUBLASGetHandle(petsclib::PetscLibType, handle::cublasHandle_t)

External Links

• PETSc Manual: Sys/PetscCUBLASGetHandle

PetscCUSOLVERDnGetHandle(petsclib::PetscLibType, handle::cusolverDnHandle_t)

External Links

• PETSc Manual: Sys/PetscCUSOLVERDnGetHandle

dups::PetscBool = PetscCheckDupsInt(petsclib::PetscLibType, n::PetscInt, X::Vector{PetscInt})

Checks if an PetscInt array has duplicates

Not Collective

Input Parameters:

• n - number of values in the array
• X - array of PetscInt

Output Parameter:

• dups - True if the array has dups, otherwise false

Level: intermediate

See also: PetscSortRemoveDupsInt(), PetscSortedCheckDupsInt()

External Links

• PETSc Manual: Sys/PetscCheckDupsInt

PetscCheckPointerSetIntensity(petsclib::PetscLibType, intensity::PetscInt)

Set the intensity of debug pointer checks

Not Collective

Input Parameter:

• intensity - how much to check pointers for validity

Options Database Key:

• -check_pointer_intensity - intensity (0, 1, or 2)

Level: advanced

See also: PetscCheckPointer(), PetscFunctionBeginHot()

External Links

• PETSc Manual: Sys/PetscCheckPointerSetIntensity

oclass::PetscClassId = PetscClassIdRegister(petsclib::PetscLibType, name::String)

Registers a new class name for objects and logging operations in an application code.

Not Collective

Input Parameter:

• name - The class name

Output Parameter:

• oclass - The class id or classid

Level: developer

See also: PetscLogEventRegister()

External Links

• PETSc Manual: Log/PetscClassIdRegister

twosided::PetscBuildTwoSidedType = PetscCommBuildTwoSidedGetType(petsclib::PetscLibType, comm::MPI_Comm)

get algorithm used when building two-sided communication

Logically Collective

Output Parameters:

• comm - communicator on which to query algorithm
• twosided - algorithm to use for PetscCommBuildTwoSided()

Level: developer

See also: PetscCommBuildTwoSided(), PetscCommBuildTwoSidedSetType(), PetscBuildTwoSidedType

External Links

• PETSc Manual: Sys/PetscCommBuildTwoSidedGetType

PetscCommBuildTwoSidedSetType(petsclib::PetscLibType, comm::MPI_Comm, twosided::PetscBuildTwoSidedType)

set algorithm to use when building two-sided communication

Logically Collective

Input Parameters:

• comm - PETSC_COMM_WORLD
• twosided - algorithm to use in subsequent calls to PetscCommBuildTwoSided()

Level: developer

See also: PetscCommBuildTwoSided(), PetscCommBuildTwoSidedGetType(), PetscBuildTwoSidedType

External Links

• PETSc Manual: Sys/PetscCommBuildTwoSidedSetType

comm::MPI_Comm = PetscCommDestroy(petsclib::PetscLibType)

Frees communicator obtained with PetscCommDuplicate().

Collective

Input Parameter:

• comm - the communicator to free

Level: developer

See also: PetscCommDuplicate()

External Links

• PETSc Manual: Sys/PetscCommDestroy

comm_out::MPI_Comm,first_tag::PetscMPIInt = PetscCommDuplicate(petsclib::PetscLibType, comm_in::MPI_Comm)

Duplicates the communicator only if it is not already a PETSc communicator.

Collective

Input Parameter:

• comm_in - Input communicator

Output Parameters:

• comm_out - Output communicator. May be comm_in.
• first_tag - Tag available that has not already been used with this communicator (you may pass in NULL if you do not need a tag)

Level: developer

See also: PetscObjectGetNewTag(), PetscCommGetNewTag(), PetscCommDestroy()

External Links

• PETSc Manual: Sys/PetscCommDuplicate

comm_out::MPI_Comm = PetscCommGetComm(petsclib::PetscLibType, comm_in::MPI_Comm)

get a new MPI communicator from a PETSc communicator that can be passed off to another package

Collective

Input Parameter:

• comm_in - Input communicator

Output Parameter:

• comm_out - Output communicator

Level: developer

See also: PetscObjectGetNewTag(), PetscCommGetNewTag(), PetscCommDestroy(), PetscCommRestoreComm()

External Links

• PETSc Manual: Sys/PetscCommGetComm

tag::PetscMPIInt = PetscCommGetNewTag(petsclib::PetscLibType, comm::MPI_Comm)

Gets a unique new tag from a PETSc communicator

Collective

Input Parameter:

• comm - the MPI communicator

Output Parameter:

• tag - the new tag

Level: developer

See also: PetscObjectGetNewTag(), PetscCommDuplicate()

External Links

• PETSc Manual: Sys/PetscCommGetNewTag

PetscCommRestoreComm(petsclib::PetscLibType, comm_in::MPI_Comm, comm_out::MPI_Comm)

restores an MPI communicator that was obtained with PetscCommGetComm()

Collective

Input Parameters:

• comm_in - Input communicator
• comm_out - returned communicator

Level: developer

See also: PetscObjectGetNewTag(), PetscCommGetNewTag(), PetscCommDestroy()

External Links

• PETSc Manual: Sys/PetscCommRestoreComm

PetscCommSplitReductionBegin(petsclib::PetscLibType, comm::MPI_Comm)

Begin an asynchronous split-mode reduction

Collective but not synchronizing

Input Parameter:

• comm - communicator on which split reduction has been queued

Level: advanced

See also: VecNormBegin(), VecNormEnd(), VecDotBegin(), VecDotEnd(), VecTDotBegin(), VecTDotEnd(), VecMDotBegin(), VecMDotEnd(), VecMTDotBegin(), VecMTDotEnd()

External Links

• PETSc Manual: Vec/PetscCommSplitReductionBegin

name::Ptr{Cchar} = PetscDLAddr(petsclib::PetscLibType, func::Ptr{Cvoid})

find the name of a symbol in a dynamic library

Not Collective, No Fortran Support

Input Parameters:

• func - pointer to the function, NULL if not found

Output Parameter:

• name - name of symbol, or NULL if name lookup is not supported.

Level: developer

See also: PetscDLClose(), PetscDLSym(), PetscDLOpen(), PetscDLLibrary, PetscLoadDynamicLibrary(), PetscDLLibraryAppend(), PetscDLLibraryRetrieve(), PetscDLLibraryOpen(), PetscDLLibraryClose(), PetscDLLibrarySym()

External Links

• PETSc Manual: Sys/PetscDLAddr

PetscDLClose(petsclib::PetscLibType, handle::PetscDLHandle)

closes a dynamic library

Not Collective, No Fortran Support

Input Parameter:

• handle - the handle for the library obtained with PetscDLOpen()

Level: developer

See also: PetscDLOpen(), PetscDLSym(), PetscDLAddr()

External Links

• PETSc Manual: Sys/PetscDLClose

handle::PetscDLHandle = PetscDLOpen(petsclib::PetscLibType, name::String, mode::PetscDLMode)

opens a dynamic library

Not Collective, No Fortran Support

Input Parameters:

• name - name of library
• mode - options on how to open library, see PetscDLMode

Output Parameter:

• handle - opaque pointer to be used with PetscDLSym()

Level: developer

See also: PetscDLClose(), PetscDLSym(), PetscDLAddr(), PetscDLLibrary, PetscLoadDynamicLibrary(), PetscDLLibraryAppend(), PetscDLLibraryRetrieve(), PetscDLLibraryOpen(), PetscDLLibraryClose(), PetscDLLibrarySym(), PetscDLMode, PetscDLHandle

External Links

• PETSc Manual: Sys/PetscDLOpen

value::Ptr{Cvoid} = PetscDLSym(petsclib::PetscLibType, handle::PetscDLHandle, symbol::String)

finds a symbol in a dynamic library

Not Collective, No Fortran Support

Input Parameters:

• handle - obtained with PetscDLOpen() or NULL
• symbol - name of symbol

Output Parameter:

• value - returns pointer to the function, NULL if not found

Level: developer

See also: PetscDLClose(), PetscDLOpen(), PetscDLAddr(), PetscDLLibrary, PetscLoadDynamicLibrary(), PetscDLLibraryAppend(), PetscDLLibraryRetrieve(), PetscDLLibraryOpen(), PetscDLLibraryClose(), PetscDLLibrarySym(), PetscDLHandle

External Links

• PETSc Manual: Sys/PetscDLSym

wv::PetscReal = PetscDTAltVApply(petsclib::PetscLibType, N::PetscInt, k::PetscInt, w::Vector{PetscReal}, v::Vector{PetscReal})

Apply an a k-form (an alternating k-linear map) to a set of k N-dimensional vectors

Input Parameters:

• N - the dimension of the vector space, N >= 0
• k - the degree k of the k-form w, 0 <= k <= N
• w - a k-form, size [N choose k] (each degree of freedom of a k-form is associated with a subset of k coordinates of the N-dimensional vectors.

The degrees of freedom are ordered lexicographically by their associated subsets)

• v - a set of k vectors of size N, size [k x N], each vector stored contiguously

Output Parameter:

• wv - w(v1,...,vk) = \sumi wi * det(Vi): the degree of freedom wi is associated with coordinates [s{i,1},...,s{i,k}], and the square matrix V_i has

entry (j,k) given by the s{i,k}'th coordinate of vj

Level: intermediate

See also: PetscDTAltV, PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVApply

wIntv::PetscReal = PetscDTAltVInterior(petsclib::PetscLibType, N::PetscInt, k::PetscInt, w::Vector{PetscReal}, v::Vector{PetscReal})

Compute the interior product of a k-form with a vector

Input Parameters:

• N - the dimension of the vector space, N >= 0
• k - the degree k of the k-form w, 0 <= k <= N
• w - a k-form, size [N choose k]
• v - an N dimensional vector

Output Parameter:

• wIntv - the (k-1)-form (w int v), size [N choose (k-1)]: (w int v) is defined by its action on (k-1) vectors {v1, ..., v{k-1}} as (w inv v)(v1, ..., v{k-1}) = w(v, v1, ..., v{k-1}).

Level: intermediate

See also: PetscDTAltV, PetscDTAltVInteriorMatrix(), PetscDTAltVInteriorPattern(), PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVInterior

intvMat::PetscReal = PetscDTAltVInteriorMatrix(petsclib::PetscLibType, N::PetscInt, k::PetscInt, v::Vector{PetscReal})

Compute the matrix of the linear transformation induced on a k-form by the interior product with a vector

Input Parameters:

• N - the dimension of the vector space, N >= 0
• k - the degree k of the k-forms on which intvMat acts, 0 <= k <= N
• v - an N dimensional vector

Output Parameter:

• intvMat - an [(N choose (k-1)) x (N choose k)] matrix, row-major: (intvMat) * w = (w int v)

Level: intermediate

See also: PetscDTAltV, PetscDTAltVInterior(), PetscDTAltVInteriorPattern(), PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVInteriorMatrix

PetscDTAltVInteriorPattern(petsclib::PetscLibType, N::PetscInt, k::PetscInt, noname::Ptr{Cvoid})

compute the sparsity and sign pattern of the interior product matrix computed in PetscDTAltVInteriorMatrix()

Input Parameters:

• N - the dimension of the vector space, N \ge 0
• k - the degree of the k-forms on which intvMat from PetscDTAltVInteriorMatrix() acts, 0 le k le N .

Output Parameter:

• indices - The interior product matrix intvMat has dimensions [(N choose (k-1)) x (N choose k)] and has (N choose k) * k

non-zeros. indices[i][0] and indices[i][1] are the row and column of a non-zero, and its value is equal to the vector coordinate v[j] if indices[i][2] = j, or -v[j] if indices[i][2] = -(j+1)

Level: intermediate

See also: PetscDTAltV, PetscDTAltVInterior(), PetscDTAltVInteriorMatrix(), PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVInteriorPattern

Lstarw::PetscReal = PetscDTAltVPullback(petsclib::PetscLibType, N::PetscInt, M::PetscInt, L::Vector{PetscReal}, k::PetscInt, w::Vector{PetscReal})

Compute the pullback of a k-form under a linear transformation of the coordinate space

Input Parameters:

• N - the dimension of the origin vector space of the linear transformation, M >= 0
• M - the dimension of the image vector space of the linear transformation, N >= 0
• L - a linear transformation, an [M x N] matrix in row-major format
• k - the signed degree k of the |k|-form w, -(min(M,N)) <= k <= min(M,N). A negative form degree indicates that the pullback should be conjugated by

the Hodge star operator (see note).

• w - a |k|-form in the image space, size [M choose |k|]

Output Parameter:

• Lstarw - the pullback of w to a |k|-form in the origin space, size [N choose |k|]: (Lstarw)(v1,...vk) = w(Lv_1,...,Lv_k).

Level: intermediate

See also: PetscDTAltV, PetscDTAltVPullbackMatrix(), PetscDTAltVStar()

External Links

• PETSc Manual: DT/PetscDTAltVPullback

Lstar::PetscReal = PetscDTAltVPullbackMatrix(petsclib::PetscLibType, N::PetscInt, M::PetscInt, L::Vector{PetscReal}, k::PetscInt)

Compute the pullback matrix for k-forms under a linear transformation

Input Parameters:

• N - the dimension of the origin vector space of the linear transformation, N >= 0
• M - the dimension of the image vector space of the linear transformation, M >= 0
• L - a linear transformation, an [M x N] matrix in row-major format
• k - the signed degree k of the |k|-forms on which Lstar acts, -(min(M,N)) <= k <= min(M,N).

A negative form degree indicates that the pullback should be conjugated by the Hodge star operator (see note in PetscDTAltvPullback())

Output Parameter:

• Lstar - the pullback matrix, an [(N choose |k|) x (M choose |k|)] matrix in row-major format such that Lstar * w = L^* w

Level: intermediate

See also: PetscDTAltV, PetscDTAltVPullback(), PetscDTAltVStar()

External Links

• PETSc Manual: DT/PetscDTAltVPullbackMatrix

starw::PetscReal = PetscDTAltVStar(petsclib::PetscLibType, N::PetscInt, k::PetscInt, pow::PetscInt, w::Vector{PetscReal})

Apply a power of the Hodge star operator, which maps k-forms to (N-k) forms, to a k-form

Input Parameters:

• N - the dimension of the vector space, N >= 0
• k - the degree k of the k-form w, 0 <= k <= N
• pow - the number of times to apply the Hodge star operator: pow < 0 indicates that the inverse of the Hodge star operator should be applied |pow| times.
• w - a k-form, size [N choose k]

Output Parameter:

• starw - (star)^pow w

Level: intermediate

See also: PetscDTAltV, PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVStar

awedgeb::PetscReal = PetscDTAltVWedge(petsclib::PetscLibType, N::PetscInt, j::PetscInt, k::PetscInt, a::Vector{PetscReal}, b::Vector{PetscReal})

Compute the wedge product of a j-form and a k-form, giving a (j+k) form

Input Parameters:

• N - the dimension of the vector space, N >= 0
• j - the degree j of the j-form a, 0 <= j <= N
• k - the degree k of the k-form b, 0 <= k <= N and 0 <= j+k <= N
• a - a j-form, size [N choose j]
• b - a k-form, size [N choose k]

Output Parameter:

• awedgeb - the (j+k)-form a wedge b, size [N choose (j+k)]: (a wedge b)(v1,...,v{j+k}) = \sum{s} sign(s) a(v{s1},...,v{sj}) b(v{s{j+1}},...,v{s_{j+k}}),

where the sum is over permutations s such that s1 < s2 < ... < sj and s{j+1} < s{j+2} < ... < s{j+k}.

Level: intermediate

See also: PetscDTAltV, PetscDTAltVWedgeMatrix(), PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVWedge

awedgeMat::PetscReal = PetscDTAltVWedgeMatrix(petsclib::PetscLibType, N::PetscInt, j::PetscInt, k::PetscInt, a::Vector{PetscReal})

Compute the matrix defined by the wedge product with a given j-form that maps k-forms to (j+k)-forms

Input Parameters:

• N - the dimension of the vector space, N >= 0
• j - the degree j of the j-form a, 0 <= j <= N
• k - the degree k of the k-forms that (a wedge) will be applied to, 0 <= k <= N and 0 <= j+k <= N
• a - a j-form, size [N choose j]

Output Parameter:

• awedgeMat - (a wedge), an [(N choose j+k) x (N choose k)] matrix in row-major order, such that (a wedge) * b = a wedge b

Level: intermediate

See also: PetscDTAltV, PetscDTAltVPullback(), PetscDTAltVPullbackMatrix()

External Links

• PETSc Manual: DT/PetscDTAltVWedgeMatrix

index::PetscInt = PetscDTBaryToIndex(petsclib::PetscLibType, len::PetscInt, sum::PetscInt, coord::Vector{PetscInt})

convert a barycentric coordinate to an index

Input Parameters:

• len - the desired length of the barycentric tuple (usually 1 more than the dimension it represents, so a barycentric coordinate in a triangle has length 3)
• sum - the value that the sum of the barycentric coordinates (which will be non-negative integers) should sum to
• coord - a barycentric coordinate with the given length len and sum

Output Parameter:

• index - the unique index for the coordinate, >= 0 and < Binomial(len - 1 + sum, sum)

Level: beginner

See also: PetscDTIndexToBary

External Links

• PETSc Manual: DT/PetscDTBaryToIndex

q::PetscQuadrature,fq::PetscQuadrature = PetscDTCreateDefaultQuadrature(petsclib::PetscLibType, ct::DMPolytopeType, qorder::PetscInt)

Create default quadrature for a given cell

Not collective

Input Parameters:

• ct - The integration domain
• qorder - The desired quadrature order

Output Parameters:

• q - The cell quadrature
• fq - The face quadrature

Level: developer

See also: PetscDTCreateQuadratureByCell(), PetscFECreateDefault(), PetscDTGaussTensorQuadrature(), PetscDTSimplexQuadrature(), PetscDTTensorQuadratureCreate()

External Links

• PETSc Manual: DT/PetscDTCreateDefaultQuadrature

q::PetscQuadrature,fq::PetscQuadrature = PetscDTCreateQuadratureByCell(petsclib::PetscLibType, ct::DMPolytopeType, qorder::PetscInt, qtype::PetscDTSimplexQuadratureType)

Create default quadrature for a given cell

Not collective

Input Parameters:

• ct - The integration domain
• qorder - The desired quadrature order
• qtype - The type of simplex quadrature, or PETSCDTSIMPLEXQUAD_DEFAULT

Output Parameters:

• q - The cell quadrature
• fq - The face quadrature

Level: developer

See also: PetscDTCreateDefaultQuadrature(), PetscFECreateDefault(), PetscDTGaussTensorQuadrature(), PetscDTSimplexQuadrature(), PetscDTTensorQuadratureCreate()

External Links

• PETSc Manual: DT/PetscDTCreateQuadratureByCell

PetscDTGaussJacobiQuadrature(petsclib::PetscLibType, npoints::PetscInt, a::PetscReal, b::PetscReal, alpha::PetscReal, beta::PetscReal, x::Vector{PetscReal}, w::Vector{PetscReal})

quadrature for the interval [a, b] with the weight function (x-a)^\alpha (x-b)^\beta.

Not Collective

Input Parameters:

• npoints - the number of points in the quadrature rule
• a - the left endpoint of the interval
• b - the right endpoint of the interval
• alpha - the left exponent
• beta - the right exponent

Output Parameters:

• x - array of length npoints, the locations of the quadrature points
• w - array of length npoints, the weights of the quadrature points

Level: intermediate

See also: PetscDTGaussQuadrature()

External Links

• PETSc Manual: DT/PetscDTGaussJacobiQuadrature

PetscDTGaussLobattoJacobiQuadrature(petsclib::PetscLibType, npoints::PetscInt, a::PetscReal, b::PetscReal, alpha::PetscReal, beta::PetscReal, x::Vector{PetscReal}, w::Vector{PetscReal})

quadrature for the interval [a, b] with the weight function (x-a)^\alpha (x-b)^\beta, with endpoints a and b included as quadrature points.

Not Collective

Input Parameters:

• npoints - the number of points in the quadrature rule
• a - the left endpoint of the interval
• b - the right endpoint of the interval
• alpha - the left exponent
• beta - the right exponent

Output Parameters:

• x - array of length npoints, the locations of the quadrature points
• w - array of length npoints, the weights of the quadrature points

Level: intermediate

See also: PetscDTGaussJacobiQuadrature()

External Links

• PETSc Manual: DT/PetscDTGaussLobattoJacobiQuadrature

PetscDTGaussLobattoLegendreQuadrature(petsclib::PetscLibType, npoints::PetscInt, type::PetscGaussLobattoLegendreCreateType, x::Vector{PetscReal}, w::Vector{PetscReal})

creates a set of the locations and weights of the Gauss-Lobatto-Legendre nodes of a given size on the domain [-1,1]

Not Collective

Input Parameters:

• npoints - number of grid nodes
• type - PETSCGAUSSLOBATTOLEGENDRE_VIA_LINEAR_ALGEBRA or PETSCGAUSSLOBATTOLEGENDRE_VIA_NEWTON

Output Parameters:

• x - quadrature points, pass in an array of length npoints
• w - quadrature weights, pass in an array of length npoints

Level: intermediate

See also: PetscDTGaussQuadrature(), PetscGaussLobattoLegendreCreateType

External Links

• PETSc Manual: DT/PetscDTGaussLobattoLegendreQuadrature

PetscDTGaussQuadrature(petsclib::PetscLibType, npoints::PetscInt, a::PetscReal, b::PetscReal, x::Vector{PetscReal}, w::Vector{PetscReal})

create Gauss-Legendre quadrature

Not Collective

Input Parameters:

• npoints - number of points
• a - left end of interval (often-1)
• b - right end of interval (often +1)

Output Parameters:

• x - quadrature points
• w - quadrature weights

Level: intermediate

See also: PetscDTLegendreEval(), PetscDTGaussJacobiQuadrature()

External Links

• PETSc Manual: DT/PetscDTGaussQuadrature

q::PetscQuadrature = PetscDTGaussTensorQuadrature(petsclib::PetscLibType, dim::PetscInt, Nc::PetscInt, npoints::PetscInt, a::PetscReal, b::PetscReal)

creates a tensor-product Gauss quadrature

Not Collective

Input Parameters:

• dim - The spatial dimension
• Nc - The number of components
• npoints - number of points in one dimension
• a - left end of interval (often-1)
• b - right end of interval (often +1)

Output Parameter:

• q - A PetscQuadrature object

Level: intermediate

See also: PetscDTGaussQuadrature(), PetscDTLegendreEval()

External Links

• PETSc Manual: DT/PetscDTGaussTensorQuadrature

index::PetscInt = PetscDTGradedOrderToIndex(petsclib::PetscLibType, len::PetscInt, degtup::Vector{PetscInt})

convert a tuple into an index in a graded order, the inverse of PetscDTIndexToGradedOrder().

Input Parameters:

• len - the length of the degree tuple
• degtup - tuple with this length

Output Parameter:

• index - index in graded order: >= 0

Level: beginner

See also: PetscDTIndexToGradedOrder()

External Links

• PETSc Manual: DT/PetscDTGradedOrderToIndex

PetscDTIndexToBary(petsclib::PetscLibType, len::PetscInt, sum::PetscInt, index::PetscInt, coord::Vector{PetscInt})

convert an index into a barycentric coordinate.

Input Parameters:

• len - the desired length of the barycentric tuple (usually 1 more than the dimension it represents, so a barycentric coordinate in a triangle has length 3)
• sum - the value that the sum of the barycentric coordinates (which will be non-negative integers) should sum to
• index - the index to convert: should be >= 0 and < Binomial(len - 1 + sum, sum)

Output Parameter:

• coord - will be filled with the barycentric coordinate, of length n

Level: beginner

See also: PetscDTBaryToIndex()

External Links

• PETSc Manual: DT/PetscDTIndexToBary

PetscDTIndexToGradedOrder(petsclib::PetscLibType, len::PetscInt, index::PetscInt, degtup::Vector{PetscInt})

convert an index into a tuple of monomial degrees in a graded order (that is, if the degree sum of tuple x is less than the degree sum of tuple y, then the index of x is smaller than the index of y)

Input Parameters:

• len - the desired length of the degree tuple
• index - the index to convert: should be >= 0

Output Parameter:

• degtup - filled with a tuple of degrees

Level: beginner

See also: PetscDTGradedOrderToIndex()

External Links

• PETSc Manual: DT/PetscDTIndexToGradedOrder

PetscDTJacobiEval(petsclib::PetscLibType, npoints::PetscInt, alpha::PetscReal, beta::PetscReal, points::Vector{PetscReal}, ndegree::PetscInt, degrees::Vector{PetscInt}, B::Vector{PetscReal}, D::Vector{PetscReal}, D2::Vector{PetscReal})

evaluate Jacobi polynomials for the weight function (1.+x)^{\alpha} (1.-x)^{\beta} at a set of points at points

Not Collective

Input Parameters:

• npoints - number of spatial points to evaluate at
• alpha - the left exponent > -1
• beta - the right exponent > -1
• points - array of locations to evaluate at
• ndegree - number of basis degrees to evaluate
• degrees - sorted array of degrees to evaluate

Output Parameters:

• B - row-oriented basis evaluation matrix B[pointndegree + degree] (dimension npointsndegrees, allocated by caller) (or NULL)
• D - row-oriented derivative evaluation matrix (or NULL)
• D2 - row-oriented second derivative evaluation matrix (or NULL)

Level: intermediate

See also: PetscDTGaussQuadrature(), PetscDTLegendreEval()

External Links

• PETSc Manual: DT/PetscDTJacobiEval

PetscDTJacobiEvalJet(petsclib::PetscLibType, alpha::PetscReal, beta::PetscReal, npoints::PetscInt, points::Vector{PetscReal}, degree::PetscInt, k::PetscInt, p::Vector{PetscReal})

Evaluate the jet (function and derivatives) of the Jacobi polynomials basis up to a given degree.

Input Parameters:

• alpha - the left exponent of the weight
• beta - the right exponetn of the weight
• npoints - the number of points to evaluate the polynomials at
• points - [npoints] array of point coordinates
• degree - the maximm degree polynomial space to evaluate, (degree + 1) will be evaluated total.
• k - the maximum derivative to evaluate in the jet, (k + 1) will be evaluated total.

Output Parameter:

• p - an array containing the evaluations of the Jacobi polynomials's jets on the points. the size is (degree + 1) x

(k + 1) x npoints, which also describes the order of the dimensions of this three-dimensional array: the first (slowest varying) dimension is polynomial degree; the second dimension is derivative order; the third (fastest varying) dimension is the index of the evaluation point.

Level: advanced

See also: PetscDTJacobiEval(), PetscDTPKDEvalJet()

External Links

• PETSc Manual: DT/PetscDTJacobiEvalJet

norm::PetscReal = PetscDTJacobiNorm(petsclib::PetscLibType, alpha::PetscReal, beta::PetscReal, n::PetscInt)

Compute the weighted L2 norm of a Jacobi polynomial.

\| P^{\alpha,\beta}n \|{\alpha,\beta}^2 = \int{-1}^1 (1 + x)^{\alpha} (1 - x)^{\beta} P^{\alpha,\beta}n (x)^2 dx.

Input Parameters:

• alpha - the left exponent > -1
• beta - the right exponent > -1
• n - the polynomial degree

Output Parameter:

• norm - the weighted L2 norm

Level: beginner

See also: PetscQuadrature, PetscDTJacobiEval()

External Links

• PETSc Manual: DT/PetscDTJacobiNorm

PetscDTLegendreEval(petsclib::PetscLibType, npoints::PetscInt, points::Vector{PetscReal}, ndegree::PetscInt, degrees::Vector{PetscInt}, B::Vector{PetscReal}, D::Vector{PetscReal}, D2::Vector{PetscReal})

evaluate Legendre polynomials at points

Not Collective

Input Parameters:

• npoints - number of spatial points to evaluate at
• points - array of locations to evaluate at
• ndegree - number of basis degrees to evaluate
• degrees - sorted array of degrees to evaluate

Output Parameters:

• B - row-oriented basis evaluation matrix B[pointndegree + degree] (dimension npointsndegrees, allocated by caller) (or NULL)
• D - row-oriented derivative evaluation matrix (or NULL)
• D2 - row-oriented second derivative evaluation matrix (or NULL)

Level: intermediate

See also: PetscDTGaussQuadrature()

External Links

• PETSc Manual: DT/PetscDTLegendreEval

PetscDTPKDEvalJet(petsclib::PetscLibType, dim::PetscInt, npoints::PetscInt, points::Vector{PetscReal}, degree::PetscInt, k::PetscInt, p::Vector{PetscReal})

Evaluate the jet (function and derivatives) of the Proriol-Koornwinder-Dubiner (PKD) basis for the space of polynomials up to a given degree.

Input Parameters:

• dim - the number of variables in the multivariate polynomials
• npoints - the number of points to evaluate the polynomials at
• points - [npoints x dim] array of point coordinates
• degree - the degree (sum of degrees on the variables in a monomial) of the polynomial space to evaluate. There are ((dim + degree) choose dim) polynomials in this space.
• k - the maximum order partial derivative to evaluate in the jet. There are (dim + k choose dim) partial derivatives

in the jet. Choosing k = 0 means to evaluate just the function and no derivatives

Output Parameter:

• p - an array containing the evaluations of the PKD polynomials' jets on the points. The size is ((dim + degree)

choose dim) x ((dim + k) choose dim) x npoints, which also describes the order of the dimensions of this three-dimensional array: the first (slowest varying) dimension is basis function index; the second dimension is jet index; the third (fastest varying) dimension is the index of the evaluation point.

Level: advanced

See also: PetscDTGradedOrderToIndex(), PetscDTIndexToGradedOrder(), PetscDTJacobiEvalJet()

External Links

• PETSc Manual: DT/PetscDTPKDEvalJet

PetscDTPTrimmedEvalJet(petsclib::PetscLibType, dim::PetscInt, npoints::PetscInt, points::Vector{PetscReal}, degree::PetscInt, formDegree::PetscInt, jetDegree::PetscInt, p::Vector{PetscReal})

Evaluate the jet (function and derivatives) of a basis of the trimmed polynomial k-forms up to a given degree.

Input Parameters:

• dim - the number of variables in the multivariate polynomials
• npoints - the number of points to evaluate the polynomials at
• points - [npoints x dim] array of point coordinates
• degree - the degree (sum of degrees on the variables in a monomial) of the trimmed polynomial space to evaluate.

There are ((dim + degree) choose (dim + formDegree)) x ((degree + formDegree - 1) choose (formDegree)) polynomials in this space. (You can use PetscDTPTrimmedSize() to compute this size.)

• formDegree - the degree of the form
• jetDegree - the maximum order partial derivative to evaluate in the jet. There are ((dim + jetDegree) choose dim) partial derivatives

in the jet. Choosing jetDegree = 0 means to evaluate just the function and no derivatives

Output Parameter:

• p - an array containing the evaluations of the PKD polynomials' jets on the points.

Level: advanced

See also: PetscDTPKDEvalJet(), PetscDTPTrimmedSize()

External Links

• PETSc Manual: DT/PetscDTPTrimmedEvalJet

size::PetscInt = PetscDTPTrimmedSize(petsclib::PetscLibType, dim::PetscInt, degree::PetscInt, formDegree::PetscInt)

The size of the trimmed polynomial space of k-forms with a given degree and form degree, which can be evaluated in PetscDTPTrimmedEvalJet().

Input Parameters:

• dim - the number of variables in the multivariate polynomials
• degree - the degree (sum of degrees on the variables in a monomial) of the trimmed polynomial space.
• formDegree - the degree of the form

Output Parameter:

• size - The number ((dim + degree) choose (dim + formDegree)) x ((degree + formDegree - 1) choose (formDegree))

Level: advanced

See also: PetscDTPTrimmedEvalJet()

External Links

• PETSc Manual: DT/PetscDTPTrimmedSize

PetscDTReconstructPoly(petsclib::PetscLibType, degree::PetscInt, nsource::PetscInt, sourcex::Vector{PetscReal}, ntarget::PetscInt, targetx::Vector{PetscReal}, R::Vector{PetscReal})

create matrix representing polynomial reconstruction using cell intervals and evaluation at target intervals

Not Collective

Input Parameters:

• degree - degree of reconstruction polynomial
• nsource - number of source intervals
• sourcex - sorted coordinates of source cell boundaries (length nsource+1)
• ntarget - number of target intervals
• targetx - sorted coordinates of target cell boundaries (length ntarget+1)

Output Parameter:

• R - reconstruction matrix, utarget = sum_s R[t*nsource+s] * usource[s]

Level: advanced

See also: PetscDTLegendreEval()

External Links

• PETSc Manual: DT/PetscDTReconstructPoly

quad::PetscQuadrature = PetscDTSimplexQuadrature(petsclib::PetscLibType, dim::PetscInt, degree::PetscInt, type::PetscDTSimplexQuadratureType)

Create a quadrature rule for a simplex that exactly integrates polynomials up to a given degree.

Not Collective

Input Parameters:

• dim - The spatial dimension of the simplex (1 = segment, 2 = triangle, 3 = tetrahedron)
• degree - The largest polynomial degree that is required to be integrated exactly
• type - PetscDTSimplexQuadratureType indicating the type of quadrature rule

Output Parameter:

• quad - A PetscQuadrature object for integration over the biunit simplex

(defined by the bounds xi >= -1 and \sumi x_i <= 2 - d) that is exact for polynomials up to the given degree

Level: intermediate

See also: PetscDTSimplexQuadratureType, PetscDTGaussQuadrature(), PetscDTStroudCononicalQuadrature(), PetscQuadrature

External Links

• PETSc Manual: DT/PetscDTSimplexQuadrature

q::PetscQuadrature = PetscDTStroudConicalQuadrature(petsclib::PetscLibType, dim::PetscInt, Nc::PetscInt, npoints::PetscInt, a::PetscReal, b::PetscReal)

create Stroud conical quadrature for a simplex {cite}karniadakis2005spectral

Not Collective

Input Parameters:

• dim - The simplex dimension
• Nc - The number of components
• npoints - The number of points in one dimension
• a - left end of interval (often-1)
• b - right end of interval (often +1)

Output Parameter:

• q - A PetscQuadrature object

Level: intermediate

See also: PetscDTGaussTensorQuadrature(), PetscDTGaussQuadrature()

External Links

• PETSc Manual: DT/PetscDTStroudConicalQuadrature

sol::PetscReal = PetscDTTanhSinhIntegrate(petsclib::PetscLibType, func::external, a::PetscReal, b::PetscReal, digits::PetscInt, ctx::Ptr{Cvoid})

Approximate \int_a^b f(x)\,dx to a requested precision using adaptive tanh-sinh (double-exponential) quadrature

Not Collective; No Fortran Support

Input Parameters:

• func - the integrand callback (func(x, ctx, &value) evaluates the integrand at point x)
• a - lower limit of integration
• b - upper limit of integration
• digits - target number of correct decimal digits
• ctx - optional application context passed to func

Output Parameter:

• sol - the approximate value of the integral

Level: developer

See also: PetscDTTanhSinhIntegrateMPFR(), PetscDTGaussQuadrature()

External Links

• PETSc Manual: DT/PetscDTTanhSinhIntegrate

sol::PetscReal = PetscDTTanhSinhIntegrateMPFR(petsclib::PetscLibType, func::external, a::PetscReal, b::PetscReal, digits::PetscInt, ctx::Ptr{Cvoid})

High-precision version of PetscDTTanhSinhIntegrate() that uses the MPFR arbitrary-precision library to evaluate the quadrature

Not Collective; No Fortran Support

Input Parameters:

• func - the integrand callback (func(x, ctx, &value) evaluates the integrand at point x)
• a - lower limit of integration
• b - upper limit of integration
• digits - target number of correct decimal digits (also drives the working MPFR precision)
• ctx - optional application context passed to func

Output Parameter:

• sol - the approximate value of the integral

Level: developer

See also: PetscDTTanhSinhIntegrate(), PetscDTGaussQuadrature()

External Links

• PETSc Manual: DT/PetscDTTanhSinhIntegrateMPFR

q::PetscQuadrature = PetscDTTanhSinhTensorQuadrature(petsclib::PetscLibType, dim::PetscInt, level::PetscInt, a::PetscReal, b::PetscReal)

create tanh-sinh quadrature for a tensor product cell

Not Collective

Input Parameters:

• dim - The cell dimension
• level - The number of points in one dimension, 2^l
• a - left end of interval (often-1)
• b - right end of interval (often +1)

Output Parameter:

• q - A PetscQuadrature object

Level: intermediate

See also: PetscDTGaussTensorQuadrature(), PetscQuadrature

External Links

• PETSc Manual: DT/PetscDTTanhSinhTensorQuadrature

q::PetscQuadrature = PetscDTTensorQuadratureCreate(petsclib::PetscLibType, q1::PetscQuadrature, q2::PetscQuadrature)

create the tensor product quadrature from two lower-dimensional quadratures

Not Collective

Input Parameters:

• q1 - The first quadrature
• q2 - The second quadrature

Output Parameter:

• q - A PetscQuadrature object

Level: intermediate

See also: PetscQuadrature, PetscDTGaussTensorQuadrature()

External Links

• PETSc Manual: DT/PetscDTTensorQuadratureCreate

name::String = PetscDemangleSymbol(petsclib::PetscLibType, mangledName::String)

Convert a C++-mangled symbol name to its human-readable form using abi::__cxa_demangle() when available

Not Collective

Input Parameter:

• mangledName - the mangled symbol name (typically obtained from dladdr())

Output Parameter:

• name - newly-allocated, null-terminated demangled name; caller must PetscFree() it

Level: developer

See also: PetscStackView(), PetscStackPrint()

External Links

• PETSc Manual: Sys/PetscDemangleSymbol

PetscDetermineInitialFPTrap(petsclib::PetscLibType)

Attempts to determine the floating point trapping that exists when PetscInitialize() is called

Not Collective

See also: PetscFPTrapPush(), PetscFPTrapPop(), PetscDetermineInitialFPTrap()

External Links

• PETSc Manual: Sys/PetscDetermineInitialFPTrap

value::PetscInt,found::PetscBool = PetscEListFind(petsclib::PetscLibType, n::PetscInt, list::Cchar, str::String)

searches list of strings for given string, using case insensitive matching

Not Collective; No Fortran Support

Input Parameters:

• n - number of strings in
• list - list of strings to search
• str - string to look for, empty string "" accepts default (first entry in list)

Output Parameters:

• value - index of matching string (if found)
• found - boolean indicating whether string was found (can be NULL)

Level: developer

See also: PetscEnumFind()

External Links

• PETSc Manual: Sys/PetscEListFind

PetscElementalFinalizePackage(petsclib::PetscLibType)

External Links

• PETSc Manual: Sys/PetscElementalFinalizePackage

PetscElementalInitializePackage(petsclib::PetscLibType)

External Links

• PETSc Manual: Sys/PetscElementalInitializePackage

isInitialized::PetscBool = PetscElementalInitialized(petsclib::PetscLibType)

External Links

• PETSc Manual: Sys/PetscElementalInitialized

PetscEmacsClientErrorHandler(petsclib::PetscLibType, comm::MPI_Comm, line::Cint, fun::String, file::String, n::PetscErrorCode, p::PetscErrorType, mess::String, ctx::Ptr{Cvoid})

Error handler that uses the emacsclient program to load the file where the error occurred. Then calls the "previous" error handler.

Not Collective, No Fortran Support

Input Parameters:

• comm - communicator over which error occurred
• line - the line number of the error (usually indicated by __LINE__ in the calling routine)
• file - the file in which the error was detected (usually indicated by __FILE__ in the calling routine)
• fun - the function name of the calling routine
• mess - an error text string, usually just printed to the screen
• n - the generic error number
• p - PETSC_ERROR_INITIAL indicates this is the first time the error handler is being called while PETSC_ERROR_REPEAT indicates it was previously called
• ctx - error handler context

Options Database Key:

• -on_error_emacs machinename - will contact machinename to open the Emacs client there

Level: developer

See also: PetscError(), PetscPushErrorHandler(), PetscPopErrorHandler(), PetscAttachDebuggerErrorHandler(), PetscAbortErrorHandler(), PetscMPIAbortErrorHandler(), PetscTraceBackErrorHandler(), PetscReturnErrorHandler(), PetscErrorType, PETSC_ERROR_INITIAL, PETSC_ERROR_REPEAT, PetscErrorCode

External Links

• PETSc Manual: Sys/PetscEmacsClientErrorHandler

PetscEnd(petsclib::PetscLibType)

Calls PetscFinalize() and then ends the program. This is useful if one wishes a clean exit somewhere deep in the program.

Collective on PETSC_COMM_WORLD

Level: advanced

See also: PetscInitialize(), PetscOptionsView(), PetscMallocDump(), PetscMPIDump(), PetscFinalize()

External Links

• PETSc Manual: Sys/PetscEnd

value::PetscEnum,found::PetscBool = PetscEnumFind(petsclib::PetscLibType, enumlist::Cchar, str::String)

searches enum list of strings for given string, using case insensitive matching

Not Collective; No Fortran Support

Input Parameters:

• enumlist - list of strings to search, followed by enum name, then enum prefix, then NULL
• str - string to look for

Output Parameters:

• value - index of matching string (if found)
• found - boolean indicating whether string was found (can be NULL)

Level: advanced

See also: PetscEListFind()

External Links

• PETSc Manual: Sys/PetscEnumFind

text::String,specific::String = PetscErrorMessage(petsclib::PetscLibType, errnum::PetscErrorCode)

Returns the text string associated with a PETSc error code.

Not Collective, No Fortran Support

Input Parameter:

• errnum - the error code

Output Parameters:

• text - the error message (NULL if not desired)
• specific - the specific error message that was set with SETERRQ() or

PetscError(). (NULL if not desired)

Level: developer

See also: PetscErrorCode, PetscPushErrorHandler(), PetscAttachDebuggerErrorHandler(), PetscError(), SETERRQ(), PetscCall(), PetscAbortErrorHandler(), PetscTraceBackErrorHandler()

External Links

• PETSc Manual: Sys/PetscErrorMessage

PetscErrorPrintfInitialize(petsclib::PetscLibType)

Cache the architecture, host name, user name, program name and date so that PETSc's error-traceback printer does not need to make system calls from inside a signal handler

Collective

Level: developer

See also: PetscErrorPrintf, PetscTraceBackErrorHandler(), PetscPushErrorHandler()

External Links

• PETSc Manual: Sys/PetscErrorPrintfInitialize

PetscFClose(petsclib::PetscLibType, comm::MPI_Comm, fd::Libc.FILE)

Has MPI rank 0 in the communicator close a file (usually obtained with PetscFOpen(); all others do nothing.

Logically Collective

Input Parameters:

• comm - the MPI communicator
• fd - the file, opened with PetscFOpen()

Level: developer

See also: PetscFOpen()

External Links

• PETSc Manual: Sys/PetscFClose

PetscFFlush(petsclib::PetscLibType, fd::Libc.FILE)

Flush a file stream

Input Parameter:

• fd - The file stream handle

Level: intermediate

See also: PetscPrintf(), PetscFPrintf(), PetscVFPrintf(), PetscVSNPrintf()

External Links

• PETSc Manual: Sys/PetscFFlush

fp::Ptr{Libc.FILE} = PetscFOpen(petsclib::PetscLibType, comm::MPI_Comm, name::String, mode::String)

Has the first process in the MPI communicator open a file; all others do nothing.

Logically Collective

Input Parameters:

• comm - the MPI communicator
• name - the filename
• mode - the mode for fopen(), usually "w"

Output Parameter:

• fp - the file pointer

Level: developer

See also: PetscFClose(), PetscSynchronizedFGets(), PetscSynchronizedPrintf(), PetscSynchronizedFlush(), PetscFPrintf()

External Links

• PETSc Manual: Sys/PetscFOpen

PetscFPTrapPop(petsclib::PetscLibType)

push a floating point trapping mode, to be restored using PetscFPTrapPop()

Not Collective

Level: advanced

See also: PetscFPTrapPush(), PetscSetFPTrap(), PetscDetermineInitialFPTrap()

External Links

• PETSc Manual: Sys/PetscFPTrapPop

PetscFPTrapPush(petsclib::PetscLibType, trap::PetscFPTrap)

push a floating point trapping mode, restored using PetscFPTrapPop()

Not Collective

Input Parameter:

• trap - PETSC_FP_TRAP_ON or PETSC_FP_TRAP_OFF or any of the values passable to PetscSetFPTrap()

Level: advanced

See also: PetscFPTrapPop(), PetscSetFPTrap(), PetscDetermineInitialFPTrap()

External Links

• PETSc Manual: Sys/PetscFPTrapPush

found::PetscBool = PetscFileRetrieve(petsclib::PetscLibType, comm::MPI_Comm, url::String, localname::String, llen::Csize_t)

Obtains a file from a URL or a compressed file and copies into local disk space as uncompressed.

Collective

Input Parameters:

• comm - processors accessing the file
• url - name of file, including entire URL (with or without .gz)
• llen - length of localname

Output Parameters:

• localname - name of local copy of file - valid on only process zero
• found - if found or retrieved the file - valid on all processes

Level: developer

See also: PetscDLLibraryRetrieve()

External Links

• PETSc Manual: Sys/PetscFileRetrieve

PetscFinalize(petsclib::PetscLibType)

Checks for options to be called at the conclusion of a PETSc program and frees any remaining PETSc objects and data structures. of the program. Automatically calls MPI_Finalize() if the user had not called MPI_Init() before calling PetscInitialize().

Collective on PETSC_COMM_WORLD

Options Database Keys:

• -options_view - Calls PetscOptionsView() to display all options in the database
• -options_left - Prints unused options that remain in the database (default value is true)
• -objects_dump [all] - Prints list of objects allocated by the user that have not been freed, the option all cause all outstanding objects to be listed
• -mpidump - Calls PetscMPIDump()
• -malloc_dump [filename] - Calls PetscMallocDump(), displays all memory allocated that has not been freed
• -memory_view - Prints total memory usage
• -malloc_view [filename] - Prints list of all memory allocated and in what functions

Level: beginner

See also: PetscInitialize(), PetscOptionsView(), PetscMallocDump(), PetscMPIDump(), PetscEnd()

External Links

• PETSc Manual: Sys/PetscFinalize

isFinalized::PetscBool = PetscFinalized(petsclib::PetscLibType)

Determine whether PetscFinalize() has been called yet

Output Parameter:

• isFinalized - PETSC_TRUE if PETSc is finalized, PETSC_FALSE otherwise

Level: developer

See also: PetscInitialize(), PetscInitializeNoArguments(), PetscInitializeFortran()

External Links

• PETSc Manual: Sys/PetscFinalized

loc::PetscCount = PetscFindCount(petsclib::PetscLibType, key::PetscCount, n::PetscCount, X::Vector{PetscCount})

Finds the location of a PetscCount key in a sorted array of PetscCount

Not Collective

Input Parameters:

• key - the PetscCount key to locate
• n - number of values in the array
• X - array of PetscCount

Output Parameter:

• loc - the location if found, otherwise -(slot+1) where slot is the place the value would go

Level: intermediate

See also: PetscCount, PetscSortCount()

External Links

• PETSc Manual: Sys/PetscFindCount

loc::PetscInt = PetscFindInt(petsclib::PetscLibType, key::PetscInt, n::PetscCount, X::Vector{PetscInt})

Finds the location of a PetscInt key in a sorted array of PetscInt

Not Collective

Input Parameters:

• key - the PetscInt key to locate
• n - number of values in the array
• X - array of PetscInt

Output Parameter:

• loc - the location if found, otherwise -(slot+1) where slot is the place the value would go

Level: intermediate

See also: PetscIntSortSemiOrdered(), PetscSortInt(), PetscSortIntWithArray(), PetscSortRemoveDupsInt()

External Links

• PETSc Manual: Sys/PetscFindInt

loc::PetscInt = PetscFindMPIInt(petsclib::PetscLibType, key::PetscMPIInt, n::PetscCount, X::Vector{PetscMPIInt})

Finds PetscMPIInt in a sorted array of PetscMPIInt

Not Collective

Input Parameters:

• key - the integer to locate
• n - number of values in the array
• X - array of PetscMPIInt

Output Parameter:

• loc - the location if found, otherwise -(slot+1) where slot is the place the value would go

Level: intermediate

See also: PetscMPIIntSortSemiOrdered(), PetscSortInt(), PetscSortIntWithArray(), PetscSortRemoveDupsInt()

External Links

• PETSc Manual: Sys/PetscFindMPIInt

loc::PetscInt = PetscFindReal(petsclib::PetscLibType, key::PetscReal, n::PetscCount, t::Vector{PetscReal}, eps::PetscReal)

Finds a PetscReal in a sorted array of PetscReals

Not Collective

Input Parameters:

• key - the value to locate
• n - number of values in the array
• t - array of values
• eps - tolerance used to compare

Output Parameter:

• loc - the location if found, otherwise -(slot+1) where slot is the place the value would go

Level: intermediate

See also: PetscSortReal(), PetscSortRealWithArrayInt()

External Links

• PETSc Manual: Sys/PetscFindReal

PetscFixFilename(petsclib::PetscLibType, filein::String, fileout::String)

Fixes a file name so that it is correct for both Unix and Microsoft Windows by using the correct / or \ to separate directories.

Not Collective

Input Parameter:

• filein - name of file to be fixed

Output Parameter:

• fileout - the fixed name. Should long enough to hold the filename.

Level: developer

See also: PetscFOpen()

External Links

• PETSc Manual: Sys/PetscFixFilename

PetscFormKeySort(petsclib::PetscLibType, n::PetscInt, arr::Vector{PetscFormKey})

Sorts an array of PetscFormKey in place in increasing order.

Not Collective

Input Parameters:

• n - number of values
• arr - array of PetscFormKey

Level: intermediate

See also: PetscFormKey, PetscIntSortSemiOrdered(), PetscSortInt()

External Links

• PETSc Manual: DT/PetscFormKeySort

PetscFormatConvert(petsclib::PetscLibType, format::String, newformat::String)

converts %g to [|%g|] so that PetscVSNPrintf() can ensure all %g formatted numbers have a decimal point when printed.

No Fortran Support

Input Parameter:

• format - the PETSc format string

Output Parameter:

• newformat - the formatted string, must be long enough to hold result

Level: developer

See also: PetscFormatConvertGetSize(), PetscVSNPrintf(), PetscVFPrintf()

External Links

• PETSc Manual: Sys/PetscFormatConvert

size::Csize_t = PetscFormatConvertGetSize(petsclib::PetscLibType, format::String)

Gets the length of a string needed to hold data converted with PetscFormatConvert() based on the format

No Fortran Support

Input Parameter:

• format - the PETSc format string

Output Parameter:

• size - the needed length of the new format

Level: developer

See also: PetscFormatConvert(), PetscVSNPrintf(), PetscVFPrintf()

External Links

• PETSc Manual: Sys/PetscFormatConvertGetSize

PetscFormatRealArray(petsclib::PetscLibType, buf::String, len::Csize_t, fmt::String, n::PetscInt, x::Vector{PetscReal})

Format an array of PetscReal values as a comma-separated string using a printf-style format

Not Collective; No Fortran Support

Input Parameters:

• len - the length of the output buffer in bytes
• fmt - the printf-style format string applied to each element (e.g. "%g")
• n - number of values in x
• x - array of PetscReal values to format

Output Parameter:

• buf - the formatted, null-terminated string

Level: developer

See also: PetscSNPrintf(), PetscViewerASCIIPrintf()

External Links

• PETSc Manual: Sys/PetscFormatRealArray

args::String = PetscFreeArguments(petsclib::PetscLibType)

Frees the memory obtained with PetscGetArguments()

Not Collective, No Fortran Support

Output Parameter:

• args - the command line arguments

Level: intermediate

See also: PetscFinalize(), PetscInitializeFortran(), PetscGetArgs(), PetscGetArguments()

External Links

• PETSc Manual: Sys/PetscFreeArguments

onodes::Ptr{PetscMPIInt},olengths::Ptr{PetscMPIInt} = PetscGatherMessageLengths(petsclib::PetscLibType, comm::MPI_Comm, nsends::PetscMPIInt, nrecvs::PetscMPIInt, ilengths::Vector{PetscMPIInt})

Computes information about messages that an MPI rank will receive, including (from-id,length) pairs for each message.

Collective, No Fortran Support

Input Parameters:

• comm - Communicator
• nsends - number of messages that are to be sent.
• nrecvs - number of messages being received
• ilengths - an array of integers of length sizeof(comm)

a non zero ilengths[i] represent a message to i of length ilengths[i]

Output Parameters:

• onodes - list of ranks from which messages are expected
• olengths - corresponding message lengths

Level: developer

See also: PetscGatherNumberOfMessages(), PetscGatherMessageLengths2(), PetscCommBuildTwoSided()

External Links

• PETSc Manual: Sys/PetscGatherMessageLengths

onodes::Ptr{PetscMPIInt},olengths1::Ptr{PetscMPIInt},olengths2::Ptr{PetscMPIInt} = PetscGatherMessageLengths2(petsclib::PetscLibType, comm::MPI_Comm, nsends::PetscMPIInt, nrecvs::PetscMPIInt, ilengths1::Vector{PetscMPIInt}, ilengths2::Vector{PetscMPIInt})

Computes info about messages that a MPI rank will receive, including (from-id,length) pairs for each message. Same functionality as PetscGatherMessageLengths() except it takes TWO ilenths and output TWO olengths.

Collective, No Fortran Support

Input Parameters:

• comm - Communicator
• nsends - number of messages that are to be sent.
• nrecvs - number of messages being received
• ilengths1 - first array of integers of length sizeof(comm)
• ilengths2 - second array of integers of length sizeof(comm)

Output Parameters:

• onodes - list of ranks from which messages are expected
• olengths1 - first corresponding message lengths
• olengths2 - second message lengths

Level: developer

See also: PetscGatherMessageLengths(), PetscGatherNumberOfMessages(), PetscCommBuildTwoSided()

External Links

• PETSc Manual: Sys/PetscGatherMessageLengths2

nrecvs::PetscMPIInt = PetscGatherNumberOfMessages(petsclib::PetscLibType, comm::MPI_Comm, iflags::Vector{PetscMPIInt}, ilengths::Vector{PetscMPIInt})

Computes the number of messages an MPI rank expects to receive during a neighbor communication

Collective, No Fortran Support

Input Parameters:

• comm - Communicator
• iflags - an array of integers of length sizeof(comm). A '1' in ilengths[i] represent a

message from current node to ith node. Optionally NULL

• ilengths - Non zero ilengths[i] represent a message to i of length ilengths[i].

Optionally NULL.

Output Parameter:

• nrecvs - number of messages received

Level: developer

See also: PetscGatherMessageLengths(), PetscGatherMessageLengths2(), PetscCommBuildTwoSided()

External Links

• PETSc Manual: Sys/PetscGatherNumberOfMessages

AA::Ptr{PetscReal} = PetscGaussLobattoLegendreElementAdvectionCreate(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal})

computes the advection operator for a single 1d GLL element

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, of length n
• weights - the GLL weights, of length n

Output Parameter:

• AA - the stiffness element, of dimension n by n

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementLaplacianCreate(), PetscGaussLobattoLegendreElementAdvectionDestroy()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementAdvectionCreate

PetscGaussLobattoLegendreElementAdvectionDestroy(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal}, AA::PetscReal)

frees the advection stiffness for a single 1d GLL element created with PetscGaussLobattoLegendreElementAdvectionCreate()

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, ignored
• weights - the GLL weights, ignored
• AA - advection obtained with PetscGaussLobattoLegendreElementAdvectionCreate()

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementAdvectionCreate()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementAdvectionDestroy

AA::Ptr{PetscReal},AAT::Ptr{PetscReal} = PetscGaussLobattoLegendreElementGradientCreate(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal})

computes the gradient for a single 1d GLL element

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, of length n
• weights - the GLL weights, of length n

Output Parameters:

• AA - the stiffness element, of dimension n by n
• AAT - the transpose of AA (pass in NULL if you do not need this array), of dimension n by n

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementLaplacianDestroy(), PetscGaussLobattoLegendreElementGradientDestroy()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementGradientCreate

PetscGaussLobattoLegendreElementGradientDestroy(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal}, AA::PetscReal, AAT::PetscReal)

frees the gradient for a single 1d GLL element obtained with PetscGaussLobattoLegendreElementGradientCreate()

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, ignored
• weights - the GLL weights, ignored
• AA - the stiffness element obtained with PetscGaussLobattoLegendreElementGradientCreate()
• AAT - the transpose of the element obtained with PetscGaussLobattoLegendreElementGradientCreate()

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementLaplacianCreate(), PetscGaussLobattoLegendreElementAdvectionCreate()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementGradientDestroy

AA::Ptr{PetscReal} = PetscGaussLobattoLegendreElementLaplacianCreate(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal})

computes the Laplacian for a single 1d GLL element

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, of length n
• weights - the GLL weights, of length n

Output Parameter:

• AA - the stiffness element, of size n by n

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementLaplacianDestroy()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementLaplacianCreate

PetscGaussLobattoLegendreElementLaplacianDestroy(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal}, AA::PetscReal)

frees the Laplacian for a single 1d GLL element created with PetscGaussLobattoLegendreElementLaplacianCreate()

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes, ignored
• weights - the GLL weightss, ignored
• AA - the stiffness element from PetscGaussLobattoLegendreElementLaplacianCreate()

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementLaplacianCreate()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementLaplacianDestroy

nodes::PetscReal,weights::PetscReal,AA::Ptr{PetscReal} = PetscGaussLobattoLegendreElementMassCreate(petsclib::PetscLibType, n::PetscInt)

Build the elemental mass matrix for a single 1D Gauss-Lobatto-Legendre (GLL) spectral element

Not Collective; No Fortran Support

Input Parameters:

• n - number of GLL nodes
• nodes - the GLL quadrature nodes
• weights - the GLL quadrature weights

Output Parameter:

• AA - newly allocated n x n mass matrix as PetscReal **

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature(), PetscGaussLobattoLegendreElementMassDestroy(), PetscGaussLobattoLegendreElementLaplacianCreate(), PetscGaussLobattoLegendreElementAdvectionCreate()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementMassCreate

nodes::PetscReal,weights::PetscReal = PetscGaussLobattoLegendreElementMassDestroy(petsclib::PetscLibType, n::PetscInt, AA::PetscReal)

Free a 1D GLL elemental mass matrix created with PetscGaussLobattoLegendreElementMassCreate()

Not Collective; No Fortran Support

Input Parameters:

• n - number of GLL nodes (ignored)
• nodes - the GLL quadrature nodes (ignored)
• weights - the GLL quadrature weights (ignored)
• AA - the mass matrix to free; *AA is set to NULL on return

Level: beginner

See also: PetscGaussLobattoLegendreElementMassCreate(), PetscDTGaussLobattoLegendreQuadrature()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreElementMassDestroy

in::PetscReal = PetscGaussLobattoLegendreIntegrate(petsclib::PetscLibType, n::PetscInt, nodes::Vector{PetscReal}, weights::Vector{PetscReal}, f::Vector{PetscReal})

Compute the L2 integral of a function on the GLL points

Not Collective

Input Parameters:

• n - the number of GLL nodes
• nodes - the GLL nodes
• weights - the GLL weights
• f - the function values at the nodes

Output Parameter:

• in - the value of the integral

Level: beginner

See also: PetscDTGaussLobattoLegendreQuadrature()

External Links

• PETSc Manual: DT/PetscGaussLobattoLegendreIntegrate

PetscGetArchType(petsclib::PetscLibType, str::String, slen::Csize_t)

Returns the PETSC_ARCH that was used for this configuration of PETSc

Not Collective

Input Parameter:

• slen - length of string buffer

Output Parameter:

• str - string area to contain architecture name, should be at least 10 characters long. Name is truncated if string is not long enough.

Level: developer

See also: PetscGetUserName(), PetscGetHostName()

External Links

• PETSc Manual: Sys/PetscGetArchType

argc::Cint,args::String = PetscGetArgs(petsclib::PetscLibType)

Allows you to access the raw command line arguments anywhere after PetscInitialize() is called but before PetscFinalize().

Not Collective, No Fortran Support

Output Parameters:

• argc - count of the number of command line arguments
• args - the command line arguments

Level: intermediate

See also: PetscFinalize(), PetscInitializeFortran(), PetscGetArguments(), PetscInitialize()

External Links

• PETSc Manual: Sys/PetscGetArgs

args::String = PetscGetArguments(petsclib::PetscLibType)

Allows you to access the command line arguments anywhere after PetscInitialize() is called but before PetscFinalize().

Not Collective, No Fortran Support

Output Parameter:

• args - the command line arguments

Level: intermediate

See also: PetscFinalize(), PetscInitializeFortran(), PetscGetArgs(), PetscFreeArguments(), PetscInitialize()

External Links

• PETSc Manual: Sys/PetscGetArguments

t::PetscLogDouble = PetscGetCPUTime(petsclib::PetscLibType)

Returns the CPU time in seconds used by the process.

Not Collective

Output Parameter:

• t - Time in seconds charged to the process.

Example: `` #include <petscsys.h> -.. PetscLogDouble t1, t2;

PetscCall(PetscGetCPUTime(&t1)); -.. code to time ... PetscCall(PetscGetCPUTime(&t2)); printf("Code took %f CPU seconds\n", t2-t1); ``

Level: intermediate

See also: PetscTime(), PetscLogView()

External Links

• PETSc Manual: Sys/PetscGetCPUTime

PetscGetCurrentCUDAStream(petsclib::PetscLibType, stream::cudaStream_t)

External Links

• PETSc Manual: Sys/PetscGetCurrentCUDAStream

PetscGetCurrentHIPStream(petsclib::PetscLibType, stream::hipStream_t)

External Links

• PETSc Manual: Sys/PetscGetCurrentHIPStream

PetscGetDate(petsclib::PetscLibType, date::String, len::Csize_t)

Gets the current date.

Not Collective

Input Parameter:

• len - length of string to hold date

Output Parameter:

• date - the date

Level: beginner

See also: PetscGetHostName()

External Links

• PETSc Manual: Sys/PetscGetDate

PetscGetDisplay(petsclib::PetscLibType, display::String, n::Csize_t)

Gets the X windows display variable for all processors.

Input Parameter:

• n - length of string display

Output Parameter:

• display - the display string

Options Database Keys:

• -display display - sets the display to use
• -x_virtual - forces use of a X virtual display Xvfb that will not display anything but -draw_save will still work. Xvfb is automatically

started up in PetscSetDisplay() with this option

Level: advanced

See also: PETSC_DRAW_X, PetscDrawOpenX()

External Links

• PETSc Manual: Sys/PetscGetDisplay

flops::PetscLogDouble = PetscGetFlops(petsclib::PetscLibType)

Returns the number of flops used on this processor since the program began.

Not Collective

Output Parameter:

• flops - number of floating point operations

Level: intermediate

See also: PetscLogGpuFlops(), PetscTime(), PetscLogFlops()

External Links

• PETSc Manual: Log/PetscGetFlops

PetscGetFullPath(petsclib::PetscLibType, path::String, fullpath::String, flen::Csize_t)

Given a filename, returns the fully qualified file name.

Not Collective

Input Parameters:

• path - pathname to qualify
• flen - size of fullpath

Output Parameter:

• fullpath - buffer to hold the full pathname

Level: developer

See also: PetscGetRelativePath()

External Links

• PETSc Manual: Sys/PetscGetFullPath

PetscGetHomeDirectory(petsclib::PetscLibType, dir::String, maxlen::Csize_t)

Returns the name of the user's home directory

Not Collective

Input Parameter:

• maxlen - maximum length allowed

Output Parameter:

• dir - contains the home directory. Must be long enough to hold the name.

Level: developer

See also: PetscGetTmp(), PetscSharedTmp(), PetscGetWorkingDirectory()

External Links

• PETSc Manual: Sys/PetscGetHomeDirectory

PetscGetHostName(petsclib::PetscLibType, name::String, nlen::Csize_t)

Returns the name of the host. This attempts to return the entire Internet name. It may not return the same name as MPI_Get_processor_name().

Not Collective

Input Parameter:

• nlen - length of name

Output Parameter:

• name - contains host name. Must be long enough to hold the name

This is the fully qualified name, including the domain.

Level: developer

See also: PetscGetUserName(), PetscGetArchType()

External Links

• PETSc Manual: Sys/PetscGetHostName

type::PetscMemType = PetscGetMemType(petsclib::PetscLibType, ptr::Ptr{Cvoid})

Query the PetscMemType of a pointer

Not Collective, No Fortran Support

Input Parameter:

• ptr - The pointer to query (may be NULL)

Output Parameter:

• type - The PetscMemType of the pointer

Level: intermediate

See also: PetscMemType, PetscDeviceMalloc(), PetscDeviceCalloc(), PetscDeviceFree(), PetscDeviceArrayCopy(), PetscDeviceArrayZero()

External Links

• PETSc Manual: Sys/PetscGetMemType

dir::String = PetscGetPetscDir(petsclib::PetscLibType)

Gets the directory PETSc is installed in

Not Collective; No Fortran Support

Output Parameter:

• dir - the directory

Level: developer

See also: PetscGetArchType()

External Links

• PETSc Manual: Sys/PetscGetPetscDir

PetscGetProgramName(petsclib::PetscLibType, name::String, len::Csize_t)

Gets the name of the running program.

Not Collective

Input Parameter:

• len - length of the string name

Output Parameter:

• name - the name of the running program, provide a string of length PETSC_MAX_PATH_LEN

Level: advanced

See also: PetscFinalize(), PetscInitializeFortran(), PetscGetArguments(), PetscInitialize()

External Links

• PETSc Manual: Sys/PetscGetProgramName

PetscGetRealPath(petsclib::PetscLibType, path::String, rpath::String)

Get the path without symbolic links etc. in absolute form.

Not Collective

Input Parameter:

• path - path to resolve

Output Parameter:

• rpath - resolved path

Level: developer

See also: PetscGetFullPath()

External Links

• PETSc Manual: Sys/PetscGetRealPath

PetscGetRelativePath(petsclib::PetscLibType, fullpath::String, path::String, flen::Csize_t)

Given a filename, returns the relative path (removes all directory specifiers).

Not Collective; No Fortran Support

Input Parameters:

• fullpath - full pathname
• flen - size of path

Output Parameter:

• path - buffer that holds relative pathname

Level: developer

See also: PetscGetFullPath()

External Links

• PETSc Manual: Sys/PetscGetRelativePath

PetscGetTmp(petsclib::PetscLibType, comm::MPI_Comm, dir::String, len::Csize_t)

Gets the name of the "tmp" directory, often this is /tmp

Collective

Input Parameters:

• comm - MPI_Communicator that may share tmp
• len - length of string to hold name

Output Parameter:

• dir - directory name

Environmental Variables:

• PETSC_SHARED_TMP - indicates the directory is known to be shared among the MPI processes
• PETSC_NOT_SHARED_TMP - indicates the directory is known to be not shared among the MPI processes
• PETSC_TMP - name of the directory you wish to use as tmp

Level: developer

See also: PetscSharedTmp(), PetscSharedWorkingDirectory(), PetscGetWorkingDirectory(), PetscGetHomeDirectory()

External Links

• PETSc Manual: Sys/PetscGetTmp

PetscGetUserName(petsclib::PetscLibType, name::String, nlen::Csize_t)

Get the login name of the user running the program on the current MPI process

Not Collective

Input Parameter:

• nlen - length of the name buffer

Output Parameter:

• name - on output, holds the user name (null-terminated)

Level: developer

See also: PetscGetHostName(), PetscGetProgramName()

External Links

• PETSc Manual: Sys/PetscGetUserName

PetscGetVersion(petsclib::PetscLibType, version::String, len::Csize_t)

Gets the PETSc version information in a string.

Not Collective; No Fortran Support

Input Parameter:

• len - length of the string

Output Parameter:

• version - version string

Level: developer

See also: PetscGetProgramName(), PetscGetVersionNumber()

External Links

• PETSc Manual: Sys/PetscGetVersion

major::PetscInt,minor::PetscInt,subminor::PetscInt,release::PetscInt = PetscGetVersionNumber(petsclib::PetscLibType)

Gets the PETSc version information from the library

Not Collective

Output Parameters:

• major - the major version (optional, pass NULL if not requested)
• minor - the minor version (optional, pass NULL if not requested)
• subminor - the subminor version (patch number) (optional, pass NULL if not requested)
• release - indicates the library is from a release, not random git repository (optional, pass NULL if not requested)

Level: developer

See also: PetscGetProgramName(), PetscGetVersion(), PetscInitialize()

External Links

• PETSc Manual: Sys/PetscGetVersionNumber

PetscGetWorkingDirectory(petsclib::PetscLibType, path::String, len::Csize_t)

Gets the current working directory.

Not Collective

Input Parameter:

• len - maximum length of path

Output Parameter:

• path - holds the result value. The string should be long enough to hold the path, for example, PETSC_MAX_PATH_LEN

Level: developer

See also: PetscGetTmp(), PetscSharedTmp(), PetscSharedWorkingDirectory(), PetscGetHomeDirectory()

External Links

• PETSc Manual: Sys/PetscGetWorkingDirectory

PetscGlobalMinMaxInt(petsclib::PetscLibType, comm::MPI_Comm, minMaxVal::Vector{PetscInt}, minMaxValGlobal::Vector{PetscInt})

Get the global min/max from local min/max input

Collective

Input Parameters:

• comm - The MPI communicator to reduce with
• minMaxVal - An array with the local min and max

Output Parameter:

• minMaxValGlobal - An array with the global min and max

Level: beginner

See also: PetscSplitOwnership(), PetscGlobalMinMaxReal()

External Links

• PETSc Manual: Sys/PetscGlobalMinMaxInt

PetscGlobalMinMaxReal(petsclib::PetscLibType, comm::MPI_Comm, minMaxVal::Vector{PetscReal}, minMaxValGlobal::Vector{PetscReal})

Get the global min/max from local min/max input

Collective

Input Parameters:

• comm - The MPI communicator to reduce with
• minMaxVal - An array with the local min and max

Output Parameter:

• minMaxValGlobal - An array with the global min and max

Level: beginner

See also: PetscSplitOwnership(), PetscGlobalMinMaxInt()

External Links

• PETSc Manual: Sys/PetscGlobalMinMaxReal

PetscGlobusAuthorize(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, tokensize::Csize_t)

Get an access token allowing PETSc applications to make Globus file transfer requests

Not Collective, only the first process in MPI_Comm does anything

Input Parameters:

• comm - the MPI communicator
• tokensize - size of the token array

Output Parameter:

• access_token - can be used with PetscGlobusUpLoad() for 30 days

Level: intermediate

See also: PetscGoogleDriveRefresh(), PetscGoogleDriveUpload(), PetscGlobusUpload()

External Links

• PETSc Manual: Sys/PetscGlobusAuthorize

PetscGlobusGetTransfers(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, buff::String, buffsize::Csize_t)

Get a record of current transfers requested from Globus

Not Collective, only the first process in MPI_Comm does anything

Input Parameters:

• comm - the MPI communicator
• access_token - Globus access token, if NULL will check in options database for -globusaccesstoken XXX otherwise

will call PetscGlobusAuthorize().

• buffsize - size of the buffer

Output Parameter:

• buff - location to put Globus information

Level: intermediate

See also: PetscGoogleDriveRefresh(), PetscGoogleDriveUpload(), PetscGlobusUpload(), PetscGlobusAuthorize()

External Links

• PETSc Manual: Sys/PetscGlobusGetTransfers

PetscGlobusUpload(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, filename::String)

Loads a file to Globus

Not Collective, only the first process in the MPI_Comm uploads the file

Input Parameters:

• comm - MPI communicator
• access_token - obtained with PetscGlobusAuthorize(), pass NULL to use -globus_access_token XXX from the PETSc database
• filename - file to upload

Options Database Key:

• -globus_access_token XXX - the Globus token

Level: intermediate

See also: PetscGoogleDriveAuthorize(), PetscGoogleDriveRefresh(), PetscGlobusAuthorize()

External Links

• PETSc Manual: Sys/PetscGlobusUpload

PetscGoogleDriveAuthorize(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, refresh_token::String, tokensize::Csize_t)

Get authorization and refresh token for accessing Google drive from PETSc

Not Collective, only the first process in MPI_Comm does anything

Input Parameters:

• comm - the MPI communicator
• tokensize - size of the token arrays

Output Parameters:

• access_token - can be used with PetscGoogleDriveUpload() for this one session
• refresh_token - can be used for ever to obtain new access_tokens with PetscGoogleDriveRefresh(), guard this like a password

it gives access to your Google Drive

Level: intermediate

See also: PetscGoogleDriveRefresh(), PetscGoogleDriveUpload()

External Links

• PETSc Manual: Sys/PetscGoogleDriveAuthorize

PetscGoogleDriveRefresh(petsclib::PetscLibType, comm::MPI_Comm, refresh_token::String, access_token::String, tokensize::Csize_t)

Get a new authorization token for accessing Google drive from PETSc from a refresh token

Not Collective, only the first process in the MPI_Comm does anything

Input Parameters:

• comm - MPI communicator
• refresh_token - obtained with PetscGoogleDriveAuthorize(), if NULL PETSc will first look for one in the options data

if not found it will call PetscGoogleDriveAuthorize()

• tokensize - size of the output string access_token

Output Parameter:

• access_token - token that can be passed to PetscGoogleDriveUpload()

Options Database Key:

• -google_refresh_token XXX - where XXX was obtained from PetscGoogleDriveAuthorize()

Level: intermediate

See also: PetscGoogleDriveAuthorize(), PetscGoogleDriveUpload()

External Links

• PETSc Manual: Sys/PetscGoogleDriveRefresh

PetscGoogleDriveUpload(petsclib::PetscLibType, comm::MPI_Comm, access_token::String, filename::String)

Loads a file to the Google Drive

Not Collective, only the first process in the MPI_Comm uploads the file

Input Parameters:

• comm - MPI communicator
• access_token - obtained with PetscGoogleDriveRefresh(), pass NULL to have PETSc generate one
• filename - file to upload; if you upload multiple times it will have different names each time on Google Drive

Options Database Key:

• -google_refresh_token XXX - pass the access token for the operation

See also: PetscGoogleDriveAuthorize(), PetscGoogleDriveRefresh()

External Links

• PETSc Manual: Sys/PetscGoogleDriveUpload

ptype::PetscDataType = PetscHDF5DataTypeToPetscDataType(petsclib::PetscLibType, htype::hid_t)

Finds the PETSc name of a datatype from its HDF5 name

Not Collective

Input Parameter:

• htype - the HDF5 datatype (for example H5T_NATIVE_DOUBLE, ...)

Output Parameter:

• ptype - the PETSc datatype name (for example PETSC_DOUBLE)

Level: advanced

See also: PetscDataType

External Links

• PETSc Manual: Viewer/PetscHDF5DataTypeToPetscDataType

PetscHIPBLASGetHandle(petsclib::PetscLibType, handle::hipblasHandle_t)

External Links

• PETSc Manual: Sys/PetscHIPBLASGetHandle

PetscHIPSOLVERGetHandle(petsclib::PetscLibType, handle::hipsolverHandle_t)

External Links

• PETSc Manual: Sys/PetscHIPSOLVERGetHandle

PetscHTTPRequest(petsclib::PetscLibType, type::String, url::String, header::String, ctype::String, body::String, sock::Cint, buff::String, buffsize::Csize_t)

Send a request to an HTTP server

Input Parameters:

• type - either "POST" or "GET"
• url - URL of request host/path
• header - additional header information, may be NULL
• ctype - data type of body, for example application/json
• body - data to send to server
• sock - obtained with PetscOpenSocket()
• buffsize - size of buffer

Output Parameter:

• buff - everything returned from server

Level: advanced

See also: PetscHTTPSRequest(), PetscOpenSocket(), PetscHTTPSConnect(), PetscPullJSONValue()

External Links

• PETSc Manual: Sys/PetscHTTPRequest

sock::Cint,ssl::Ptr{SSL} = PetscHTTPSConnect(petsclib::PetscLibType, host::String, port::Cint, ctx::SSL_CTX)

connect to a HTTPS server

Input Parameters:

• host - the name of the machine hosting the HTTPS server
• port - the port number where the server is hosting, usually 443
• ctx - value obtained with PetscSSLInitializeContext()

Output Parameters:

• sock - socket to connect
• ssl - the argument passed to PetscHTTPSRequest()

Level: advanced

See also: PetscOpenSocket(), PetscHTTPSRequest(), PetscSSLInitializeContext()

External Links

• PETSc Manual: Sys/PetscHTTPSConnect

PetscHTTPSRequest(petsclib::PetscLibType, type::String, url::String, header::String, ctype::String, body::String, ssl::SSL, buff::String, buffsize::Csize_t)

Send a request to an HTTPS server

Input Parameters:

• type - either "POST" or "GET"
• url - URL of request host/path
• header - additional header information, may be NULL
• ctype - data type of body, for example application/json
• body - data to send to server
• ssl - obtained with PetscHTTPSConnect()
• buffsize - size of buffer

Output Parameter:

• buff - everything returned from server

Level: advanced

See also: PetscHTTPRequest(), PetscHTTPSConnect(), PetscSSLInitializeContext(), PetscSSLDestroyContext(), PetscPullJSONValue()

External Links

• PETSc Manual: Sys/PetscHTTPSRequest

has::PetscBool = PetscHasExternalPackage(petsclib::PetscLibType, pkg::String)

Determine whether PETSc has been configured with the given package

Not Collective

Input Parameter:

• pkg - external package name

Output Parameter:

• has - PETSC_TRUE if PETSc is configured with the given package, else PETSC_FALSE.

Level: intermediate

See also: PetscViewerType, MatPartitioningType, MatSolverType

External Links

• PETSc Manual: Sys/PetscHasExternalPackage

PetscInfoActivateClass(petsclib::PetscLibType, classid::PetscClassId)

Activates PetscInfo() messages for a PETSc object class.

Not Collective

Input Parameter:

• classid - The object class, e.g., MAT_CLASSID, SNES_CLASSID, etc.

Options Database Key:

• -info [filename][:[~]list,of,classnames[:[~]self]] - specify which informative messages are printed, See PetscInfo().

Level: developer

See also: PetscInfoDeactivateClass(), PetscInfo(), PetscInfoAllow(), PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoActivateClass

PetscInfoAllow(petsclib::PetscLibType, flag::PetscBool)

Enables/disables PetscInfo() messages

Not Collective

Input Parameter:

• flag - PETSC_TRUE or PETSC_FALSE

Level: advanced

See also: PetscInfo(), PetscInfoEnabled(), PetscInfoGetInfo(), PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoAllow

PetscInfoDeactivateClass(petsclib::PetscLibType, classid::PetscClassId)

Deactivates PetscInfo() messages for a PETSc object class.

Not Collective

Input Parameter:

• classid - The object class, e.g., MAT_CLASSID, SNES_CLASSID, etc.

Options Database Key:

• -info [filename][:[~]list,of,classnames[:[~]self]] - specify which informative messages are printed, See PetscInfo().

Level: developer

See also: PetscInfoActivateClass(), PetscInfo(), PetscInfoAllow(), PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoDeactivateClass

PetscInfoDestroy(petsclib::PetscLibType)

Destroys and resets internal PetscInfo() data structures.

Not Collective

Level: developer

See also: PetscInfo(), PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoDestroy

enabled::PetscBool = PetscInfoEnabled(petsclib::PetscLibType, classid::PetscClassId)

Checks whether a given PetscClassid is allowed to print using PetscInfo()

Not Collective

Input Parameter:

• classid - PetscClassid retrieved from a PetscObject e.g. VEC_CLASSID

Output Parameter:

• enabled - PetscBool indicating whether this classid is allowed to print

Level: advanced

See also: PetscInfo(), PetscInfoAllow(), PetscInfoGetInfo(), PetscObjectGetClassid()

External Links

• PETSc Manual: Log/PetscInfoEnabled

found::PetscBool = PetscInfoGetClass(petsclib::PetscLibType, classname::String)

Indicates whether the provided classname is marked as a filter in PetscInfo() as set by PetscInfoSetClasses()

Not Collective

Input Parameter:

• classname - Name of the class to search for

Output Parameter:

• found - PetscBool indicating whether the classname was found

Level: developer

See also: PetscInfo(), PetscInfoSetClasses(), PetscInfoSetFromOptions(), PetscObjectGetName()

External Links

• PETSc Manual: Log/PetscInfoGetClass

filename::Ptr{Cchar},InfoFile::Ptr{Libc.FILE} = PetscInfoGetFile(petsclib::PetscLibType)

Gets the filename and FILE pointer of the file where PetscInfo() prints to

Not Collective; No Fortran Support

Output Parameters:

• filename - The name of the output file
• InfoFile - The FILE pointer for the output file

Level: advanced

See also: PetscInfo(), PetscInfoSetFile(), PetscInfoSetFromOptions(), PetscInfoDestroy()

External Links

• PETSc Manual: Log/PetscInfoGetFile

infoEnabled::PetscBool,classesSet::PetscBool,exclude::PetscBool,locked::PetscBool,commSelfFlag::PetscInfoCommFlag = PetscInfoGetInfo(petsclib::PetscLibType)

Returns the current state of several flags for PetscInfo()

Not Collective

Output Parameters:

• infoEnabled - PETSC_TRUE if PetscInfoAllow(PETSC_TRUE) has been called
• classesSet - PETSC_TRUE if the list of classes to filter for has been set
• exclude - PETSC_TRUE if the class filtering for PetscInfo() is inverted
• locked - PETSC_TRUE if the list of classes to filter for has been locked
• commSelfFlag - Enum indicating whether PetscInfo() will print for communicators of size 1, any size != 1, or all

communicators

Level: developer

See also: PetscInfo(), PetscInfoAllow(), PetscInfoSetFilterCommSelf, PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoGetInfo

PetscInfoProcessClass(petsclib::PetscLibType, classname::String, numClassID::PetscInt, classIDs::Vector{PetscClassId})

Activates or deactivates a class based on the filtering status of PetscInfo()

Not Collective

Input Parameters:

• classname - Name of the class to activate/deactivate PetscInfo() for
• numClassID - Number of entries in classIDs
• classIDs - Array containing all of the PetscClassIds associated with classname

Options Database Key:

• -info [filename][:[~]list,of,classnames[:[~]self]] - specify which informative messages are printed, see PetscInfo().

Level: developer

See also: PetscInfo(), PetscInfoActivateClass(), PetscInfoDeactivateClass(), PetscInfoSetFromOptions()

External Links

• PETSc Manual: Log/PetscInfoProcessClass

PetscInfoSetClasses(petsclib::PetscLibType, exclude::PetscBool, n::PetscInt, classnames::Cchar)

Sets the classes which PetscInfo() is filtered for/against

Not Collective; No Fortran Support

Input Parameters:

• exclude - Whether or not to invert the filter, i.e. if exclude is true, PetscInfo() will print from every class that

is NOT one of the classes specified

• n - Number of classes to filter for (size of classnames)
• classnames - String array containing the names of classes to filter for, e.g. "vec"

Level: developer

See also: PetscInfo(), PetscInfoGetClass(), PetscInfoProcessClass(), PetscInfoSetFromOptions(), PetscStrToArray(), PetscObjectGetName()

External Links

• PETSc Manual: Log/PetscInfoSetClasses

PetscInfoSetFile(petsclib::PetscLibType, filename::String, mode::String)

Sets the printing destination for all PetscInfo() calls

Not Collective

Input Parameters:

• filename - Name of the file where PetscInfo() will print to, use NULL to write to PETSC_STDOUT.
• mode - Write mode passed to PetscFOpen()

Level: advanced

See also: PetscInfo(), PetscInfoGetFile(), PetscInfoSetFromOptions(), PetscFOpen()

External Links

• PETSc Manual: Log/PetscInfoSetFile

PetscInfoSetFilterCommSelf(petsclib::PetscLibType, commSelfFlag::PetscInfoCommFlag)

Sets PetscInfoCommFlag enum to determine communicator filtering for PetscInfo()

Not Collective

Input Parameter:

• commSelfFlag - Enum value indicating method with which to filter PetscInfo() based on the size of the communicator of the object calling PetscInfo()

Options Database Key:

• -info [filename][:[~]list,of,classnames[:[~]self]] - specify which informative messages are printed, See PetscInfo().

Level: advanced

See also: PetscInfo(), PetscInfoGetInfo()

External Links

• PETSc Manual: Log/PetscInfoSetFilterCommSelf

PetscInfoSetFromOptions(petsclib::PetscLibType, options::AbstractPetscOptions)

Configure PetscInfo() using command line options, enabling or disabling various calls to PetscInfo()

Not Collective

Input Parameter:

• options - Options database, use NULL for default global database

Options Database Key:

• -info [filename][:[~]list,of,classnames[:[~]self]] - specify which informative messages are printed, See PetscInfo().

Level: advanced

See also: PetscInfo(), PetscInfoAllow(), PetscInfoSetFile(), PetscInfoSetClasses(), PetscInfoSetFilterCommSelf(), PetscInfoDestroy()

External Links

• PETSc Manual: Log/PetscInfoSetFromOptions

PetscInitialize(petsclib::PetscLibType, args::Vector{String}, file::Union{Nothing, String} = nothing, help::Union{Nothing, String} = nothing)

Initializes the PETSc database and MPI, with args as the command line: args[1] is the program name and the rest are options, one token per entry, such as ["prog", "-ksp_type", "cg"]. Options given here override those in the PETSC_OPTIONS environment variable.

PETSc keeps pointers to args until PetscFinalize(), so the strings are held here until the next call.

Collective on MPI_COMM_WORLD or PETSC_COMM_WORLD if it has been set

Input Parameters:

• args - the command line, program name first
• file - an optional options file, or nothing
• help - an optional help message printed by -help, or nothing

Level: beginner

See also: PetscFinalize(), PetscInitializeNoArguments(), PetscGetArgs()

External Links

• PETSc Manual: Sys/PetscInitialize

PetscInitializeFortran(petsclib::PetscLibType)

Routine that should be called soon AFTER the call to PetscInitialize() if one is using a C main program that calls Fortran routines that in turn call PETSc routines.

Collective on PETSC_COMM_WORLD

Level: beginner

See also: PetscInitialize()

External Links

• PETSc Manual: Sys/PetscInitializeFortran

PetscInitializeNoArguments(petsclib::PetscLibType)

Calls PetscInitialize() from C/C++ without the command line arguments.

Collective

Level: advanced

See also: PetscInitialize(), PetscInitializeFortran()

External Links

• PETSc Manual: Sys/PetscInitializeNoArguments

PetscInitializeNoPointers(petsclib::PetscLibType, argc::Cint, args::Cchar, filename::String, help::String)

Calls PetscInitialize() from C/C++ without the pointers to argc and args

Collective, No Fortran Support

Input Parameters:

• argc - number of args
• args - array of command line arguments
• filename - optional name of the program file, pass NULL to ignore
• help - optional help, pass NULL to ignore

Level: advanced

See also: PetscInitialize(), PetscInitializeFortran(), PetscInitializeNoArguments()

External Links

• PETSc Manual: Sys/PetscInitializeNoPointers

isInitialized::PetscBool = PetscInitialized(petsclib::PetscLibType)

Determine whether PETSc is initialized.

Output Parameter:

• isInitialized - PETSC_TRUE if PETSc is initialized, PETSC_FALSE otherwise

Level: beginner

See also: PetscInitialize(), PetscInitializeNoArguments(), PetscInitializeFortran()

External Links

• PETSc Manual: Sys/PetscInitialized

PetscIntSortSemiOrdered(petsclib::PetscLibType, n::PetscInt, arr::Vector{PetscInt})

Sorts an array of PetscInt in place in increasing order.

Not Collective

Input Parameters:

• n - number of values
• arr - array of integers

Output Parameter:

• arr - sorted array of integers

Level: intermediate

See also: PetscTimSort(), PetscSortInt(), PetscSortIntWithPermutation()

External Links

• PETSc Manual: Sys/PetscIntSortSemiOrdered

PetscIntSortSemiOrderedWithArray(petsclib::PetscLibType, n::PetscInt, arr1::Vector{PetscInt}, arr2::Vector{PetscInt})

Sorts an array of PetscInt in place in increasing order and reorders a second PetscInt array to match the first.

Not Collective

Input Parameter:

• n - number of values

Input/Output Parameters:

• arr1 - array of integers to be sorted, modified on output
• arr2 - array of integers to be reordered, modified on output

Level: intermediate

See also: PetscTimSortWithArray(), PetscSortIntWithArray(), PetscSortIntWithPermutation()

External Links

• PETSc Manual: Sys/PetscIntSortSemiOrderedWithArray

PetscIntView(petsclib::PetscLibType, N::PetscInt, idx::Vector{PetscInt}, viewer::PetscViewer)

Prints an array of integers; useful for debugging.

Collective

Input Parameters:

• N - number of integers in array
• idx - array of integers
• viewer - location to print array, PETSC_VIEWER_STDOUT_WORLD, PETSC_VIEWER_STDOUT_SELF or 0

Level: intermediate

See also: PetscViewer, PetscIntViewNumColumns(), PetscRealView()

External Links

• PETSc Manual: Sys/PetscIntView

PetscIntViewNumColumns(petsclib::PetscLibType, N::PetscInt, Ncol::PetscInt, idx::Vector{PetscInt}, viewer::PetscViewer)

Prints an array of integers; useful for debugging.

Collective

Input Parameters:

• N - number of integers in array
• Ncol - number of integers to print per row
• idx - array of integers
• viewer - location to print array, PETSC_VIEWER_STDOUT_WORLD, PETSC_VIEWER_STDOUT_SELF or 0

Level: intermediate

See also: PetscViewer, PetscIntView(), PetscRealView()

External Links

• PETSc Manual: Sys/PetscIntViewNumColumns

PetscKokkosInitializeCheck(petsclib::PetscLibType)

External Links

• PETSc Manual: Sys/PetscKokkosInitializeCheck

slope::PetscReal,intercept::PetscReal = PetscLinearRegression(petsclib::PetscLibType, n::PetscInt, x::Vector{PetscReal}, y::Vector{PetscReal})

Gives the best least-squares linear fit to some x-y data points

Input Parameters:

• n - The number of points
• x - The x-values
• y - The y-values

Output Parameters:

• slope - The slope of the best-fit line
• intercept - The y-intercept of the best-fit line

Level: intermediate

See also: PetscConvEstGetConvRate()

External Links

• PETSc Manual: Sys/PetscLinearRegression

PetscLogActions(petsclib::PetscLibType, flag::PetscBool)

Determines whether actions are logged for the default log handler.

Not Collective

Input Parameter:

• flag - PETSC_TRUE if actions are to be logged

Options Database Key:

• -log_exclude_actions - (deprecated) Does nothing
• -log_include_actions - Turn on action logging

Level: intermediate

See also: PetscLogStagePush(), PetscLogStagePop(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogActions

classid::PetscClassId = PetscLogClassGetClassId(petsclib::PetscLibType, name::String)

Returns the PetscClassId when given the class name.

Not Collective

Input Parameter:

• name - The class name

Output Parameter:

• classid - The PetscClassId id, or -1 if no class with that name exists

Level: intermediate

See also: PetscLogEventBegin(), PetscLogEventEnd(), PetscLogStageGetId()

External Links

• PETSc Manual: Log/PetscLogClassGetClassId

name::String = PetscLogClassIdGetName(petsclib::PetscLibType, classid::PetscClassId)

Returns a PetscClassId's name.

Not Collective

Input Parameter:

• classid - A PetscClassId

Output Parameter:

• name - The class name

Level: intermediate

See also: PetscLogClassRegister(), PetscLogClassBegin(), PetscLogClassEnd(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadClass()

External Links

• PETSc Manual: Log/PetscLogClassIdGetName

PetscLogDefaultBegin(petsclib::PetscLibType)

Turns on logging (profiling) of PETSc code using the default log handler (profiler). This logs time, flop rates, and object creation and should not slow programs down too much.

Logically Collective on PETSC_COMM_WORLD

Options Database Key:

• -log_view [viewertype[:filename[:viewerformat]]] - Prints summary of flop and timing (profiling) information to the

screen (for PETSc configured with --with-log=1 (which is the default)). This option must be provided before PetscInitialize().

See also: PetscLogDump(), PetscLogView(), PetscLogTraceBegin()

External Links

• PETSc Manual: Log/PetscLogDefaultBegin

PetscLogDump(petsclib::PetscLibType, sname::String)

Dumps logs of objects to a file. There is currently no utility to read the dump file.

Collective on PETSC_COMM_WORLD

Input Parameter:

• sname - an optional file name

See also: PetscLogDefaultBegin(), PetscLogView(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogDump

PetscLogEventActivate(petsclib::PetscLibType, event::PetscLogEvent)

Indicates that a particular event should be logged.

Not Collective

Input Parameter:

• event - The event id

See also: PetscLogEventDeactivate(), PetscLogEventDeactivatePush(), PetscLogEventDeactivatePop()

External Links

• PETSc Manual: Log/PetscLogEventActivate

PetscLogEventActivateClass(petsclib::PetscLibType, classid::PetscClassId)

Activates event logging for a PETSc object class for the current stage

Not Collective

Input Parameter:

• classid - The event class, for example MAT_CLASSID, SNES_CLASSID, etc.

Level: developer

See also: PetscLogEventIncludeClass(), PetscLogEventExcludeClass(), PetscLogEventDeactivateClass(), PetscLogEventActivate(), PetscLogEventDeactivate()

External Links

• PETSc Manual: Log/PetscLogEventActivateClass

PetscLogEventDeactivate(petsclib::PetscLibType, event::PetscLogEvent)

Indicates that a particular event should not be logged.

Not Collective

Input Parameter:

• event - The event id

See also: PetscLogEventActivate(), PetscLogEventDeactivatePush(), PetscLogEventDeactivatePop()

External Links

• PETSc Manual: Log/PetscLogEventDeactivate

PetscLogEventDeactivateClass(petsclib::PetscLibType, classid::PetscClassId)

Deactivates event logging for a PETSc object class for the current stage

Not Collective

Input Parameter:

• classid - The event class, for example MAT_CLASSID, SNES_CLASSID, etc.

Level: developer

See also: PetscLogEventIncludeClass(), PetscLogEventExcludeClass(), PetscLogEventActivateClass(), PetscLogEventActivate(), PetscLogEventDeactivate()

External Links

• PETSc Manual: Log/PetscLogEventDeactivateClass

PetscLogEventDeactivatePop(petsclib::PetscLibType, event::PetscLogEvent)

Indicates that a particular event should again be logged after the logging was turned off with PetscLogEventDeactivatePush()

Not Collective

Input Parameter:

• event - The event id

See also: PetscLogEventActivate(), PetscLogEventDeactivatePush()

External Links

• PETSc Manual: Log/PetscLogEventDeactivatePop

PetscLogEventDeactivatePush(petsclib::PetscLibType, event::PetscLogEvent)

Indicates that a particular event should not be logged until PetscLogEventDeactivatePop() is called

Not Collective

Input Parameter:

• event - The event id

See also: PetscLogEventActivate(), PetscLogEventDeactivate(), PetscLogEventDeactivatePop()

External Links

• PETSc Manual: Log/PetscLogEventDeactivatePush

PetscLogEventExcludeClass(petsclib::PetscLibType, classid::PetscClassId)

Deactivates event logging for a PETSc object class in every stage.

Not Collective

Input Parameter:

• classid - The object class, for example MAT_CLASSID, SNES_CLASSID, etc.

Level: developer

See also: PetscLogEventDeactivateClass(), PetscLogEventActivateClass(), PetscLogEventDeactivate(), PetscLogEventActivate()

External Links

• PETSc Manual: Log/PetscLogEventExcludeClass

event::PetscLogEvent = PetscLogEventGetId(petsclib::PetscLibType, name::String)

Returns the event id when given the event name.

Not Collective

Input Parameter:

• name - The event name

Output Parameter:

• event - The event, or -1 if no event with that name exists

Level: intermediate

See also: PetscLogEventBegin(), PetscLogEventEnd(), PetscLogStageGetId()

External Links

• PETSc Manual: Log/PetscLogEventGetId

name::String = PetscLogEventGetName(petsclib::PetscLibType, event::PetscLogEvent)

Returns the event name when given the event id.

Not Collective

Input Parameter:

• event - The event

Output Parameter:

• name - The event name

Level: intermediate

See also: PetscLogEventRegister(), PetscLogEventBegin(), PetscLogEventEnd(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadStage()

External Links

• PETSc Manual: Log/PetscLogEventGetName

info::PetscEventPerfInfo = PetscLogEventGetPerfInfo(petsclib::PetscLibType, stage::PetscLogStage, event::PetscLogEvent)

Return the performance information about the given event in the given stage

No Fortran Support

Input Parameters:

• stage - The stage number or PETSC_DETERMINE for the current stage
• event - The event number

Output Parameter:

• info - This structure is filled with the performance information

Level: intermediate

See also: PetscLogEventRegister(), PetscLogEventBegin(), PetscLogEventEnd(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogEventGetPerfInfo

PetscLogEventIncludeClass(petsclib::PetscLibType, classid::PetscClassId)

Activates event logging for a PETSc object class in every stage.

Not Collective

Input Parameter:

• classid - The object class, for example MAT_CLASSID, SNES_CLASSID, etc.

Level: developer

See also: PetscLogEventActivateClass(), PetscLogEventDeactivateClass(), PetscLogEventActivate(), PetscLogEventDeactivate()

External Links

• PETSc Manual: Log/PetscLogEventIncludeClass

event::PetscLogEvent = PetscLogEventRegister(petsclib::PetscLibType, name::String, classid::PetscClassId)

Registers an event name for logging operations

Not Collective

Input Parameters:

• name - The name associated with the event
• classid - The classid associated to the class for this event, obtain either with

PetscClassIdRegister() or use a predefined one such as KSP_CLASSID, SNES_CLASSID, the predefined ones are only available in C code

Output Parameter:

• event - The event id for use with PetscLogEventBegin() and PetscLogEventEnd().

See also: PetscLogStageRegister(), PetscLogEventBegin(), PetscLogEventEnd(), PetscLogFlops(), PetscLogEventActivate(), PetscLogEventDeactivate(), PetscClassIdRegister()

External Links

• PETSc Manual: Log/PetscLogEventRegister

PetscLogEventSetActiveAll(petsclib::PetscLibType, event::PetscLogEvent, isActive::PetscBool)

Turns on logging of all events

Not Collective

Input Parameters:

• event - The event id
• isActive - The activity flag determining whether the event is logged

Level: advanced

See also: PetscLogEventActivate(), PetscLogEventDeactivate()

External Links

• PETSc Manual: Log/PetscLogEventSetActiveAll

PetscLogEventSetCollective(petsclib::PetscLibType, event::PetscLogEvent, collective::PetscBool)

Indicates that a particular event is collective.

Logically Collective

Input Parameters:

• event - The event id
• collective - PetscBool indicating whether a particular event is collective

Level: developer

See also: PetscLogEventBegin(), PetscLogEventEnd(), PetscLogEventRegister()

External Links

• PETSc Manual: Log/PetscLogEventSetCollective

PetscLogEventSetDof(petsclib::PetscLibType, event::PetscLogEvent, n::PetscInt, dof::PetscLogDouble)

Set the nth number of degrees of freedom of a numerical problem associated with this event

Not Collective

Input Parameters:

• event - The event id to log
• n - The dof index, in [0, 8)
• dof - The number of dofs

Options Database Key:

• -log_view - Activates log summary

Level: developer

See also: PetscLogEventSetError(), PetscLogEventRegister(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogEventSetDof

PetscLogEventSetError(petsclib::PetscLibType, event::PetscLogEvent, n::PetscInt, error::PetscLogDouble)

Set the nth error associated with a numerical problem associated with this event

Not Collective

Input Parameters:

• event - The event id to log
• n - The error index, in [0, 8)
• error - The error

Options Database Key:

• -log_view - Activates log summary

Level: developer

See also: PetscLogEventSetDof(), PetscLogEventRegister(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogEventSetError

PetscLogEventsPause(petsclib::PetscLibType)

Put event logging into "paused" mode: timers and counters for in-progress events are paused, and any events that happen before logging is resumed with PetscLogEventsResume() are logged in the "Main Stage" of execution.

Not collective

Level: advanced

See also: PetscLogEventDeactivatePush(), PetscLogEventDeactivatePop(), PetscLogEventsResume(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogEventsPause

PetscLogEventsResume(petsclib::PetscLibType)

Return logging to normal behavior after it was paused with PetscLogEventsPause().

Not collective

Level: advanced

See also: PetscLogEventDeactivatePush(), PetscLogEventDeactivatePop(), PetscLogEventsPause(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogEventsResume

handler::PetscLogHandler = PetscLogGetDefaultHandler(petsclib::PetscLibType)

Get the default log handler if it is running.

Not collective

Output Parameter:

• handler - the default PetscLogHandler, or NULL if it is not running.

Level: developer

Notes: The default handler is started with PetscLogDefaultBegin(), if the options flags -log_all or -log_view is given without arguments, or for -log_view :output:format if format is not ascii_xml or ascii_flamegraph.

External Links

• PETSc Manual: Log/PetscLogGetDefaultHandler

state::PetscLogState = PetscLogGetState(petsclib::PetscLibType)

Get the PetscLogState for PETSc's global logging, used by all default log handlers (PetscLogDefaultBegin(), PetscLogNestedBegin(), PetscLogTraceBegin(), PetscLogMPEBegin(), PetscLogPerfstubsBegin()).

Collective on PETSC_COMM_WORLD

Output Parameter:

• state - The PetscLogState changed by registrations (such as

PetscLogEventRegister()) and actions (such as PetscLogEventBegin() or PetscLogStagePush()), or NULL if logging is not active

Level: developer

See also: PetscLogState

External Links

• PETSc Manual: Log/PetscLogGetState

isActive::PetscBool = PetscLogIsActive(petsclib::PetscLibType)

Check if logging (profiling) is currently in progress.

Not Collective

Output Parameter:

• isActive - PETSC_TRUE if logging is in progress, PETSC_FALSE otherwise

Level: beginner

See also: PetscLogDefaultBegin()

External Links

• PETSc Manual: Log/PetscLogIsActive

PetscLogLegacyCallbacksBegin(petsclib::PetscLibType, PetscLogPLB::external, PetscLogPLE::external, PetscLogPHC::external, PetscLogPHD::external)

Create and start a log handler from callbacks matching the now deprecated function pointers PetscLogPLB, PetscLogPLE, PetscLogPHC, PetscLogPHD.

Logically Collective on PETSC_COMM_WORLD

Input Parameters:

• PetscLogPLB - A callback that will be executed by PetscLogEventBegin() (or NULL)
• PetscLogPLE - A callback that will be executed by PetscLogEventEnd() (or NULL)
• PetscLogPHC - A callback that will be executed by PetscLogObjectCreate() (or NULL)
• PetscLogPHD - A callback that will be executed by PetscLogObjectCreate() (or NULL)

Calling sequence of PetscLogPLB:

• e - a PetscLogEvent that is beginning
• _i - deprecated, unused
• o1 - a PetscObject associated with e (or NULL)
• o2 - a PetscObject associated with e (or NULL)
• o3 - a PetscObject associated with e (or NULL)
• o4 - a PetscObject associated with e (or NULL)

Calling sequence of PetscLogPLE:

• e - a PetscLogEvent that is beginning
• _i - deprecated, unused
• o1 - a PetscObject associated with e (or NULL)
• o2 - a PetscObject associated with e (or NULL)
• o3 - a PetscObject associated with e (or NULL)
• o4 - a PetscObject associated with e (or NULL)

Calling sequence of PetscLogPHC:

• o - a PetscObject that has just been created

Calling sequence of PetscLogPHD:

• o - a PetscObject that is about to be destroyed

Level: advanced

See also: PetscLogHandler, PetscLogHandlerStart(), PetscLogState

External Links

• PETSc Manual: Log/PetscLogLegacyCallbacksBegin

PetscLogMPEBegin(petsclib::PetscLibType)

Turns on MPE logging of events. This creates large log files and slows the program down.

Collective on PETSC_COMM_WORLD, No Fortran Support

Options Database Key:

• -log_mpe - Prints extensive log information

Level: advanced

See also: PetscLogDump(), PetscLogDefaultBegin(), PetscLogEventActivate(), PetscLogEventDeactivate()

External Links

• PETSc Manual: Log/PetscLogMPEBegin

PetscLogMPEDump(petsclib::PetscLibType, sname::String)

Dumps the MPE logging info to file for later use with Jumpshot.

Collective on PETSC_COMM_WORLD

Input Parameter:

• sname - filename for the MPE logfile

Level: advanced

See also: PetscLogDump(), PetscLogMPEBegin()

External Links

• PETSc Manual: Log/PetscLogMPEDump

PetscLogNestedBegin(petsclib::PetscLibType)

Turns on nested logging of objects and events. This logs flop rates and object creation and should not slow programs down too much.

Logically Collective on PETSC_COMM_WORLD, No Fortran Support

Options Database Keys:

• -log_view :filename.xml:ascii_xml - Prints an XML summary of flop and timing information to the file

See also: PetscLogDump(), PetscLogView(), PetscLogTraceBegin(), PetscLogDefaultBegin()

External Links

• PETSc Manual: Log/PetscLogNestedBegin

PetscLogObjects(petsclib::PetscLibType, flag::PetscBool)

Determines whether objects are logged for the graphical viewer.

Not Collective

Input Parameter:

• flag - PETSC_TRUE if objects are to be logged

Options Database Key:

• -log_exclude_objects - (deprecated) Does nothing
• -log_include_objects - Turns on object logging

Level: intermediate

See also: PetscLogStagePush(), PetscLogStagePop(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogObjects

PetscLogPerfstubsBegin(petsclib::PetscLibType)

Turns on logging of events using the perfstubs interface.

Collective on PETSC_COMM_WORLD, No Fortran Support

Options Database Key:

• -log_perfstubs - use an external log handler through the perfstubs interface

Level: advanced

See also: PetscLogDefaultBegin(), PetscLogEventActivate()

External Links

• PETSc Manual: Log/PetscLogPerfstubsBegin

oldThresh::PetscLogDouble = PetscLogSetThreshold(petsclib::PetscLibType, newThresh::PetscLogDouble)

Set the threshold time for logging the events; this is a percentage out of 100, so 1. means any event that takes 1 or more percent of the time.

Logically Collective on PETSC_COMM_WORLD

Input Parameter:

• newThresh - the threshold to use

Output Parameter:

• oldThresh - the previously set threshold value

Options Database Keys:

• -log_view :filename.xml:ascii_xml - Prints an XML summary of flop and timing information to the file

See also: PetscLogDump(), PetscLogView(), PetscLogTraceBegin(), PetscLogDefaultBegin(), PetscLogNestedBegin()

External Links

• PETSc Manual: Log/PetscLogSetThreshold

isActive::PetscBool = PetscLogStageGetActive(petsclib::PetscLibType, stage::PetscLogStage)

Checks if a stage is used for PetscLogEventBegin() and PetscLogEventEnd().

Not Collective

Input Parameter:

• stage - The stage

Output Parameter:

• isActive - The activity flag, PETSC_TRUE for logging, else PETSC_FALSE (defaults to PETSC_TRUE)

Level: intermediate

See also: PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscLogEventBegin(), PetscLogEventEnd(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadStage()

External Links

• PETSc Manual: Log/PetscLogStageGetActive

stage::PetscLogStage = PetscLogStageGetId(petsclib::PetscLibType, name::String)

Returns the stage id when given the stage name.

Not Collective

Input Parameter:

• name - The stage name

Output Parameter:

• stage - The stage, , or -1 if no stage with that name exists

Level: intermediate

See also: PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadStage()

External Links

• PETSc Manual: Log/PetscLogStageGetId

name::String = PetscLogStageGetName(petsclib::PetscLibType, stage::PetscLogStage)

Returns the stage name when given the stage id.

Not Collective

Input Parameter:

• stage - The stage

Output Parameter:

• name - The stage name

Level: intermediate

See also: PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadStage()

External Links

• PETSc Manual: Log/PetscLogStageGetName

info::PetscEventPerfInfo = PetscLogStageGetPerfInfo(petsclib::PetscLibType, stage::PetscLogStage)

Return the performance information about the given stage

No Fortran Support

Input Parameters:

• stage - The stage number or PETSC_DETERMINE for the current stage

Output Parameter:

• info - This structure is filled with the performance information

Level: intermediate

See also: PetscLogEventRegister(), PetscLogEventBegin(), PetscLogEventEnd(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogStageGetPerfInfo

isVisible::PetscBool = PetscLogStageGetVisible(petsclib::PetscLibType, stage::PetscLogStage)

Returns stage visibility in PetscLogView()

Not Collective

Input Parameter:

• stage - The stage

Output Parameter:

• isVisible - The visibility flag, PETSC_TRUE to print, else PETSC_FALSE (defaults to PETSC_TRUE)

Level: intermediate

See also: PetscLogStageSetVisible(), PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscLogView(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogStageGetVisible

PetscLogStagePop(petsclib::PetscLibType)

This function pops a stage from the logging stack that was pushed with PetscLogStagePush()

Not Collective

See also: PetscLogStagePush(), PetscLogStageRegister(), PetscBarrier()

External Links

• PETSc Manual: Log/PetscLogStagePop

PetscLogStagePush(petsclib::PetscLibType, stage::PetscLogStage)

This function pushes a stage on the logging stack. Events started and stopped until PetscLogStagePop() will be associated with the stage

Not Collective

Input Parameter:

• stage - The stage on which to log

See also: PetscLogStagePop(), PetscLogStageRegister(), PetscBarrier()

External Links

• PETSc Manual: Log/PetscLogStagePush

stage::PetscLogStage = PetscLogStageRegister(petsclib::PetscLibType, sname::String)

Attaches a character string name to a logging stage.

Not Collective

Input Parameter:

• sname - The name to associate with that stage

Output Parameter:

• stage - The stage number or -1 if logging is not active (PetscLogIsActive()).

Level: intermediate

See also: PetscLogStagePush(), PetscLogStagePop()

External Links

• PETSc Manual: Log/PetscLogStageRegister

PetscLogStageSetActive(petsclib::PetscLibType, stage::PetscLogStage, isActive::PetscBool)

Sets if a stage is used for PetscLogEventBegin() and PetscLogEventEnd().

Not Collective

Input Parameters:

• stage - The stage
• isActive - The activity flag, PETSC_TRUE for logging, else PETSC_FALSE (defaults to PETSC_TRUE)

Level: intermediate

See also: PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscLogEventBegin(), PetscLogEventEnd(), PetscPreLoadBegin(), PetscPreLoadEnd(), PetscPreLoadStage()

External Links

• PETSc Manual: Log/PetscLogStageSetActive

PetscLogStageSetVisible(petsclib::PetscLibType, stage::PetscLogStage, isVisible::PetscBool)

Determines stage visibility in PetscLogView()

Not Collective

Input Parameters:

• stage - The stage
• isVisible - The visibility flag, PETSC_TRUE to print, else PETSC_FALSE (defaults to PETSC_TRUE)

Level: intermediate

See also: PetscLogStageGetVisible(), PetscLogStageRegister(), PetscLogStagePush(), PetscLogStagePop(), PetscLogView(), PetscLogGetDefaultHandler()

External Links

• PETSc Manual: Log/PetscLogStageSetVisible

PetscLogTraceBegin(petsclib::PetscLibType, file::Libc.FILE)

Begins trace logging. Every time a PETSc event begins or ends, the event name is printed.

Logically Collective on PETSC_COMM_WORLD, No Fortran Support

Input Parameter:

• file - The file to print trace in (e.g. stdout)

Options Database Key:

• -log_trace [filename] - Begins PetscLogTraceBegin()

Level: intermediate

See also: PetscLogDump(), PetscLogView(), PetscLogDefaultBegin()

External Links

• PETSc Manual: Log/PetscLogTraceBegin

PetscLogView(petsclib::PetscLibType, viewer::PetscViewer)

Prints a summary of the logging.

Collective

Input Parameter:

• viewer - an ASCII viewer

Options Database Keys:

• -log_view [:filename] - Prints summary of log information
• -log_view :filename.py:ascii_info_detail - Saves logging information from each process as a Python file
• -log_view :filename.xml:ascii_xml - Saves a summary of the logging information in a nested format (see below for how to view it)
• -log_view :filename.txt:ascii_flamegraph - Saves logging information in a format suitable for visualising as a Flame Graph (see below for how to view it)
• -log_view :filename.csv:ascii_csv - Saves logging information as a comma-separated values file
• -log_view_memory - Also display memory usage in each event
• -log_view_gpu_time - Also display time in each event for GPU kernels (Note this may slow the computation)
• -log_view_gpu_energy - Also display energy (estimated with power*gtime) in Joules for GPU kernels
• -log_view_gpu_energy_meter - [Experimental] Also display energy (readings from energy meters) in Joules for GPU kernels.

This option is ignored if -log_view_gpu_energy is provided.

• -log_all - Saves a file Log.rank for each MPI process with details of each step of the computation, where

rank is the MPI rank of each process

• -log_trace [filename] - Displays a trace of what each process is doing

Level: beginner

See also: PetscLogDefaultBegin(), PetscLogDump()

External Links

• PETSc Manual: Log/PetscLogView

PetscLogViewFromOptions(petsclib::PetscLibType)

Processes command line options to determine if/how a PetscLog is to be viewed.

Collective on PETSC_COMM_WORLD

Level: developer

See also: PetscLogView()

External Links

• PETSc Manual: Log/PetscLogViewFromOptions

flg::PetscBool = PetscLs(petsclib::PetscLibType, comm::MPI_Comm, dirname::String, found::String, tlen::Csize_t)

produce a listing of the files in a directory

Collective

Input Parameters:

• comm - the MPI communicator
• dirname - the directory name
• tlen - the length of the buffer found

Output Parameters:

• found - listing of files
• flg - the directory exists

Level: intermediate

See also: PetscTestFile(), PetscRMTree(), PetscTestDirectory()

External Links

• PETSc Manual: Sys/PetscLs

PetscMPIAbortErrorHandler(petsclib::PetscLibType, comm::MPI_Comm, line::Cint, fun::String, file::String, n::PetscErrorCode, p::PetscErrorType, mess::String, ctx::Ptr{Cvoid})

Calls PETSCABORT() and exits.

Not Collective, No Fortran Support

Input Parameters:

• comm - communicator over which error occurred
• line - the line number of the error (indicated by __LINE__)
• fun - the function name
• file - the file in which the error was detected (indicated by __FILE__)
• mess - an error text string, usually just printed to the screen
• n - the generic error number
• p - PETSC_ERROR_INITIAL if error just detected, otherwise PETSC_ERROR_REPEAT
• ctx - error handler context

Level: developer

See also: PetscError(), PetscPushErrorHandler(), PetscPopErrorHandler(), PetscAttachDebuggerErrorHandler(), PetscAbortErrorHandler(), PetscTraceBackErrorHandler(), PetscEmacsClientErrorHandler(), PetscReturnErrorHandler()

External Links

• PETSc Manual: Sys/PetscMPIAbortErrorHandler

PetscMPIDump(petsclib::PetscLibType, fd::Libc.FILE)

Dumps a listing of incomplete MPI operations, such as sends that have never been received, etc.

Collective on PETSC_COMM_WORLD

Input Parameter:

• fd - file pointer. If fp is NULL, stdout is assumed.

Options Database Key:

• -mpidump - Dumps MPI incompleteness during call to PetscFinalize()

Level: developer

See also: PetscMallocDump()

External Links

• PETSc Manual: Sys/PetscMPIDump

PetscMPIIntSortSemiOrdered(petsclib::PetscLibType, n::PetscInt, arr::Vector{PetscMPIInt})

Sorts an array of PetscMPIInt in place in increasing order.

Not Collective

Input Parameters:

• n - number of values
• arr - array of PetscMPIInt

Output Parameter:

• arr - sorted array of integers

Level: intermediate

See also: PetscTimSort(), PetscSortMPIInt()

External Links

• PETSc Manual: Sys/PetscMPIIntSortSemiOrdered

PetscMPIIntSortSemiOrderedWithArray(petsclib::PetscLibType, n::PetscInt, arr1::Vector{PetscMPIInt}, arr2::Vector{PetscMPIInt})

Sorts an array of PetscMPIInt in place in increasing order and reorders a second PetscMPIInt array to match the first.

Not Collective

Input Parameter:

• n - number of values

Input/Output Parameters:

• arr1 - array of integers to be sorted, modified on output
• arr2 - array of integers to be reordered, modified on output

Level: intermediate

See also: PetscTimSortWithArray(), PetscSortMPIIntWithArray(), PetscSortIntWithPermutation()

External Links

• PETSc Manual: Sys/PetscMPIIntSortSemiOrderedWithArray

PetscMallocClear(petsclib::PetscLibType)

Resets the routines used by PetscMalloc() and PetscFree()

Not Collective

Level: developer

See also: PetscMallocSet(), PetscMalloc(), PetscFree()

External Links

• PETSc Manual: Sys/PetscMallocClear

PetscMallocDump(petsclib::PetscLibType, fp::Libc.FILE)

Dumps the currently allocated memory blocks to a file. The information printed is: size of space (in bytes), address of space, id of space, file in which space was allocated, and line number at which it was allocated.

Not Collective

Input Parameter:

• fp - file pointer. If fp is NULL, stdout is assumed.

Options Database Key:

• -malloc_dump optional filename - Print summary of unfreed memory during call to PetscFinalize(), writing to filename if given

Level: intermediate

See also: PetscMallocGetCurrentUsage(), PetscMallocView(), PetscMallocViewSet(), PetscMallocValidate(), PetscMalloc(), PetscFree()