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::VolumeDataReader 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::VolumeDataReader to your Metavariables::component_list. Also make sure you have a Metavariables::Phase in which you will perform registration with the importer, and another for loading 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::VolumeDataReader<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 };

  static Phase determine_next_phase(
      const Phase& current_phase,
      const Parallel::CProxy_ConstGlobalCache<
          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;
    }
  }
};

To register elements of your array parallel component for receiving volume data, invoke the importers::Actions::RegisterWithVolumeDataReader action in the phase_dependent_action_list. Here's an example:

      Parallel::PhaseActions<
          typename Metavariables::Phase, Metavariables::Phase::Register,
          tmpl::list<importers::Actions::RegisterWithVolumeDataReader,
                     Parallel::Actions::TerminatePhase>>,

Now you're all set to load a data file. To do so, invoke the importers::ThreadedActions::ReadVolumeData action on the importers::VolumeDataReader. A good place for this is the execute_next_phase function of the array parallel component:

  using import_fields = tmpl::list<ScalarFieldTag, VectorFieldTag<Dim>>;

  using read_element_data_action = importers::ThreadedActions::ReadVolumeData<
      VolumeDataOptions<TheGrid>, import_fields,
      ::Actions::SetData<import_fields>, ElementArray>;

  static void execute_next_phase(
      const typename Metavariables::Phase next_phase,
      Parallel::CProxy_ConstGlobalCache<Metavariables>& global_cache) noexcept {
    auto& local_cache = *(global_cache.ckLocalBranch());
    Parallel::get_parallel_component<ElementArray>(local_cache)
        .start_phase(next_phase);

    if (next_phase == Metavariables::Phase::ImportData) {
      Parallel::threaded_action<read_element_data_action>(
          Parallel::get_parallel_component<
              importers::VolumeDataReader<Metavariables>>(local_cache));
    }
  }

In the first snippet the read_element_data_action type alias is set to a specialization of the importers::ThreadedActions::ReadVolumeData template. Its first template parameter specifies an option group that determines the data file to load, the second parameter is a typelist of the tags to import and fill with the volume data, the third parameter is the action that is called upon receiving the data on the array elements, and the last template parameter is the parallel component on which the callback action will be invoked. See the documentation of the importers::ThreadedActions::ReadVolumeData action for details on these parameters. Here is more information on the parameters used in the example above:

• The VolumeDataOptions in this example 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 OptionString 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.

• The Actions::SetData callback action in the example will be invoked to receive the data on each element. You can use this particular action to move the received data directly into the DataBox, but it's generally better to write a new action that does a few consistency checks on the data before moving it into the DataBox.

When the importers::ThreadedActions::ReadVolumeData is invoked, the data file will be read and its data distributed to all elements of the array that have been registered.