Importing data

The importers namespace holds functionality for importing data into SpECTRE. We currently support loading volume data files in the same format that is written by the observers.

Importing volume data

The importers::ElementDataReader parallel component is responsible for loading volume data and distributing it to elements of one or multiple array parallel components. As a first step, make sure you have added the importers::ElementDataReader to your Metavariables::component_list. Also make sure you have a Metavariables::Phase in which you will perform registration with the importer, and another in which you want to load the data. Here's an example for such Metavariables:

template <size_t Dim>
struct Metavariables {
  using component_list =
      tmpl::list<ElementArray<Dim, Grid::Fine, Metavariables>,
                 ElementArray<Dim, Grid::Coarse, Metavariables>,
                 TestDataWriter<Dim, Metavariables>,
                 importers::ElementDataReader<Metavariables>>;
 
  static constexpr const char* const help{"Test the volume data reader"};
  static constexpr bool ignore_unrecognized_command_line_options = false;
 
  enum class Phase { Initialization, Register, ImportData, TestResult, Exit };
 
  template <typename... Tags>
  static Phase determine_next_phase(
      const gsl::not_null<
          tuples::TaggedTuple<Tags...>*> /*phase_change_decision_data*/,
      const Phase& current_phase,
      const Parallel::CProxy_GlobalCache<
          Metavariables>& /*cache_proxy*/) noexcept {
    switch (current_phase) {
      case Phase::Initialization:
        return Phase::Register;
      case Phase::Register:
        return Phase::ImportData;
      case Phase::ImportData:
        return Phase::TestResult;
      default:
        return Phase::Exit;
    }
  }
 
  // NOLINTNEXTLINE(google-runtime-references)
  void pup(PUP::er& /*p*/) noexcept {}
};

To load volume data from a file, invoke the importers::Actions::ReadVolumeData iterable action in the phase_dependent_action_list of your array parallel component. Here's an example that will be explained in more detail below:

      Parallel::PhaseActions<
          typename Metavariables::Phase, Metavariables::Phase::Register,
          tmpl::list<importers::Actions::RegisterWithElementDataReader,
                     Parallel::Actions::TerminatePhase>>,
      Parallel::PhaseActions<
          typename Metavariables::Phase, Metavariables::Phase::ImportData,
          tmpl::list<importers::Actions::ReadVolumeData<
                         VolumeDataOptions<TheGrid>, import_fields>,
                     importers::Actions::ReceiveVolumeData<
                         VolumeDataOptions<TheGrid>, import_fields>,
                     Parallel::Actions::TerminatePhase>>,

• The importers::Actions::ReadVolumeData action will load the volume data file once per node on its first invocation by dispatching to importers::Actions::ReadAllVolumeDataAndDistribute on the importers::ElementDataReader nodegroup component. Subsequent invocations of these actions, e.g. from all other elements on the node, will do nothing. The data is distributed into the inboxes of all elements on the node under the importers::Tags::VolumeData tag using Parallel::receive_data.
• The importers::Actions::ReceiveVolumeData action waits for the volume data to be available and directly moves it into the DataBox. If you wish to verify or post-process the data before populating the DataBox, use your own specialized action in place of importers::Actions::ReceiveVolumeData.
• You need to register the elements of your array parallel component for receiving volume data. To do so, invoke the importers::Actions::RegisterWithElementDataReader action in an earlier phase, as shown in the example above.

The template parameters to the actions in the example above specify the volume data to load. The first template parameter is an option group that determines the file to read and the second parameter is a typelist of the tags to import and fill with the volume data. See the documentation of the importers::Actions::ReadAllVolumeDataAndDistribute action for details on these parameters. In the example above, the VolumeDataOptions is an option group that supplies information such as the file name. You provide an option group that represents the data you want to import. For example, we have the evolution::OptionTags::NumericInitialData that represents numeric initial data for an evolution. In our example, we created a new class like this:

template <Grid TheGrid>
struct VolumeDataOptions {
  using group = importers::OptionTags::Group;
  static std::string name() noexcept {
    return MakeString{} << TheGrid << "VolumeData";
  }
  static constexpr Options::String help = "Numeric volume data";
};

This results in a section in the input file that may look like this:

Importers:
  FineVolumeData:
    FileName: "Test_DataImporterAlgorithm2D_shared.h5"
    Subgroup: "fine_data"
    ObservationValue: 3.
  CoarseVolumeData:
    FileName: "Test_DataImporterAlgorithm2D_shared.h5"
    Subgroup: "coarse_data"
    ObservationValue: 2.