update documentation

- add new flags to the documentation

docs/TBG_macros.cfg

@@ -166,23 +166,26 @@ TBG_macroCount="--<species>_macroParticlesCount.period 100"
 TBG_countPerSuper="--<species>_macroParticlesPerSuperCell.period 100 --<species>_macroParticlesPerSuperCell.period 100"
 
 # Dump simulation data (fields and particles) to HDF5 files using libSplash.
-# Data is dumped every .period steps to the fileset .file.
-TBG_hdf5="--hdf5.period 100 --hdf5.file simData"
+# Data selected in .source is dumped every .period steps to the fileset .file.
+TBG_hdf5="--hdf5.period 100 --hdf5.file simData --hdf5.source 'species_all,fields_all'"
 
 # Dump simulation data (fields and particles) to ADIOS files.
 # Data is dumped every .period steps to the fileset .file.
-TBG_adios="--adios.period 100 --adios.file simData"
+TBG_adios="--adios.period 100 --adios.file simData --adios.source 'species_all,fields_all'"
 # see 'adios_config -m', e.g., for on-the-fly zlib compression
 #     (compile ADIOS with --with-zlib=<ZLIB_ROOT>)
 #   --adios.compression zlib
 # for parallel large-scale parallel file-systems:
 #   --adios.aggregators <N * 3> --adios.ost <N>
 # avoid writing meta file on massively parallel runs
-#   --adios.disable-meta
+#   --adios.disable-meta <B>
+#   B = 0 is equal to false, B = 1 is true
 # specify further options for the transports, see ADIOS manual
 # chapter 6.1.5, e.g., 'random_offset=1;stripe_count=4'
 #                      (FS chooses OST;user chooses striping factor)
 #   --adios.transport-params "semicolon_separated_list"
+# select data sources for the dump
+#   --adios.source <comma_seperated_list_of_data_sources>
 
 # Create a checkpoint that is restartable every --checkpoint.period steps
 #   http://git.io/PToFYg

docs/source/usage/plugins/adios.rst

@@ -28,19 +28,30 @@ One can e.g. disable the output of particles by setting:
 ^^^^^^^^^
 
 You can use ``--adios.period`` and ``--adios.file`` to specify the output period and path and name of the created fileset.
-For example, ``--adios.period 128 --adios.file simData`` will write the simulation data to files of the form ``simData_0.bp``, ``simData_128.bp`` in the default simulation output directory every 128 steps.
+For example, ``--adios.period 128 --adios.file simData --adios.source 'species_all'`` will write only the particle species data to files of the form ``simData_0.bp``, ``simData_128.bp`` in the default simulation output directory every 128 steps.
 Note that this plugin will only be available if ADIOS is found during compile configuration.
 
 ============================ ==================================================================================================================================================================
 PIConGPU command line option description
 ============================ ==================================================================================================================================================================
-``--adios.period``           Period after which simulation data should be stored on disk. Default is ``0``, which means that no data is stored.
-``--adios.file``             Relative or absolute fileset prefix for simulation data. If relative, files are stored under ``simOutput``. Default is ``simDataAdios``.
+``--adios.period``           Period after which simulation data should be stored on disk.
+``--adios.file``             Relative or absolute fileset prefix for simulation data. If relative, files are stored under ``simOutput``.
 ``--adios.compression``      Set data transform compression method. See ``adios_config -m`` for which compression methods are available. This flag also influences compression for checkpoints.
 ``--adios.aggregators``      Set number of I/O aggregator nodes for ADIOS ``MPI_AGGREGATE`` transport method.
 ``--adios.ost``              Set number of I/O OSTs for ADIOS ``MPI_AGGREGATE`` transport method.
+``--adios.disable-meta``     Disable on-defly creation of the adios journal file.
+``--adios.source``           Select data sources to dump. Default is ``species_all,fields_all``, which dumps all fields and particle species.
 ============================ ==================================================================================================================================================================
 
+.. note::
+
+   This plugin is a multi plugin. 
+   Command line parameter can be used multiple times to create e.g. dumps with different dumping period.
+   In the case where a optional parameter with a default value is explicitly defined the parameter will be always passed to the instance of the multi plugin where the parameter is not set.
+   e.g. ``--adios.period 128 --adios.file simData1 --adios.source 'species_all' --adios.period 1000 --adios.file simData2 --adios.source 'fields_all' --adios.disable-meta 1`` creates two plugins:
+      - 1th. dump all species data each 128th time step, **do not create** the adios journal meta file.
+      - 2nd. dump all field data each 1000th time step but **create** the adios journal meta file.
+
 Additional Tools
 ^^^^^^^^^^^^^^^^
 

docs/source/usage/plugins/hdf5.rst

@@ -44,18 +44,26 @@ One can e.g. disable the output of particles by setting:
 ^^^^^^^^^
 
 You can use ``--hdf5.period`` and ``--hdf5.file`` to specify the output period and path and name of the created fileset.
-For example, ``--hdf5.period 128 --hdf5.file simData`` will write the simulation data to files of the form ``simData_0.h5``, ``simData_128.h5`` in the default simulation output directory every 128 steps.
+For example, ``--hdf5.period 128 --hdf5.file simData --hdf5.source 'species_all'`` will write only the particle species data to files of the form ``simData_0.h5``, ``simData_128.h5`` in the default simulation output directory every 128 steps.
 Note that this plugin will only be available if libSplash and HDF5 is found during compile configuration.
 
-============================ ======================================================================================
+============================ ================================================================================================================
 PIConGPU command line option Description
-============================ ======================================================================================
+============================ ================================================================================================================
 ``--hdf5.period``            Period after which simulation data should be stored on disk.
-                             Default is ``0``, which means that no data is stored.
 ``--hdf5.file``              Relative or absolute fileset prefix for simulation data.
                              If relative, files are stored under ``simOutput/``.
-                             Default is ``h5``.
-============================ ======================================================================================
+``--hdf5.source``            Select data sources to dump. Default is ``species_all,fields_all``, which dumps all fields and particle species.
+============================ ================================================================================================================
+
+.. note::
+
+   This plugin is a multi plugin. 
+   Command line parameter can be used multiple times to create e.g. dumps with different dumping period.
+   In the case where a optional parameter with a default value is explicitly defined the parameter will be always passed to the instance of the multi plugin where the parameter is not set.
+   e.g. ``--hdf5.period 128 --hdf5.file simData1 --hdf5.period 1000 --hdf5.file simData2 --hdf5.source 'species_all'`` creates two plugins:
+      - 1th. dump **all species data** each 128th time step.
+      - 2nd. dump **all fields and species data** (this is the default) data each 1000th time step.
 
 Additional Tools
 ^^^^^^^^^^^^^^^^