Advanced Configuration

This tutorial demonstrates alternative ways of configuring wakeflow models not covered in the Quickstart Tutorial, including from files, dictionaries, and altering developer parameters. It is assumed that you have read the Quickstart Tutorial.

Configuring model from .yaml file

In the Quickstart Tutorial, running our model generated a .yaml file with all of the model parameters we used:

!ls HD_163296/quickstart_tutorial

0.5Mj                           quickstart_tutorial_config.yaml

If you would like to configure wakeflow from a .yaml file, the easiest way is to modify one that is created automatically by wakeflow such as the above, to ensure you get the formatting correct. Note that this configuration method requires that you specify ALL wakeflow parameters, it will NOT set unprovided values to default.

For this example, we will simply run an identical model to the tutorial using the above .yaml parameter file. We initialise the model as usual:

from wakeflow import WakeflowModel

hd163_model = WakeflowModel()

Model initialised.

Now we use the configure_from_file method to configure using quickstart_tutorial_config.yaml instead of using the usual configure method:

file_path = "HD_163296/quickstart_tutorial/quickstart_tutorial_config.yaml"

hd163_model.configure_from_file(file_path)

Model configured.
Model configuration read from file: HD_163296/quickstart_tutorial/quickstart_tutorial_config.yaml

And we are done. Running the model then proceeds as usual by the run method.

Configuring model from dictionary

You may also configure wakeflow using dictionaries, which is the easiest option if you are wanting to do a parameter space scan. This is because it is easy to iteratively create dictionaries with different model parameters. We can do this easily using the usual configure method and some Python magic. First, let’s assemble our dictionary. We can include as many or few wakeflow parameters as we want, those unspecified will be left as default values.

Lets create the dictionary. We need to ensure that each key corresponds exactly to an argument of the configure method. For the sake of the example we will stick to specifying only a few parameters and leaving the rest as default:

my_model_config = dict(
    name     = "advanced_config_tutorial",
    system   = "HD_163296",
    m_star   = 1.9,
    m_planet = 0.1
)

Now we initialise our model as ususal:

from wakeflow import WakeflowModel

hd163_model_2 = WakeflowModel()

Model initialised.

And now we give the dictionary to the configure method, prepended by two asterisks:

hd163_model_2.configure(**my_model_config)

Model configured.

That’s it! Very simple. Again, you could now run this model by using the run method.

Configuring developer parameters

Lastly, we cover here how to change the developer and numerical parameters (hereafter referred to as developer parameters). A full list/description of what these parameters are and do is available in the Reference section of the documentation under Wakeflow Parameters.

Please don’t change these parameters unless you have a good understanding of how it will effect your results. Some of these options if changed can completely invalidate or break the results. If you are interested in models that do not use the default values of the developer parameters please contact the lead developer Thomas Hilder at Thomas.Hilder@monash.edu to discuss what you are trying to achieve and if it is valid. It is very likely that these parameters do not do quite what you think they do.

For the reasons described above, these parameters are deliberately a little more obtuse to change. You cannot set them using either the configure or the configure_from_file methods.

We can find and change the developer parameters after configuring the model, so let us do that. We stick to the default values for the example:

from wakeflow import WakeflowModel

hd163_model_3 = WakeflowModel()

hd163_model_3.configure()

Model initialised.
Model configured.

Now, we can find all parameters in a dictionary under the WakeflowModel.model_params attribute. Printing this:

print(hd163_model_3.model_params)

{'name': 'default_results_dir', 'system': 'default_parent_dir', 'm_star': 1.0, 'm_planet': 0.1, 'r_outer': 500, 'r_inner': 100, 'r_planet': 250, 'phi_planet': 0, 'r_ref': None, 'r_c': 0, 'z_max': 3, 'q': 0.25, 'p': 1.0, 'hr': 0.1, 'dens_ref': 1.0, 'cw_rotation': False, 'grid_type': 'cartesian', 'n_x': 400, 'n_y': 400, 'n_r': 200, 'n_phi': 160, 'n_z': 50, 'r_log': False, 'make_midplane_plots': True, 'show_midplane_plots': True, 'dimensionless': False, 'include_planet': True, 'include_linear': True, 'save_perturbations': True, 'save_total': True, 'write_FITS': False, 'run_mcfost': False, 'inclination': -225, 'PA': 45, 'PAp': 45, 'temp_star': 9250, 'distance': 101.5, 'v_max': 3.2, 'n_v': 40, 'adiabatic_index': 1.6666667, 'damping_malpha': 0.0, 'CFL': 0.5, 'scale_box_l': 1.0, 'scale_box_r': 1.0, 'scale_box_ang_t': 1.0, 'scale_box_ang_b': 1.0, 'tf_fac': 1.0, 'show_teta_debug_plots': False, 'box_warp': True, 'use_box_IC': False, 'use_old_vel': False}

This is also a nice and quick way of checking the default parameter values to see if you want to change them, without having to refer to the documentation. The developer parameters of the above are

• adiabatic_index

• damping_malpha

• CFL

• scale_box

• scale_box_ang

• tf_fac

• show_teta_debug_plots

• box_warp

• use_box_IC

Suppose we wish to change CFL to a lower value, which has the effect of taking smaller time steps in the Burger’s equation solver for the wake propagation. We can do this by just overriding the value in the model_params dictionary:

hd163_model_3.model_params["CFL"] = 0.1

Now we would simply run the model as usual using the run method.

Changing the developer parameters must occur after calling configure or configure_from_file, and before calling run.