CCPP framework needs to be independent of any host model

[gold2718]

In order for the CCPP framework to function as a library that can be used with many host models, it should not require information for any host model to be in its repository.

[gold2718]

To facilitate this shift, I propose a new, simple interface to the CCPP framework, tentatively called ccpp_capgen. There are five categories of inputs to this function:

1. A list of physics scheme files (pathnames)
2. A list of relevant host-model files (pathnames)
3. A list of suite definition files (pathnames, may be empty)
4. Cap generation options (e.g., --static-build, --output-directory <pathname>, --verbose)
5. Preprocessor directives (e.g., -DDEBUG, used for correctly reading files with #if and #ifdef statements)

The output from ccpp-capgen is simply a list of generated cap files and a list of generated host-model code.

One approach to lists of files is to simply pass them in a file, one (input or output) pathname per line. This is easy for any scripting language or build system to create or to ingest. If this is used, the interface could be:

ccpp-capgen <scheme_pathnames> <host_pathnames> [--sdf-pathlist <sdf_pathnames> ]
                       [ --static-build ] [ --output-directory <pathname> ] [ --verbose ]
                       [ --preproc-directives <symbol>[,<symbol>[...]]]
                       [ --cap-pathlist <filename for list of cap files> ]
                       [ --host-pathlist <filename for list of host files> ]

Notes:

• The default for --output-directory could be the current working directory
• The default for --cap-pathlist could be something like capfiles.txt in the the output directory.
• The default for --host-pathlist could be something like hostfiles.txt in the output directory.
• --static-build could be replaced with --dynamic-build making static build the default.

Thoughts? Ideas? Ridicule?

[gold2718]

Notes from 2018-11-01 meeting: Add documentation generation switch to generate LaTeX and HTML documentation.

[gold2718]

In order to clarify when things happen in a CCPP suite, I would like to propose the following four suite 'groups' which are always created:

• <suite_name>_initialize:
  • This will be called once at the beginning of the run.
  • It will allocate any suite variables that need to exist for the entire run.
  • It will store host-model constants (e.g., dimension sizes, constituent indices, physical constants) as suite variables to lower the number of parameters that need to be passed to run-time groups.
  • It will call an optional <initialize> suite group (after above actions).
  • It will call any <scheme_name>_init routines (after above actions).
  • The interface to this group could be CCPP_initialize('<suite_name>').
• <suite_name>_timestep_inital:
  • This group is called once per time step before any other groups in the suite.
  • It will allocate any suite variables that need to exist for the entire time step.
  • It will call an optional <timestep_init> suite group (after above actions).
  • It will call any <scheme_name>_timestep_init routines (after above actions).
  • The interface to this group could be CCPP_timestep_init('<suite_name>').
  • It is an error to call this routine if CCPP_initialize('<suite_name>') has not been called or if CCPP_finalize('<suite_name>') has been called.
  • It is an error to call this routine if CCPP_timestep_final('<suite_name>') has not been called since the last call to this routine.
• <suite_name>_timestep_final:
  • This group is called once per time step after any other groups in the suite.
  • It will call any <scheme_name>_timestep_final routines (after above actions).
  • It will call an optional <timestep_final> suite group (after above actions).
  • It will deallocate any suite variables allocated by CCPP_timestep_init('<suite_name>') (after above actions).
  • The interface to this group could be CCPP_timestep_final('<suite_name>').
  • It is an error to call this routine if CCPP_timestep_init('<suite_name>') has not been called or if CCPP_finalize('<suite_name>') has been called.
  • It is an error to call this routine if CCPP_timestep_init('<suite_name>') has not been called since the last call to this routine.
• <suite_name>_finalize:
  • This will be called once at the end of the run.
  • It will call any <scheme_name>_final routines.
  • It will call an optional <finalize> suite group (after above action).
  • It will deallocate any suite variables allocated by CCPP_initialize('<suite_name>') (after above actions).
  • It is an error to call this routine if CCPP_initialize('<suite_name>') has not been called.
  • It is an error to call this routine if CCPP_timestep_init('<suite_name>') has been called but CCPP_timestep_final('<suite_name>') has not been called.
  • The interface to this group could be CCPP_finalize('<suite_name>').

'Suite Variables' are variables automatically created for the suite to handle data which is passed between suite parameterizations but not to or from the host model. Suite variables are implemented as module variables in the generated suite module file.

Note that these four groups cannot be called from a threaded region (they should be protected !$OMP MASTER block or equivalent`).