Setting Up Experiments

Users / developers are encouraged to place their experiments in the experiments directory. The experiments/supercell_example is there as an example of how to set this up with an example driver, CMakeLists.txt file, and inputs input file directory using YAML formatting for input files. You will almost certainly also need to add a custom_modules directory with modules that do custom things for your experiment like generate statistics about the data you want to emulate with a ML model, generate / curate data for your ML model, and deploy a trained ML model.

Tips and Tricks

• Whenever you get data from the coupler, please ensure that it you only plan to read from it that you extract it as a const type, e.g., coupler.dm.get<real const,3>("water_vapor"). The coupler's DataManager object keeps track of variables that are potentially written to (meaning variables that are extracted as a non-const type). Everything to get from the DataManager object that doesn't have a const type is flagged as "dirty", i.e., potentially written to. Everything retrieved as a const data type does not set this flag. Since ML models only need to predict the data that changes, this makes it easier to understand what data to predict in an ML model using the trick in the next item of this list. You can retrieve the DataManager object with either coupler.get_data_manager_readonly() or coupler.get_data_manager_readwrite().
• If you're wanting to create a surrogate model for a given subroutine, you can identify the arrays that are written to by: (1) cleaning all entries of their "dirty bit", (2) running the module, and (3) printing all dirty arrays that were potentially written to. This can help guide you as to what data you should output when creating samples for ML model training. E.g.

coupler.dm.clean_all_entries();
my_timestepping_module( coupler , dtphys );
auto dirty_entries = coupler.dm.get_dirty_entries();
std::cout << "The following entries have potentially been written to: "
for (auto &entry : dirty_entries) { std::cout << entry << " , "; }
std::cout << std::endl;

• Use the coupler's cloning function to capture a coupler state before running a module. E.g.,

core::Coupler inputs;
coupler.clone_into( inputs );
my_timestepping_module( coupler , dtphys );
// Now that the module has run, the coupler is the output state of the module
// We can pass the input and output couplers to a custom module to generate data
//    for offline ML model training like the API below:
my_data_generation_module( input , coupler , dtphys , etime );