diff --git a/doc/RTD/source/ParameterFiles/output_selection.rst b/doc/RTD/source/ParameterFiles/output_selection.rst index 8100c97abdc8f2839cffa29c9683bcf68bea00f0..3c29d0a0cf588e17da02f74eaaf86b8cf497e4d2 100644 --- a/doc/RTD/source/ParameterFiles/output_selection.rst +++ b/doc/RTD/source/ParameterFiles/output_selection.rst @@ -60,34 +60,86 @@ CGS. Entries in the file look like: .. code:: YAML - SelectOutput: - # Particle Type Gas - Coordinates_Gas: 1 # Co-moving positions of the particles. ::: Conversion to physical CGS: a U_L [ cm ] - Velocities_Gas: 1 # Peculiar velocities of the stars. This is (a * dx/dt) where x is the co-moving positions of the particles. ::: Conversion to physical CGS: U_L U_t^-1 [ cm s^-1 ] - Masses_Gas: 1 # Masses of the particles. ::: Conversion to physical CGS: U_M [ g ] - SmoothingLengths_Gas: 1 # Co-moving smoothing lengths (FWHM of the kernel) of the particles. ::: Conversion to physical CGS: a U_L [ cm ] - -Users can select the particle fields to output in snapshot using the -YAML parameter file. In section ``SelectOutput``, users can demand to -remove a field by adding a parameter formatted in the following way -``field_parttype`` where ``field`` is the name of the field that is to -be removed (e.g. ``Masses``) and ``parttype`` is the type of particles -that contains this field (``Gas``, ``DM``, ``Stars`` or ``BH``). For -a parameter, the only values accepted are ``0`` (skip this field when -writing) or ``1`` (default, do not skip this field when writing). By -default all fields are written. - -This field is mostly used to remove unnecessary output by listing them -with 0's. A classic use-case for this feature is a DM-only simulation -(pure n-body) where all particles have the same mass. Outputting the -mass field in the snapshots results in extra i/o time and unnecessary -waste of disk space. The corresponding section of the ``yaml`` -parameter file would look like: + Default: + # Particle Type Gas + Coordinates_Gas: off # Co-moving positions of the particles : a U_L [ cm ] + Velocities_Gas: on # Peculiar velocities of the stars. This is (a * dx/dt) where x is the co-moving positions of the particles : U_L U_t^-1 [ cm s^-1 ] + Masses_Gas: on # Masses of the particles : U_M [ g ] + SmoothingLengths_Gas: on # Co-moving smoothing lengths (FWHM of the kernel) of the particles : a U_L [ cm ] + ... + +Users can select the particle fields to output in snapshot using a (separate) +YAML parameter file. By default, you can define a section `Default` at the +top level of this file (in the exact same way as the file dumped by using the +`-o` option in SWIFT). By default, all fields are written, but by using the +"off" string, you can force the code to skip over unwanted outputs. + +You must then, in the regular SWIFT parameter file, select the following +options: .. code:: YAML - - SelectOutput: - Masses_DM: 0 + + Snapshots: + select_output_on: 1 + select_output: your_select_output_yaml.yml + +This field is mostly used to remove unnecessary output by listing them with +0's. A classic use-case for this feature is a DM-only simulation (pure +n-body) where all particles have the same mass. Outputting the mass field in +the snapshots results in extra i/o time and unnecessary waste of disk space. +The corresponding section of the YAML file would look like: + +.. code:: YAML + + Default: + Masses_DM: off Entries can simply be copied from the ``output.yml`` generated by the ``-o`` runtime flag. + + +Combining Output Lists and Output Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to combine the behaviour of the output list and the select +output file. To do so, you will need to enable both the ``select_output`` and +``output_list`` options in your main ``parameter_file.yml`` as follows: + +.. code:: YAML + + Snapshots: + output_list_on: 1 + output_list: "output_list.txt" + select_output_on: 1 + select_output: "select_output.yml" + +A typical use case for such a scenario is the dumping of 'snapshots' and +so-called 'snipshots', containing less information than their full snapshot +cousins. To do this, we will define two top-level sections in our +``select_output.yml`` file as follows: +.. code:: YAML + + # Only turn off DM masses in snapshots, everything else is turned on + Snapshot: + Masses_DM: off + + # Turn off lots of stuff in snipshots! + Snipshot: + Metal_Mass_Fractions_Gas: off + Element_Mass_Fractions_Gas: off + ... + +To then select which outputs are 'snapshots' and which are 'snipshots', you +will need to add the ``Select Output`` column to the ``output_list.txt`` as +follows:: + + # Redshift, Select Output + 100.0, Snapshot + 90.0, Snipshot + 80.0, Snipshot + 70.0, Snipshot + 60.0, Snapshot + ... + +This will enable your simulation to perform partial dumps only at the outputs +labelled as ``Snipshot``. diff --git a/examples/parameter_example.yml b/examples/parameter_example.yml index fbd44cc56172a9cc1fb629afab9c7529e19a397e..1bc907c17f36c62c822ceee7b6163be012991f03 100644 --- a/examples/parameter_example.yml +++ b/examples/parameter_example.yml @@ -142,6 +142,8 @@ Snapshots: UnitTemp_in_cgs: 1 # (Optional) Unit system for the outputs (Kelvin) output_list_on: 0 # (Optional) Enable the output list output_list: snaplist.txt # (Optional) File containing the output times (see documentation in "Parameter File" section) + select_output_on: 0 # (Optional) Enable the output selection behaviour + select_output: selectoutput.yml # (Optional) File containing information to select outputs with (see documentation in the "Output Selection" section) # Parameters governing the logger snapshot system Logger: