From 4cda41bc8af2d1a7be1dda590fc10f1b3a9254a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Widera?= Date: Wed, 6 Dec 2017 14:20:59 +0100 Subject: [PATCH] update documentation - add new flags to the documentation --- docs/TBG_macros.cfg | 11 +++++++---- docs/source/usage/plugins/adios.rst | 17 ++++++++++++++--- docs/source/usage/plugins/hdf5.rst | 20 ++++++++++++++------ 3 files changed, 35 insertions(+), 13 deletions(-) diff --git a/docs/TBG_macros.cfg b/docs/TBG_macros.cfg index 92fd6c6e0d..d9fc82b526 100644 --- a/docs/TBG_macros.cfg +++ b/docs/TBG_macros.cfg @@ -166,23 +166,26 @@ TBG_macroCount="--_macroParticlesCount.period 100" TBG_countPerSuper="--_macroParticlesPerSuperCell.period 100 --_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=) # --adios.compression zlib # for parallel large-scale parallel file-systems: # --adios.aggregators --adios.ost # avoid writing meta file on massively parallel runs -# --adios.disable-meta +# --adios.disable-meta +# 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 # Create a checkpoint that is restartable every --checkpoint.period steps # http://git.io/PToFYg diff --git a/docs/source/usage/plugins/adios.rst b/docs/source/usage/plugins/adios.rst index feb03c6a0a..9897c84e89 100644 --- a/docs/source/usage/plugins/adios.rst +++ b/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 ^^^^^^^^^^^^^^^^ diff --git a/docs/source/usage/plugins/hdf5.rst b/docs/source/usage/plugins/hdf5.rst index c0d1334b1c..97d0515459 100644 --- a/docs/source/usage/plugins/hdf5.rst +++ b/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 ^^^^^^^^^^^^^^^^