.. Output selection .. _Output_list_label: Output List ~~~~~~~~~~~ In the sections ``Snapshots``, ``Statistics``, ``StructureFinding``, ``LineOfSight``, ``PowerSpectrum``, and ``FOF`` 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. 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 If an output list is specified, the basic values for the first snapshot (``time_first``, ``scale_factor_first``) and difference (``delta_time``) are ignored. 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. Note that if a simulation is restarted using check-point files, the list of outputs will be re-read. This means that it must be found on the disk at the same place as it was when the simulation was first started. It also implies that the content of the file can be altered if the need for additional snapshots suddenly arises. .. _Output_selection_label: Output Selection ~~~~~~~~~~~~~~~~ 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 co-moving units to physical CGS. Entries in the file look like: .. code:: YAML 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 ] ... For cosmological simulations, users can optionally add the ``--cosmology`` flag to generate the field names appropriate for such a run. 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. Users must then, in the regular SWIFT parameter file, select the following options: .. code:: YAML Snapshots: select_output_on: 1 select_output: your_select_output_yaml.yml 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 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. 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 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 Default: Standard_Gas: off Standard_DM: off Standard_DMBackground: off Standard_Stars: off Standard_BH: on # Not strictly necessary, on is already the default Additionally, users can use the different sections to specify an alternative base name and sub-directory for the snapshots corresponding to a given selection: .. code:: YAML Default: basename: bh subdir: snip This will put the outputs corresponding to this "BlackHolesOnly" selection into a sub-directory called ``snip`` and have the files themselves called ``bh_0000.hdf5`` where the number corresponds to the global number of snapshots. The counter is global and not reset for each type of selection. If the basename or sub-directory keywords are omitted then the code will use the default values specified in the ``Snapshots`` section of the main parameter file. The sub-directories are created when writing the first snapshot of a given category; the onus is hence on the user to ensure correct writing permissions ahead of that time. Finally, it is possible to specify individual sub-sampling ratios for each output selection: .. code:: YAML Default: subsample: [0, 1, 0, 0, 0, 0, 1] # Sub-sample the DM and neutrinos subsmple_fractions: [0, 0.01, 0, 0, 0, 0, 0.1] If these keywords are omitted then the code will use the default values specified in the ``Snapshots`` section of the main parameter file. 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 and compress lots of stuff in snipshots! Snipshot: Metal_Mass_Fractions_Gas: off Element_Mass_Fractions_Gas: off Densities_Gas: FMantissa9 basename: snip subsample: [0, 1, 0, 0, 0, 0, 1] # Sub-sample the DM and neutrinos subsmple_fractions: [0, 0.01, 0, 0, 0, 0, 0.1] ... 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``. 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``. Note that if a the name used in the ``Select Output`` column does not exist as a section in the output selection YAML file, SWIFT will exit with an error message. Using non-regular snapshot numbers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In some cases it may be helpful to have snapshot numbers that do not simply increase by one each time. This could be used to encode the simulation time in the filename for instance. To achieve this, a third column can be added to the output list giving the snapshot labels to use for each output:: # Redshift, Select Output, Label 100.0, Snapshot, 100 90.0, Snapshot, 90 1.0, Snapshot, 1 ... The label has to be an integer. This will lead to the following snapshots being produced: .. code:: bash snap_100.hdf5 snap_90.hdf5 snap_1.hdf5 Assuming the snapshot basename (either global or set for the ``Snapshot`` output selection) was set to ``snap``. Note that to specify labels, the ``Select Output`` column needs to be specified.