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