Line data    Source code

       1            0 : \cond NEVER
       2              : Distributed under the MIT License.
       3              : See LICENSE.txt for details.
       4              : \endcond
       5              : # Importing data {#dev_guide_importing}
       6              : 
       7              : \tableofcontents
       8              : 
       9              : The `importers` namespace holds functionality for importing data into SpECTRE.
      10              : We currently support loading volume data files in the same format that is
      11              : written by the `observers`.
      12              : 
      13              : ## Importing volume data
      14              : 
      15              : The `importers::ElementDataReader` parallel component is responsible for loading
      16              : volume data, interpolating it, and distributing it to elements of one or
      17              : multiple array parallel components. As a first step, make sure you have added
      18              : the `importers::ElementDataReader` to your `Metavariables::component_list`. Also
      19              : make sure you have a `Parallel::Phase` in which you will perform
      20              : registration with the importer, and another in which you want to load the data.
      21              : Here's an example for such `Metavariables`:
      22              : 
      23              : \snippet Test_VolumeDataReaderAlgorithm.hpp metavars
      24              : 
      25              : To load volume data from a file, write an action in which you invoke
      26              : `importers::Actions::ReadAllVolumeDataAndDistribute` on the
      27              : `importers::ElementDataReader`. For simple use cases we provide
      28              : `importers::Actions::ReadVolumeData`, which can be added to the
      29              : `phase_dependent_action_list` of your element array and which will generate
      30              : input-file options for you. Here's an example that will be explained in more
      31              : detail below:
      32              : 
      33              : \snippet Test_VolumeDataReaderAlgorithm.hpp import_actions
      34              : 
      35              : - The `importers::Actions::ReadVolumeData` action specifies input-file options
      36              :   and dispatches to `importers::Actions::ReadAllVolumeDataAndDistribute` on the
      37              :   `importers::ElementDataReader` nodegroup component. It loads the volume data
      38              :   file once per node on its first invocation. Subsequent invocations of these
      39              :   actions, e.g. from all other elements on the node, will do nothing. The data
      40              :   is distributed into the inboxes of all elements on the node under the
      41              :   `importers::Tags::VolumeData` tag using `Parallel::receive_data`.
      42              : - The `importers::Actions::ReceiveVolumeData` action waits for the volume data
      43              :   to be available and directly moves it into the DataBox. If you wish to verify
      44              :   or post-process the data before populating the DataBox, use your own
      45              :   specialized action in place of `importers::Actions::ReceiveVolumeData`.
      46              : - You need to register the elements of your array parallel component for
      47              :   receiving volume data. To do so, invoke the
      48              :   `importers::Actions::RegisterWithElementDataReader` action in an earlier
      49              :   phase, as shown in the example above.
      50              : 
      51              : The parameters passed to `importers::Actions::ReadAllVolumeDataAndDistribute`
      52              : specify the volume data to load. See the documentation of
      53              : `importers::Actions::ReadAllVolumeDataAndDistribute` for details. In the example
      54              : above, we use `importers::Actions::ReadVolumeData` to generate the input-file
      55              : options for us and place them in an option group:
      56              : 
      57              : \snippet Test_VolumeDataReaderAlgorithm.hpp option_group
      58              : 
      59              : This results in a section in the input file that may look like this:
      60              : 
      61              : \snippet Test_VolumeDataReaderAlgorithm2D.yaml importer_options