diff --git a/docs/configuration.md b/docs/configuration.md index e2e7102..8425ace 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,6 +2,8 @@ ## Configuration Overview +Where possible, configuration information includes items like default, input range or enum options, description, units, and value, and the configuration can be queried as demonstrated in these docs to get that information. + Configuration parameters are shown in `m.show_config()` for: * the specified `drift_model` (from `m._config` which for OpenDriftModel points to `m.o._config`) @@ -130,7 +132,13 @@ m.show_config("seed:oil_type") ## Specific Configuration Options -### Ocean Model +This section is split into two: first options that are available to all models (thus are handled in the Manager) and those for `OpenDriftModel` (the only model option currently). + +This is not currently a comprehensive list but a place where extra details are included that might not be clear or available elsewhere. For more information look at the configuration information (previous section) and the docstrings for each class. + +### Manager options, available to all models + +#### Ocean Model Setting up an ocean model is also referred to as `add_reader()`. @@ -185,8 +193,43 @@ m = ptm.OpenDriftModel(lon=4.0, lat=60.0, start_time=datetime(2015, 9, 22, 6), m.run_all() ``` +### OpenDriftModel options + +#### Drift model + +Though `OpenDrift` has more models available, the currently wrapped `drift_model` options in PTM are: + +* OceanDrift: physics-only scenario (default) +* Leeway: scenario for Search and Rescue of various objects at the surface +* OpenOil: oil spill scenarios +* LarvalFish: scenario for fish eggs and larvae that can grow + +Set these with e.g.: + +``` +m = ptm.OpenDriftModel(drift_model="OpenOil") +``` + +This selection sets some of the configuration details and export variables that are relevant for the simulation. + + +#### Export Variables + +All possible variables will be exported by default into the outfiles and available in memory (`m.o.history` and `m.o.history_metadata` or `m.o.get_property()` for `OpenDriftModel`). + +The full list of possible variables to be exported is available with + +``` +m.all_export_variables() +``` + +To limit the variables saved in the export file, input a list of just the variables that you want to save, keeping in mind that `['lon', 'lat', 'ID', 'status']` will also be included regardless. For example: +``` +m = ptm.OpenDriftModel(export_variables=[]) +``` + -### How to modify details for Stokes Drift +#### How to modify details for Stokes Drift Turn on (on by default): @@ -220,7 +263,7 @@ m.show_config(key='drift:tabularised_stokes_drift_fetch') ``` -### Vertical Mixing +#### Vertical Mixing The user can change the background diffusivity with diff --git a/particle_tracking_manager/cli.py b/particle_tracking_manager/cli.py index 4456e57..378ae73 100644 --- a/particle_tracking_manager/cli.py +++ b/particle_tracking_manager/cli.py @@ -110,6 +110,7 @@ def __call__(self, parser, namespace, values, option_string=None): # if args.kwargs["ocean_model"] is None and args.kwargs["start_time"] is None: # raise KeyError("Need to either use a reader or input a start_time to avoid error.") - ptm.OpenDriftModel(**args.kwargs).run_all() + m = ptm.OpenDriftModel(**args.kwargs) + m.run_all() - # ptm.ParticleTrackingManager(**args.kwargs).run_all() + print(m.outfile_name) diff --git a/particle_tracking_manager/models/opendrift/model_opendrift.py b/particle_tracking_manager/models/opendrift/model_opendrift.py index ee712a8..0c62e1f 100644 --- a/particle_tracking_manager/models/opendrift/model_opendrift.py +++ b/particle_tracking_manager/models/opendrift/model_opendrift.py @@ -4,6 +4,8 @@ import logging import pathlib +from typing import Optional + import pandas as pd import yaml @@ -49,6 +51,8 @@ class OpenDriftModel(ParticleTrackingManager): ---------- drift_model : str, optional Options: "OceanDrift", "LarvalFish", "OpenOil", "Leeway", by default "OceanDrift" + export_variables : list, optional + List of variables to export, by default None. See PTM docs for options. radius : int, optional Radius around each lon-lat pair, within which particles will be randomly seeded. This is used by function `seed_elements`. radius_type : str @@ -134,6 +138,7 @@ class OpenDriftModel(ParticleTrackingManager): def __init__( self, drift_model: str = config_model["drift_model"]["default"], + export_variables: str = config_model["export_variables"]["default"], radius: int = config_model["radius"]["default"], radius_type: str = config_model["radius_type"]["default"], horizontal_diffusivity: float = config_model["horizontal_diffusivity"][ @@ -482,6 +487,7 @@ def run_drifters(self): self.o.run( time_step=timedir * self.time_step, steps=self.steps, + export_variables=self.export_variables, outfile=f"output-results_{datetime.datetime.utcnow():%Y-%m-%dT%H%M:%SZ}.nc", ) @@ -577,6 +583,22 @@ def _add_model_config(self): # this step brings other model config (plus additions from mapped parameter config) into the overall config self._config.update(dictC) + def all_export_variables(self): + """Output list of all possible export variables.""" + + vars = ( + list(self.o.elements.variables.keys()) + + ["trajectory", "time"] + + list(self.o.required_variables.keys()) + ) + + return vars + + def export_variables(self): + """Output list of all actual export variables.""" + + return self.o.export_variables + def get_configspec(self, prefix, substring, level, ptm_level): """Copied from OpenDrift, then modified.""" @@ -705,3 +727,9 @@ def reader_metadata(self, key): if not self.has_added_reader: raise ValueError("reader has not been added yet.") return self.o.env.readers["roms native"].__dict__[key] + + @property + def outfile_name(self): + """Output file name.""" + + return self.o.outfile_name diff --git a/particle_tracking_manager/models/opendrift/opendrift_config.yaml b/particle_tracking_manager/models/opendrift/opendrift_config.yaml index 0a6670c..d7a95bd 100644 --- a/particle_tracking_manager/models/opendrift/opendrift_config.yaml +++ b/particle_tracking_manager/models/opendrift/opendrift_config.yaml @@ -12,6 +12,11 @@ drift_model: - Leeway description: Which model in OpenDrift to use. This corresponds to the type of drift scenario the user wants to run. +export_variables: + default: ["z"] + ptm_level: 1 + type: list + description: List of variables to export. Options available with `m.all_export_variables` for a given `drift_model`. ['lon', 'lat', 'ID', 'status'] will always be exported. radius: default: 0.0 diff --git a/particle_tracking_manager/the_manager.py b/particle_tracking_manager/the_manager.py index 5546da4..a68ecfc 100644 --- a/particle_tracking_manager/the_manager.py +++ b/particle_tracking_manager/the_manager.py @@ -424,5 +424,27 @@ def reader_metadata(self, key): pass def query_reader(self): - """Overwrite method in model.""" + """define in child class.""" + pass + + def all_export_variables(self): + """Output list of all possible export variables. + + define in child class. + """ + pass + + def export_variables(self): + """Output list of all actual export variables. + + define in child class. + """ + pass + + @property + def outfile_name(self): + """Output file name. + + define in child class. + """ pass