AO (Application Ordering) - Low-level Interface

The AO (Application Ordering) component provides mappings between the natural "application" ordering of unknowns and the PETSc parallel ordering, which is optimized for parallel sparse matrix operations.

Overview

Application orderings are used when:

Natural ordering differs from parallel ordering: Your application uses a different numbering scheme
I/O operations: Reading/writing data in application order
User interaction: Displaying results in familiar ordering
Legacy code integration: Interfacing with existing applications

The AO object maintains bidirectional mappings:

Application → PETSc: Convert from your numbering to PETSc's
PETSc → Application: Convert from PETSc's numbering to yours

Basic Usage

using PETSc, MPI

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

# Define the mapping
# application[i] is the application index for PETSc index i
n = 10
application = Int32[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]  # Reverse ordering
petsc = Int32[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]        # Natural PETSc ordering

# Create AO object
ao = LibPETSc.AOCreateBasic(petsclib, LibPETSc.PETSC_COMM_SELF, n, application, petsc)

# Convert application indices to PETSc indices
app_indices = Int32[0, 5, 9]
LibPETSc.AOApplicationToPetsc(petsclib, ao, length(app_indices), app_indices)
# app_indices now contains corresponding PETSc indices

# Convert PETSc indices to application indices  
petsc_indices = Int32[0, 1, 2]
LibPETSc.AOPetscToApplication(petsclib, ao, length(petsc_indices), petsc_indices)
# petsc_indices now contains corresponding application indices

# Cleanup
LibPETSc.AODestroy(petsclib, ao)

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

Creating AO Objects

Basic AO

Most common: explicit mapping arrays:

# Create from application and PETSc index arrays
ao = LibPETSc.AOCreateBasic(petsclib, comm, n, app_indices, petsc_indices)

Identity Mapping

When application and PETSc orderings are the same:

# Create identity mapping (no conversion needed)
ao = LibPETSc.AOCreateIdentity(petsclib, comm, n)

Memory Scalable

For large problems where storing full mapping is expensive:

# Create memory-scalable AO (uses hash table)
ao = LibPETSc.AOCreateMemoryScalable(petsclib, comm, n, app_indices, petsc_indices)

Conversion Operations

Forward Conversion (Application → PETSc)

# Convert array of application indices to PETSc indices
indices = Int32[10, 20, 30, 40]
# Create forward conversion example
LibPETSc.AOApplicationToPetsc(petsclib, ao, length(indices), indices)
# indices are now in PETSc ordering (modified in-place)

Reverse Conversion (PETSc → Application)

# Convert array of PETSc indices to application indices
indices = Int32[0, 5, 10, 15]
# Reverse conversion example
LibPETSc.AOPetscToApplication(petsclib, ao, length(indices), indices)
# indices are now in application ordering (modified in-place)

Index Set Conversion

# Convert IS (index set) from application to PETSc ordering
is_app = Ref{LibPETSc.IS}()
# ... create IS with application indices ...

LibPETSc.AOApplicationToPetscIS(petsclib, ao, is_app[])
# is_app now contains PETSc indices

Parallel Considerations

Each processor has its own local application ordering
AO objects handle parallel communication automatically
Indices not owned locally are mapped via MPI communication

# Create parallel AO
ao = LibPETSc.AOCreateBasic(petsclib, MPI.COMM_WORLD, local_n, 
                           local_app_indices, local_petsc_indices)

Common Use Cases

1. Reading Data in Application Order

# Read matrix entries in application ordering
# Then convert to PETSc ordering for assembly

# Application-ordered rows/cols
app_rows = Int32[...]
app_cols = Int32[...]

# Convert to PETSc ordering
LibPETSc.AOApplicationToPetsc(petsclib, ao, length(app_rows), app_rows)
LibPETSc.AOApplicationToPetsc(petsclib, ao, length(app_cols), app_cols)

# Now use app_rows, app_cols (which are now in PETSc ordering) for MatSetValues

2. Displaying Results

# After solve, convert solution indices for output
solution_indices = Int32[0, 1, 2, 3, 4]  # PETSc ordering

# Convert to application ordering for display
LibPETSc.AOPetscToApplication(petsclib, ao, length(solution_indices), solution_indices)

# Display in application order
# for i in solution_indices
#     println("Application DOF $i: value = ", solution[i])
# end

3. Integration with DM

# Get AO from DM
dm_ao = Ref{LibPETSc.AO}()
# LibPETSc.DMGetAO(petsclib, dm, dm_ao)

# Use for converting between natural and distributed orderings

Viewing and Debugging

# View the mapping (for debugging)
viewer = LibPETSc.PETSC_VIEWER_STDOUT_SELF(petsclib)
LibPETSc.AOView(petsclib, ao, viewer)

AO Types

Available types (set with AOSetType):

AOBASIC: Hash table based, good for general use
AOMEMSCALABLE: Memory efficient for large problems
AOMAPPING1TO1: Optimized for one-to-one mappings

Performance Tips

Reuse AO objects: Creation can be expensive for large problems
Batch conversions: Convert arrays rather than individual indices
Use identity when possible: Skip AO entirely if orderings match
Choose appropriate type: AOMEMSCALABLE for very large problems

Function Reference

PETSc.LibPETSc.AOApplicationToPetsc — Method

AOApplicationToPetsc(petsclib::PetscLibType,ao::AO, n::PetscInt, ia::Vector{PetscInt})

Maps a set of integers in the application ordering to the PETSc ordering.

Collective

Input Parameters:

ao - the application ordering context
n - the number of integers
ia - the integers; these are replaced with their mapped value

Output Parameter:

ia - the mapped integers

Level: beginner

-seealso: , AOCreateBasic(), AOView(), AOPetscToApplication(), AOPetscToApplicationIS()

External Links

PETSc Manual: Vec/AOApplicationToPetsc

source

PETSc.LibPETSc.AOApplicationToPetscIS — Method

AOApplicationToPetscIS(petsclib::PetscLibType,ao::AO, is::IS)

Maps an index set in the application ordering to the PETSc ordering.

Collective

Input Parameters:

ao - the application ordering context
is - the index set; this is replaced with its mapped values

Output Parameter:

is - the mapped index set

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOPetscToApplication(), AOPetscToApplicationIS(), AOApplicationToPetsc(), ISSTRIDE, ISBLOCK

External Links

PETSc Manual: Vec/AOApplicationToPetscIS

source

PETSc.LibPETSc.AOApplicationToPetscPermuteInt — Method

AOApplicationToPetscPermuteInt(petsclib::PetscLibType,ao::AO, block::PetscInt, array::Vector{PetscInt})

Permutes an array of blocks of integers in the application-defined ordering to the PETSc ordering.

Collective

Input Parameters:

ao - The application ordering context
block - The block size
array - The integer array

Output Parameter:

array - The permuted array

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOPetscToApplicationIS(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOApplicationToPetscPermuteInt

source

PETSc.LibPETSc.AOApplicationToPetscPermuteReal — Method

AOApplicationToPetscPermuteReal(petsclib::PetscLibType,ao::AO, block::PetscInt, array::Vector{PetscReal})

Permutes an array of blocks of reals in the application-defined ordering to the PETSc ordering.

Collective

Input Parameters:

ao - The application ordering context
block - The block size
array - The integer array

Output Parameter:

array - The permuted array

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()

External Links

PETSc Manual: Vec/AOApplicationToPetscPermuteReal

source

PETSc.LibPETSc.AOCreate — Method

ao::AO = AOCreate(petsclib::PetscLibType,comm::MPI_Comm)

Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa

Collective

Input Parameter:

comm - MPI communicator that is to share the AO

Output Parameter:

ao - the new application ordering

Options Database Key:

-ao_type <aotype> - create AO with particular format
-ao_view - call AOView() at the conclusion of AOCreate()

Level: beginner

-seealso: , AO, AOView(), AOSetIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOCreate

source

PETSc.LibPETSc.AOCreateBasic — Method

aoout::AO = AOCreateBasic(petsclib::PetscLibType,comm::MPI_Comm, napp::PetscInt, myapp::Vector{PetscInt}, mypetsc::Vector{PetscInt})

Creates a basic application ordering using two integer arrays.

Collective

Input Parameters:

comm - MPI communicator that is to share AO
napp - size of myapp and mypetsc
myapp - integer array that defines an ordering
mypetsc - integer array that defines another ordering (may be NULL to

indicate the natural ordering, that is 0,1,2,3,...)

Output Parameter:

aoout - the new application ordering

Level: beginner

-seealso: , , AO, AOCreateBasicIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOCreateBasic

source

PETSc.LibPETSc.AOCreateBasicIS — Method

aoout::AO = AOCreateBasicIS(petsclib::PetscLibType,isapp::IS, ispetsc::IS)

Creates a basic application ordering using two IS index sets.

Collective

Input Parameters:

isapp - index set that defines an ordering
ispetsc - index set that defines another ordering (may be NULL to use the natural ordering)

Output Parameter:

aoout - the new application ordering

Level: beginner

-seealso: , , IS, AO, AOCreateBasic(), AODestroy()

External Links

PETSc Manual: Vec/AOCreateBasicIS

source

PETSc.LibPETSc.AOCreateMapping — Method

aoout::AO = AOCreateMapping(petsclib::PetscLibType,comm::MPI_Comm, napp::PetscInt, myapp::Vector{PetscInt}, mypetsc::Vector{PetscInt})

Creates an application mapping using two integer arrays.

Input Parameters:

comm - MPI communicator that is to share the AO
napp - size of integer arrays
myapp - integer array that defines an ordering
mypetsc - integer array that defines another ordering (may be NULL to indicate the identity ordering)

Output Parameter:

aoout - the new application mapping

Options Database Key:

-ao_view - call AOView() at the conclusion of AOCreateMapping()

Level: beginner

-seealso: , AOCreateBasic(), AOCreateMappingIS(), AODestroy()

External Links

PETSc Manual: Vec/AOCreateMapping

source

PETSc.LibPETSc.AOCreateMappingIS — Method

aoout::AO = AOCreateMappingIS(petsclib::PetscLibType,isapp::IS, ispetsc::IS)

Creates an application mapping using two index sets.

Input Parameters:

isapp - index set that defines an ordering
ispetsc - index set that defines another ordering, maybe NULL for identity IS

Output Parameter:

aoout - the new application ordering

Options Database Key:

-ao_view - call AOView() at the conclusion of AOCreateMappingIS()

Level: beginner

-seealso: , , AOCreateBasic(), AOCreateMapping(), AODestroy()

External Links

PETSc Manual: Vec/AOCreateMappingIS

source

PETSc.LibPETSc.AOCreateMemoryScalable — Method

aoout::AO = AOCreateMemoryScalable(petsclib::PetscLibType,comm::MPI_Comm, napp::PetscInt, myapp::Vector{PetscInt}, mypetsc::Vector{PetscInt})

Creates a memory scalable application ordering using two integer arrays.

Collective

Input Parameters:

comm - MPI communicator that is to share the AO
napp - size of myapp and mypetsc
myapp - integer array that defines an ordering
mypetsc - integer array that defines another ordering (may be NULL to indicate the natural ordering, that is 0,1,2,3,...)

Output Parameter:

aoout - the new application ordering

Level: beginner

-seealso: , , AO, AOCreateMemoryScalableIS(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOCreateMemoryScalable

source

PETSc.LibPETSc.AOCreateMemoryScalableIS — Method

aoout::AO = AOCreateMemoryScalableIS(petsclib::PetscLibType,isapp::IS, ispetsc::IS)

Creates a memory scalable application ordering using two index sets.

Collective

Input Parameters:

isapp - index set that defines an ordering
ispetsc - index set that defines another ordering (may be NULL to use the natural ordering)

Output Parameter:

aoout - the new application ordering

Level: beginner

-seealso: , , AO, AOCreateBasicIS(), AOCreateMemoryScalable(), AODestroy()

External Links

PETSc Manual: Vec/AOCreateMemoryScalableIS

source

PETSc.LibPETSc.AODestroy — Method

AODestroy(petsclib::PetscLibType,ao::AO)

Destroys an application ordering.

Collective

Input Parameter:

ao - the application ordering context

Level: beginner

-seealso: , AO, AOCreate()

External Links

PETSc Manual: Vec/AODestroy

source

PETSc.LibPETSc.AOFinalizePackage — Method

AOFinalizePackage(petsclib::PetscLibType)

This function finalizes everything in the AO package. It is called from PetscFinalize().

Level: developer

-seealso: AOInitializePackage(), PetscInitialize()

External Links

PETSc Manual: Vec/AOFinalizePackage

source

PETSc.LibPETSc.AOGetType — Method

type::AOType = AOGetType(petsclib::PetscLibType,ao::AO)

Gets the AO type name (as a string) from the AO.

Not Collective

Input Parameter:

ao - The vector

Output Parameter:

type - The AO type name

Level: intermediate

-seealso: AO, AOType, AOSetType(), AOCreate()

External Links

PETSc Manual: Vec/AOGetType

source

PETSc.LibPETSc.AOInitializePackage — Method

AOInitializePackage(petsclib::PetscLibType)

This function initializes everything in the AO package. It is called from PetscDLLibraryRegister_petscvec() when using dynamic libraries, and on the first call to AOCreate() when using static or shared libraries.

Level: developer

-seealso: AOFinalizePackage(), PetscInitialize()

External Links

PETSc Manual: Vec/AOInitializePackage

source

PETSc.LibPETSc.AOMappingHasApplicationIndex — Method

hasIndex::PetscBool = AOMappingHasApplicationIndex(petsclib::PetscLibType,ao::AO, idex::PetscInt)

Checks if an AO has a requested application index.

Not Collective

Input Parameters:

ao - The AO
idex - The application index

Output Parameter:

hasIndex - Flag is PETSC_TRUE if the index exists

Level: intermediate

-seealso: , AOMappingHasPetscIndex(), AOCreateMapping(), AO

External Links

PETSc Manual: Vec/AOMappingHasApplicationIndex

source

PETSc.LibPETSc.AOMappingHasPetscIndex — Method

hasIndex::PetscBool = AOMappingHasPetscIndex(petsclib::PetscLibType,ao::AO, idex::PetscInt)

checks if an AO has a requested PETSc index.

Not Collective

Input Parameters:

ao - The AO
idex - The PETSc index

Output Parameter:

hasIndex - Flag is PETSC_TRUE if the index exists

Level: intermediate

-seealso: , AOMappingHasApplicationIndex(), AOCreateMapping()

External Links

PETSc Manual: Vec/AOMappingHasPetscIndex

source

PETSc.LibPETSc.AOPetscToApplication — Method

AOPetscToApplication(petsclib::PetscLibType,ao::AO, n::PetscInt, ia::Vector{PetscInt})

Maps a set of integers in the PETSc ordering to the application-defined ordering.

Collective

Input Parameters:

ao - the application ordering context
n - the number of integers
ia - the integers; these are replaced with their mapped value

Output Parameter:

ia - the mapped integers

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()

External Links

PETSc Manual: Vec/AOPetscToApplication

source

PETSc.LibPETSc.AOPetscToApplicationIS — Method

AOPetscToApplicationIS(petsclib::PetscLibType,ao::AO, is::IS)

Maps an index set in the PETSc ordering to the application-defined ordering.

Collective

Input Parameters:

ao - the application ordering context
is - the index set; this is replaced with its mapped values

Output Parameter:

is - the mapped index set

Level: intermediate

-seealso: , AO, AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOApplicationToPetscIS(), AOPetscToApplication(), ISSTRIDE, ISBLOCK

External Links

PETSc Manual: Vec/AOPetscToApplicationIS

source

PETSc.LibPETSc.AOPetscToApplicationPermuteInt — Method

AOPetscToApplicationPermuteInt(petsclib::PetscLibType,ao::AO, block::PetscInt, array::Vector{PetscInt})

Permutes an array of blocks of integers in the PETSc ordering to the application-defined ordering.

Collective

Input Parameters:

ao - The application ordering context
block - The block size
array - The integer array

Output Parameter:

array - The permuted array

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()

External Links

PETSc Manual: Vec/AOPetscToApplicationPermuteInt

source

PETSc.LibPETSc.AOPetscToApplicationPermuteReal — Method

AOPetscToApplicationPermuteReal(petsclib::PetscLibType,ao::AO, block::PetscInt, array::Vector{PetscReal})

Permutes an array of blocks of reals in the PETSc ordering to the application-defined ordering.

Collective

Input Parameters:

ao - The application ordering context
block - The block size
array - The integer array

Output Parameter:

array - The permuted array

Level: beginner

-seealso: , AO, AOCreateBasic(), AOView(), AOApplicationToPetsc(), AOPetscToApplicationIS()

External Links

PETSc Manual: Vec/AOPetscToApplicationPermuteReal

source

PETSc.LibPETSc.AORegister — Method

AORegister(petsclib::PetscLibType,sname::String, fnc::external)

Not Collective, No Fortran Support

Input Parameters:

sname - the name (AOType) of the AO scheme
function - the create routine for the application ordering method

Level: advanced

-seealso: AO, AOType, AOCreate(), AORegisterAll(), AOBASIC, AOADVANCED, AOMAPPING, AOMEMORYSCALABLE

External Links

PETSc Manual: Vec/AORegister

source

PETSc.LibPETSc.AORegisterAll — Method

AORegisterAll(petsclib::PetscLibType)

Registers all of the application ordering components in the AO package.

Not Collective

Level: advanced

-seealso: AO, AOType, AORegister(), AORegisterDestroy()

External Links

PETSc Manual: Vec/AORegisterAll

source

PETSc.LibPETSc.AOSetFromOptions — Method

AOSetFromOptions(petsclib::PetscLibType,ao::AO)

Sets AO options from the options database.

Collective

Input Parameter:

ao - the application ordering

Options Database Key:

-ao_type <basic, memoryscalable> - sets the type of the AO

Level: beginner

-seealso: , AO, AOCreate(), AOSetType(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOSetFromOptions

source

PETSc.LibPETSc.AOSetIS — Method

AOSetIS(petsclib::PetscLibType,ao::AO, isapp::IS, ispetsc::IS)

Sets the IS associated with the application ordering.

Collective

Input Parameters:

ao - the application ordering
isapp - index set that defines an ordering
ispetsc - index set that defines another ordering (may be NULL to use the natural ordering)

Level: beginner

-seealso: , , AO, AOCreate(), AODestroy(), AOPetscToApplication(), AOApplicationToPetsc()

External Links

PETSc Manual: Vec/AOSetIS

source

PETSc.LibPETSc.AOSetType — Method

AOSetType(petsclib::PetscLibType,ao::AO, method::AOType)

Builds an application ordering for a particular AOType

Collective

Input Parameters:

ao - The AO object
method - The name of the AO type

Options Database Key:

-ao_type <type> - Sets the AO type; use -help for a list of available types

Level: intermediate

-seealso: AO, AOType, AOCreateBasic(), AOCreateMemoryScalable(), AOGetType(), AOCreate()

External Links

PETSc Manual: Vec/AOSetType

source

PETSc.LibPETSc.AOView — Method

AOView(petsclib::PetscLibType,ao::AO, viewer::PetscViewer)

Displays an application ordering.

Collective

Input Parameters:

ao - the application ordering context
viewer - viewer used for display

Level: intermediate

Options Database Key:

-ao_view - calls AOView() at end of AOCreate()

-seealso: , AO, PetscViewerASCIIOpen(), AOViewFromOptions()

External Links

PETSc Manual: Vec/AOView

source

PETSc.LibPETSc.AOViewFromOptions — Method

AOViewFromOptions(petsclib::PetscLibType,ao::AO, obj::PetscObject, name::String)

View an AO based on values in the options database

Collective

Input Parameters:

ao - the application ordering context
obj - optional object that provides the prefix used to search the options database
name - command line option

Level: intermediate

-seealso: , AO, AOView(), PetscObjectViewFromOptions(), AOCreate()

External Links

PETSc Manual: Vec/AOViewFromOptions

source