Overview

PyGNOME is a complex package, however, it is fairly straightforward to write scripts to run the model for a variety of simulations.

Simulations with the gnome package are performed via a Model object. A model has model-level attributes such as the start time, run duration, and time step. It can be configured with a variety of Movers, Weatherers, and Spills to drive the model, and Outputters can output the model results in a number of formats.

The scripting module

The gnome package contains a large hierarchy of subpackages and modules that contain all of objects and functions that support the full functionality of the model. Therefore, creating objects and adding them to the model can involve importing classes from many different modules. To make this easier, all of the typically required classes and helper functions are made accessible via the “scripting” module. We recommend that you import it like so:

import gnome.scripting as gs

And then you can use most of the common objects needed for the model. For example:

model = gs.Model()

This is equivalent to:

import gnome
model = gnome.model.Model()

Working with dates and times

Internally, GNOME uses the python standard library datetime and timedelta functions. In most cases, you can pass objects of these types into GNOME. But for scripting convenience, most places that take a datetime object will also accept a ISO 8601 string, such as: “2015-01-01T12:15:00”

The gnome.scripting module also provides a number of shortcuts for creating timedelta objects: seconds, minutes, hours, days. You can use them like so:

gs.hours(3)  # for 3 hours
gs.days(2)  # for two days

Examples in this section will use the scripting module. In the following more detailed sections about specific object types, we may sometimes also show the full import path for clarity.

Simplest Example

For a first introduction to scripting with gnome, the example below will demonstrate how to set up and run the very simplest model possible. This example does not load any external data, but creates a simple map and movers manually. The “spill” is a conservative substance, i.e. a “passive tracer.”

This example is in the PyGNOME source under “scripts/example_scripts”, or can be downloaded here:

simple_script.py

Initialize the Model

The model is initialized to begin on New Years Day 2015 and run for 3 days with a model time step of 15 minutes:

import gnome.scripting as gs
start_time = "2015-01-01"
model = gs.Model(start_time=start_time,
                 duration=gs.days(3),
                 time_step=gs.minutes(15)
                 )

Create and Add a Map

Create a very simple map which is all water with a rectangle defined by four longitude/latitude points to specify the boundary of the model:

model.map = gs.GnomeMap(map_bounds=((-145, 48), (-145, 49),
                                    (-143, 49), (-143, 48))
                                    )

Create and Add Movers

The model needs one or more “Movers” to move the elements. In this case, a steady uniform current and random walk diffusion are demonstrated.

The SimpleMover class is used to specify a 0.2 m/s eastward current.

The RandomMover class simulates spreading due to turbulent motion via a random walk algorithm:

velocity = (.2, 0, 0)  # (u, v, w) in m/s
uniform_vel_mover = gs.SimpleMover(velocity)
#  random walk diffusion -- diffusion_coef in units of cm^2/s
random_mover = gs.RandomMover(diffusion_coef=2e4)

# the movers are added to the model
model.movers += uniform_vel_mover
model.movers += random_mover

Create and Add a Spill

Spills in gnome specify what, when, where, and how many elements are released into the model. The properties of the substance spilled (e.g. oil chemistry) are provided by a Substance Object. PyGNOME currently has two Substances available: NonWeatheringSubstance representing passive drifters, and GnomeOil, representing petroleum products with all the properties required for the oil weathering algorithms supplied with GNOME.

There are a number of “helper” functions and classes that can initialize various types of spills (for example, at a point or over a spatial area, at the surface or subsurface). See: Spills for more details.

A common spill type is created by the surface_point_line_spill. To set up an instantaneous release of a conservative substance at a point, it can be called with most of the defaults:

spill = gs.surface_point_line_spill(release_time=start_time,
                                    start_position=(-144, 48.5),
                                    num_elements=500)
model.spills += spill

  • The release time is set to the start_time previously defined to start the model.

  • The release location (start_position) is set to a (longitude, latitude) position.

  • The number of Lagrangian elements (particles) can be defined (defaults to 1000).

Create and Add an Outputter

Outputters save the model results in a variety of formats. Options include PNG images and saving the element information into netCDF files, shapefiles, or KML for further visualization and analysis. See Outputters for more details.

In this example, the Renderer class is used to save to an animated gif every 2 hours:

renderer = gs.Renderer(output_dir='./output/',
                       output_timestep=gs.hours(2),
                       # bounding box for the output images
                       viewport=((-145, 48), (-145, 49),
                                 (-143, 49), (-143, 48)),
                       formats=['gif']
                       )

model.outputters += renderer

  • The time step for output is set to 2 hours.

  • The bounding box (viewport) of the rendered map is set to be the same as those specified for the map object.

  • Renderer supports ‘bmp’, ‘jpg’, ‘jpeg’, ‘png’ and ‘gif’ – ‘gif’ will save out a single animated GIF file - the rest will output one image per output timestep.

Run the Model

Once the model is all set up, the simulation can be run.

To run the model for the entire duration:

model.full_run()

Results will be written to files based on the outputters added to the model – in this case, an animated GIF named anim.gif.

View the results

The renderer added to the model generates an animated GIF with a frame every 8 hours as specified in its creation.

It will have been saved in output dir relative to the directory that the script was executed from, as specified in the Renderer creation. The animation should show a cloud of elements moving east and spreading.