The CPPC Project

In the "Example" directory there is an example application which solves an equation system using the Gauss-Jordan method. There are two different versions. The system will build the appropriate one depending on whether you have chosen to build the MPI or the sequential version of CPPC.

1. Enter the "Example" directory.

2. Execute "make" to build all necessary targets.

3. The syntax accepted by the "gauss" executable, depending on whether or not CPPC has been built with MPI support, is:

   gauss <file1> <file2> <file3>

   or

   gauss-mpi <dimA> <dimB> <file1> <file2> <file3>

   Where:

   dimA	Rows in the grid of processors.
   dimB	Columns in the grid of processors.
   file1	File containing the system matrix.
   file2	File containing the independent terms vector
   file3	Output file.

   Hence, if the equation system to be solved is A.b=x, then <file1>=A, <file2>=b and x=<file3>.

4. Execution of the "gauss" file automatically uses the CPPC library. To achieve a suitable configuration for CPPC, a number of parameters must be defined. In the "Example" directory you will find a file called "cppc_config.example". This is an XML configuration file. Edit it and change it at will. Every CPPC plugin defines its own configuration parameters, and to allow for this the XML is structured in modules and parameters. The list of currently accepted options is:

   Module	Parameter	Description
   Controller	RootDir	Directory where CPPC will store and search for checkpoint files.
   	ApplicationName	Subdirectory of "RootDir" where checkpoint files will be effectively stored.
   	Restart	Controls whether the application must be restarted. It is highly recommended to set this to "false", and enforce restart using command-line parameters.
   	Frequency	Number of calls to CPPC_Do_checkpoint() between effective state dumping. Set to -1 to disable checkpointing.
   	FullFrequency	Number of effective checkpoint dumps in between two full checkpoints. Set to 1 to disable incremental checkpointing.
   	CheckpointOnFirstTouch	If this is set to "true", the state dumping will be performed every first time that a particular call to CPPC_Do_checkpoint() is reached.
   	Suffix	Suffix for the files being generated.
   	StoredRecoverySets	Maximum number of recovery sets stored (per node) before beginning deletion of the older ones as new ones are being created. A recovery set is composed of a full checkpoint plus a number of incremental to be applied on top of it. Set to 1 to store only the latest recovery set (not recommended if using MPI). Set to -1 to disable deletion of created checkpoints.
   	DeleteCheckpoints	If set to "true", stored checkpoints will be removed upon successful execution.
   Writer	Type	Type of writer used. See note a).
   Writer/HDF-5	Compression	Type of compression used by the HDF-5 writer. See note b).
   Writer/HDF-5	CompressionLevel	Level of compression used by the ZLib compressor. It is an integer in the 0-9 range, 9 being the maximum compression level.
   Writer/HDF-5	MinimumSize	An integer defining the minimum data size for enabling compression. E.g., if set to 100, any array with less than a hundred elements will not be compressed, but stored directly.

   1. Currently there is just one valid value for this parameter:

      3	HDF-5 writer

   2. Two valid values:

      None	No compression.
      ZLib	ZLib compression. When this is enabled, it is mandatory to also include the HDF-5/CompressionLevel and HDF-5/MinimumSize parameters.

   ** NOTE: In order for CPPC to find the configuration file, copy it to $HOME/.cppc_config, or use the CPPC/Configuration/FilePath command-line parameter (see 5). A configuration file example can be found under Example/cppc-config.example.

   For compatibility with older versions, CPPC also accepts XML configuration files. An example of the equivalent XML configuration file can be found under Example/cppc-config.xml. The DTD for the configuration file can be found under include/util/xml/cppc-config.dtd. XML configuration files are deprecated and will go away at some point.

5. CPPC accepts command-line parameters that overwrite those set in the configuration file. Used syntaxis, supposing we are running the "gauss" application, is:

   gauss <gauss-params> -CPPC,<CPPC-Param-1>,<CPPC-Param-2>,...

   Where every CPPC-Param has the following structure:

   CPPC/<Module>/<Submodule>/.../<Parameter>=<value>

   For instance, if we want to use the configuration file /tmp/cppc-config and command CPPC to restart the application, we will use:

   gauss <gauss-params> -CPPC,CPPC/Configuration/FilePath=/tmp/cppc-config,CPPC/Controller/Restart=true

   Any parameter seen in the configuration file can have its value overwritten using a command-line parameter.

   Please note that the Fortran 77 version of the CPPC library does not accept command-line parameters, due to the Fortran 77 lack of a standard way for accessing them. It will be implemented in future versions of CPPC, shall we find a portable way to do it.