5. Values from everywhere

On a cluster, heat runs from a batch script: some values belong to the environment of the job, others to a configuration file shared by a whole study. FLAP reads both, with a fixed precedence:

! every option gets an environment variable: HEAT_THREADS, HEAT_RUN_NX, ...
call cli%init(progname='heat', version='v0.5', description='Solve the 2D heat equation on a square plate', &
              auto_envvar_prefix='HEAT')
call cli%add(switch='--threads', help='OpenMP threads', required=.false., act='store', def='1')
! the configuration file: heat.ini unless --config (or HEAT_CONFIG) names another one
call cli%add(switch='--config', help='Configuration file', required=.false., act='config', def='heat.ini')
call cli%add_group(group='run', description='Run a simulation')
call cli%add(group='run', switch='--nx', help='Cells along each direction', required=.false., act='store', def='64')
call cli%add(group='run', switch='--cfl', help='CFL number', required=.false., act='store', def='0.25')

• auto_envvar_prefix='HEAT' gives every option a variable: HEAT_THREADS, and HEAT_RUN_NX, HEAT_RUN_CFL for the options of run. The help shows them.
• act='config' makes --config the name of a configuration file, heat.ini by default (a missing default file is simply skipped):

# heat.ini: the defaults of a study
threads = 8
[run]
nx      = 256
cfl     = 0.4

The keys are the long switches without the dashes; a [section] holds the options of a command.

Where does each value come from?

For a simulation, the parameters of a run matter as much as its results. provenance reports every value with its source, ready for the header of a log file:

call cli%parse(error=error)
if (error /= 0) stop 1, quiet=.true.
! the header of the run log: every value and where it comes from
print '(A)', '# heat v0.5, parameters:'
print '(A)', cli%provenance()

$ heat run
# heat v0.5, parameters:
--threads = 8        [config: heat.ini]
--config  = heat.ini [default]
run --nx  = 256      [config: heat.ini]
run --cfl = 0.4      [config: heat.ini]

$ HEAT_THREADS=16 HEAT_RUN_CFL=0.3 heat run --nx 512
# heat v0.5, parameters:
--threads = 16       [environment: HEAT_THREADS]
--config  = heat.ini [default]
run --nx  = 512      [command line]
run --cfl = 0.3      [environment: HEAT_RUN_CFL]

$ heat --config study.ini run
# heat v0.5, parameters:
--threads = 2         [config: study.ini]
--config  = study.ini [command line]
run --nx  = 64        [default]
run --cfl = 0.25      [default]

$ heat run --help
usage: heat run [--nx value] [--cfl value] [--help] [--markdown] [--version]

Run a simulation

Optional switches:
  --nx value
      environment variable name "HEAT_RUN_NX"
      default value 64
      Cells along each direction
  --cfl value
      environment variable name "HEAT_RUN_CFL"
      default value 0.25
      CFL number
  --help, -h
      Print this help message
  --markdown, -md
      Save this help message in a Markdown file
  --version, -v
      Print version

For one option, cli%get_source(switch=...) returns the source as a constant (SOURCE_COMMANDLINE, SOURCE_ENVIRONMENT, SOURCE_CONFIG, SOURCE_DEFAULT). To make a run immune to the environment, use init(ignore_env=.true.).

What you learned

Generated environment variables, configuration files, the precedence of the sources, provenance. Reference: Advanced Features.

Next: 6. Validation.