output_selection.rst 5.7 KB
Newer Older
Matthieu Schaller's avatar
Matthieu Schaller committed
1
.. Output selection
lhausamm's avatar
lhausamm committed
2

3
.. _Output_list_label:
lhausamm's avatar
lhausamm committed
4

lhausamm's avatar
lhausamm committed
5 6 7
Output List
~~~~~~~~~~~

8 9 10 11 12
In the sections ``Snapshots``, ``Statistics`` and ``StructureFinding``, you can
specify the options ``output_list_on`` and ``output_list`` which receive an int
and a filename.  The ``output_list_on`` enable or not the output list and
``output_list`` is the filename containing the output times.  With the file
header, you can choose between writing redshifts, scale factors or times.
lhausamm's avatar
lhausamm committed
13

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
Example of file containing with times (in internal units)::

  # Time
  0.5
  1.5
  3.0
  12.5

Example of file with scale factors::

  # Scale Factor
  0.1
  0.2
  0.3

Example of file with redshift::

  # Redshift
  20
  15
  10
  5
lhausamm's avatar
lhausamm committed
36

37 38 39
If an output list is specified, the basic values for the first
snapshot (``time_first``, ``scale_factor_first``) and difference
(``delta_time``) are ignored.
40 41 42 43 44 45

When an output list is used SWIFT will not write a "0th" snapshot
straight after having read the ICs. Similarly, SWIFT will also *not*
write a snapshot at the end of a simulation unless a snapshot at the
final time is specified in the list.

46
.. _Output_selection_label:
47

lhausamm's avatar
lhausamm committed
48 49 50
Output Selection
~~~~~~~~~~~~~~~~

51 52 53 54 55 56 57 58 59 60 61
Users can generate a ``yaml`` file containing all the possible fields
available for a given configuration of SWIFT by running
``./swift --output-params output.yml`` or equivalently ``./swift -o
output.yml``. The file generated contains the list of fields that a
simulation running with this config would output in each snapshot. It
also lists the description string of each field and the unit
conversion string to go from internal comoving units to physical
CGS. Entries in the file look like:

.. code:: YAML

62 63 64 65 66 67 68 69
  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 ]
    ...

70 71 72
For cosmological simulations, users can optionally add the ``--cosmology`` flag
to generate the field names appropriate for such a run.

73 74 75 76 77 78
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.

Matthieu Schaller's avatar
Matthieu Schaller committed
79
Users must then, in the regular SWIFT parameter file, select the following
80
options:
81

82
.. code:: YAML
83 84 85 86 87

  Snapshots:
    select_output_on: 1
    select_output: your_select_output_yaml.yml

88 89 90
This field is mostly used to remove unnecessary output by listing them as
"off". 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
91 92 93 94 95 96 97
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
lhausamm's avatar
lhausamm committed
98

99 100
Entries can simply be copied from the ``output.yml`` generated by the
``-o`` runtime flag. 
101

Matthieu Schaller's avatar
Matthieu Schaller committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
Alternatively, instead of "on" or "off", users can also provide the name of
one of the :ref:`Compression_filters` to write the field with reduced
accuracy and reduced disk space. The corresponding YAML file would, for
example, look like:

.. code:: YAML

  Default:
    Coordinates_Gas: DScale6
    Masses_Gas: off
    Velocities_Gas: DScale1
    Densities_Gas: FMantissa9
    ParticleIDs_Gas: IntegerNBits
	 

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
For convenience, there is also the option to set a default output status for
all fields of a particular particle type. This can be used, for example, to
skip an entire particle type in certain snapshots (see below for how to define
per-snapshot output policies). This is achieved with the special ``Standard``
field for each particle type:

.. code:: YAML

   BlackHolesOnly:
     Standard_Gas: off
     Standard_DM: off
     Standard_DMBackground: off
     Standard_Stars: off
     Standard_BH: on  # Not strictly necessary, on is already the default

132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151

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:
152

153 154 155 156 157 158
.. code:: YAML

  # Only turn off DM masses in snapshots, everything else is turned on
  Snapshot:
    Masses_DM: off

Matthieu Schaller's avatar
Matthieu Schaller committed
159
  # Turn off and compress lots of stuff in snipshots!
160 161 162
  Snipshot:
    Metal_Mass_Fractions_Gas: off
    Element_Mass_Fractions_Gas: off
Matthieu Schaller's avatar
Matthieu Schaller committed
163
    Densities_Gas: FMantissa9
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
    ...

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
179 180 181
labelled as ``Snipshot``. The name of the output selection that corresponds
to your choice in the output list will be written to the snapshot header as
``Header/SelectOutput``.