1: /*
  2:    Types for the PETSc options database. Include petscoptions.h for the functions that operate on them.
  3: */
  4: #pragma once

  6: #include <petscsystypes.h>

  8: /* SUBMANSEC = Sys */

 10: /*E
 11:    PetscOptionSource - Records where a value in the PETSc options database came from, passed to options-database monitors

 13:    Values:
 14: +   `PETSC_OPT_CODE`         - the option was set by a call from inside source code, for example `PetscOptionsSetValue()`
 15: .   `PETSC_OPT_COMMAND_LINE` - the option came from the command-line arguments of the program
 16: .   `PETSC_OPT_FILE`         - the option came from an options file processed by `PetscOptionsInsertFile()` (or its YAML counterpart)
 17: .   `PETSC_OPT_ENVIRONMENT`  - the option came from the `PETSC_OPTIONS` (or related) environment variable
 18: -   `NUM_PETSC_OPT_SOURCE`   - sentinel; equals the number of valid option sources

 20:    Level: developer

 22: .seealso: `PetscOptions`, `PetscOptionsMonitorSet()`, `PetscOptionsMonitorDefault()`
 23: E*/
 24: typedef enum {
 25:   PETSC_OPT_CODE,
 26:   PETSC_OPT_COMMAND_LINE,
 27:   PETSC_OPT_FILE,
 28:   PETSC_OPT_ENVIRONMENT,
 29:   NUM_PETSC_OPT_SOURCE
 30: } PetscOptionSource;

 32: #define PETSC_MAX_OPTION_NAME 512
 33: /*S
 34:   PetscOptions - PETSc's runtime options database object; the holder of all PETSc command-line and configuration options for a session, looked up via `PetscOptionsGet*()`

 36:   Level: beginner

 38:   Notes:
 39:   Most PETSc API calls accept `NULL` for `PetscOptions`, meaning "the default global options database". Use `PetscOptionsCreate()` / `PetscOptionsPush()` to manage non-default databases (e.g. when reading options from a file).

 41:   Each `PetscObject` may also carry its own non-default options through `PetscObjectSetOptions()`.

 43: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscOptionsPush()`, `PetscOptionsPop()`, `PetscOptionsGetBool()`,
 44:           `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, `PetscOptionsGetString()`, `PetscOptionsSetValue()`, `PetscOptionsView()`
 45: S*/
 46: typedef struct _n_PetscOptions *PetscOptions;

 48: /*
 49:     See manual page for PetscOptionsBegin()

 51:     PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
 52:   options being handled with a PetscOptionsBegin/End()

 54: */
 55: /*E
 56:    PetscOptionType - Identifies the kind of value held by a `PetscOptionItem` inside a `PetscOptionsBegin()`/`PetscOptionsEnd()` block

 58:    Values:
 59: +   `OPTION_INT`          - a single `PetscInt`
 60: .   `OPTION_BOOL`         - a single `PetscBool`
 61: .   `OPTION_REAL`         - a single `PetscReal`
 62: .   `OPTION_FLIST`        - a selection from a registered `PetscFunctionList`
 63: .   `OPTION_STRING`       - a single string
 64: .   `OPTION_REAL_ARRAY`   - an array of `PetscReal`
 65: .   `OPTION_SCALAR_ARRAY` - an array of `PetscScalar`
 66: .   `OPTION_HEAD`         - a section heading inserted with `PetscOptionsHead()`
 67: .   `OPTION_INT_ARRAY`    - an array of `PetscInt`
 68: .   `OPTION_ELIST`        - a selection from an enumerated list of strings
 69: .   `OPTION_BOOL_ARRAY`   - an array of `PetscBool`
 70: -   `OPTION_STRING_ARRAY` - an array of strings

 72:    Level: developer

 74: .seealso: `PetscOptions`, `PetscOptionItem`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsReal()`
 75: E*/
 76: typedef enum {
 77:   OPTION_INT,
 78:   OPTION_BOOL,
 79:   OPTION_REAL,
 80:   OPTION_FLIST,
 81:   OPTION_STRING,
 82:   OPTION_REAL_ARRAY,
 83:   OPTION_SCALAR_ARRAY,
 84:   OPTION_HEAD,
 85:   OPTION_INT_ARRAY,
 86:   OPTION_ELIST,
 87:   OPTION_BOOL_ARRAY,
 88:   OPTION_STRING_ARRAY
 89: } PetscOptionType;

 91: /*S
 92:   PetscOptionItem - Internal record describing a single option (such as `-ksp_type`) inside a `PetscOptionsBegin()` / `PetscOptionsEnd()` block, holding its option name, help text, default value, and selected value

 94:   Level: developer

 96: .seealso: `PetscOptions`, `PetscOptionItems`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsBool()`
 97: S*/
 98: typedef struct _n_PetscOptionItem *PetscOptionItem;

100: /*S
101:   PetscOptionItems - Internal context object representing the set of options being processed inside a `PetscOptionsBegin()` / `PetscOptionsEnd()` block; holds a linked list of `PetscOptionItem`s, the option prefix and the owning `PetscObject`

103:   Level: developer

105: .seealso: `PetscOptions`, `PetscOptionItem`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscObjectOptionsBegin()`
106: S*/
107: typedef struct _n_PetscOptionItems *PetscOptionItems;