Release Groups¶
[This note-book is in oceantracker/tutorials_how_to/]
A release group is a set of particles released at the same times and location. There can be many release groups. This enables the fate of particles from different origins to be tracked separately within the same computational run. Importantly, on the fly statistics are separated into release groups. Eg. gridded statistics return a heat map for each release group, while polygon statistics give the connectivity between each given polygon and each release group.
A release group may be a:
“point_releases” set points, giving one or more 2D or 3D locations where particles are released. A radius for 2D release around theses point also can be set.
“polygon release”, where particles are released randomly within polygon made up of 3 or more 2D points. Particles will not be released in any parts of the polygon outside the domain.
“grid_release”, particles released from points on a regular grid.
For polygons, the vertical release location is randomly chosen in the water column, or user a given in z range. If the z value of a point release is not given, then the vertical release location is chosen in the same manner.
For both types user can specify:
time to start and end the release, or the duration of the release. Defaults are to start at beginning of hindcast and continue until it’s end.
the time between releases, the “release_interval”, a zero value gives a single release.
the number of particles release each time, the “pulse_size”
whether to release in dry cells, default “allow_release_in_dry_cells” = False
Plus other options see:
add links…
# show example of release types with start and end times,
#------------------------------------------------
from oceantracker.main import OceanTracker
ot = OceanTracker()
# ot.settings method use to set basic settings
ot.settings(output_file_base='minimal_example', # name used as base for output files
root_output_dir='output', # output is put in dir 'root_output_dir'\\'output_file_base'
time_step= 120. # 2 min time step as seconds
)
# ot.set_class, sets parameters for a named class
ot.add_class('reader',input_dir= '../demos/demo_hindcast/schsim3D', # folder to search for hindcast files, sub-dirs will, by default, also be searched
file_mask= 'demo_hindcast_schisim3D*.nc') # hindcast file mask
# add point release locations from two points,
ot.add_class('release_groups',
class_name='PointRelease', # point is the default so no needed for point example
points= [[1595000, 5482600, -1], #[x,y,z(optional)] pairs of release locations
[1595000, 5486200, -1]], # must be an N by 2 or 3 or list, convertible to a numpy array
release_interval= 1800, # seconds between releasing particles
pulse_size= 10, # number of particles released each release_interval
)
# add a polygon release
ot.add_class('release_groups',
class_name='PolygonRelease', # class to use
# (x,y) points making up a 2D polygon
points=[[1597682., 5486972], [1598604, 5487275], [1598886, 5486464],
[1597917., 5484000], [1597300, 5484000], [1597682, 5486972]],
# the below are optional settings/parameters
release_interval=3600,
pulse_size=10,
z_min=-2., z_max=0.5) # set a z range to release, in default is full water depth
ot.add_class('release_groups',
class_name='GridRelease', # class to use
start='2017-01-01T02:30:00', # optional start and end times
grid_center=[1592000, 5489200], # location of grid centre
grid_span=[500, 1000], # size of grid in meters
grid_size=[3, 4], # rows and columns in grid
release_interval=1800,
pulse_size=2,
z_min=-2, z_max=-0.5) # release at random depth between these values
# run oceantracker
case_info_file_name = ot.run()
helper ---------------------------------------------------------------------- helper Starting OceanTracker helper class helper - Starting run using helper class Main Python version: 3.11.9 | packaged by conda-forge | (main, Apr 19 2024, 18:27:10) [MSC v.1938 64 bit (AMD64)] Main >>> Warning: Oceantracker is not yet compatible with Python 3.11, as not all imported packages have been updated, eg netcdf4 Main ---------------------------------------------------------------------- Main OceanTracker starting main: Main Starting package set up Main - Built OceanTracker package tree, 0.602 sec Main - Built OceanTracker sort name map, 0.000 sec Main - Done package set up to setup ClassImporter, 0.602 sec Main >>> Warning: Deleted contents of existing output dir Main Output is in dir "f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_example" Main hint: see for copies of screen output and user supplied parameters, plus all other output Main >>> Note: to help with debugging, parameters as given by user are in "user_given_params.json" Main ---------------------------------------------------------------------- Main OceanTracker version 0.50.0010-2024-03-30 - preliminary setup Main - Found input dir "../demos/demo_hindcast/schsim3D" Main - found hydro-model files of type "SCHISM" Main Cataloging hindcast with 1 files in dir ../demos/demo_hindcast/schsim3D Main - Cataloged hydro-model files/variables in time order, 0.008 sec Main >>> Note: No bottom_stress variable in in hydro-files, using near seabed velocity to calculate friction_velocity for resuspension Main - sorted hyrdo-model files in time order, 0.030 sec prelim: Starting package set up prelim: - Built OceanTracker package tree, 0.008 sec prelim: - Built OceanTracker sort name map, 0.000 sec prelim: - Done package set up to setup ClassImporter, 0.009 sec C000 ---------------------------------------------------------------------- C000 Starting case number 0, minimal_example at 2024-09-04T08:34:23.887804 C000 ---------------------------------------------------------------------- C000 - Scanned OceanTracker to build short name map to the full class_names, 0.000 sec C000 >>> Note: Hydro-model is "3D" type "SCHISMreaderNCDF" C000 hint: Files found dir and sub-dirs of "../demos/demo_hindcast/schsim3D" C000 Start: 2017-01-01T00:30:00.000000000 end: 2017-01-01T23:30:00.000000000, time steps 24 C000 grid bounding box = [1589789.0 5479437.0] to [1603398.0 5501640.0] C000 - Starting grid setup C000 - built node to triangles map, 0.888 sec C000 - built triangle adjacency matrix, 0.156 sec C000 - found boundary triangles, 0.000 sec C000 - built domain and island outlines, 0.958 sec C000 - calculated triangle areas, 0.000 sec C000 - Finished grid setup C000 - built barycentric-transform matrix, 0.247 sec C000 >>> Note: Hydro-model grid in metres, all cords should be in meters, e.g. release group locations, gridded_stats grid C000 - Setup field group manager, 0.250 sec C000 - Added release groups and found run start and end times, 0.003 sec C000 - Done initial setup of all classes, 0.583 sec C000 >>> Note: Hydro-model grid in metres, all cords should be in meters, e.g. release group locations, gridded_stats grid C000 ---------------------------------------------------------------------- C000 - Starting minimal_example, duration: 0 days 23 hrs 0 min 0 sec C000 - Reading 24 time steps, for hindcast time steps 00:23, into ring buffer offsets 000:023 C000 - read 24 time steps in 0.9 sec C000 ---------------------------------------------------------------------- C000 - Starting time stepping: 2017-01-01T00:30:00 to 2017-01-01T23:30:00 , duration 0 days 23 hrs 0 min 0 sec C000 - opening tracks output to : minimal_example_tracks_compact.nc C000 00% step 0000:H0000b00-01 Day +00 00:00 2017-01-01 00:30:00: Rel.: 102: Active:00102 M:00092 S:00000 B:00010 D:000 O:00 N:000 Buffer:0102 0% step time = 4133.1 ms C000 04% step 0030:H0001b01-02 Day +00 01:00 2017-01-01 01:30:00: Rel.: 186: Active:00186 M:00168 S:00002 B:00016 D:000 O:00 N:000 Buffer:0186 0% step time = 2.1 ms C000 09% step 0060:H0002b02-03 Day +00 02:00 2017-01-01 02:30:00: Rel.: 293: Active:00293 M:00269 S:00004 B:00020 D:000 O:00 N:000 Buffer:0293 0% step time = 247.5 ms C000 13% step 0090:H0003b03-04 Day +00 03:00 2017-01-01 03:30:00: Rel.: 422: Active:00422 M:00388 S:00023 B:00011 D:000 O:00 N:000 Buffer:0422 0% step time = 2.2 ms C000 17% step 0120:H0004b04-05 Day +00 04:00 2017-01-01 04:30:00: Rel.: 550: Active:00550 M:00517 S:00023 B:00010 D:000 O:00 N:000 Buffer:0550 0% step time = 2.4 ms C000 22% step 0150:H0005b05-06 Day +00 05:00 2017-01-01 05:30:00: Rel.: 687: Active:00687 M:00656 S:00027 B:00004 D:000 O:00 N:000 Buffer:0687 0% step time = 2.2 ms C000 26% step 0180:H0006b06-07 Day +00 06:00 2017-01-01 06:30:00: Rel.: 812: Active:00812 M:00781 S:00027 B:00004 D:000 O:00 N:000 Buffer:0812 0% step time = 2.2 ms C000 30% step 0210:H0007b07-08 Day +00 07:00 2017-01-01 07:30:00: Rel.: 939: Active:00939 M:00912 S:00023 B:00004 D:000 O:00 N:000 Buffer:0939 0% step time = 3.3 ms C000 35% step 0240:H0008b08-09 Day +00 08:00 2017-01-01 08:30:00: Rel.: 1,076: Active:01076 M:01045 S:00023 B:00008 D:000 O:00 N:000 Buffer:1076 0% step time = 2.6 ms C000 39% step 0270:H0009b09-10 Day +00 09:00 2017-01-01 09:30:00: Rel.: 1,206: Active:01206 M:01183 S:00004 B:00019 D:000 O:00 N:000 Buffer:1206 0% step time = 2.5 ms C000 43% step 0300:H0010b10-11 Day +00 10:00 2017-01-01 10:30:00: Rel.: 1,351: Active:01351 M:01328 S:00002 B:00021 D:000 O:00 N:000 Buffer:1351 0% step time = 2.4 ms C000 48% step 0330:H0011b11-12 Day +00 11:00 2017-01-01 11:30:00: Rel.: 1,490: Active:01490 M:01470 S:00002 B:00018 D:000 O:00 N:000 Buffer:1490 0% step time = 2.2 ms C000 52% step 0360:H0012b12-13 Day +00 12:00 2017-01-01 12:30:00: Rel.: 1,624: Active:01624 M:01597 S:00002 B:00025 D:000 O:00 N:000 Buffer:1624 0% step time = 2.3 ms C000 57% step 0390:H0012b12-13 Day +00 13:00 2017-01-01 13:30:00: Rel.: 1,766: Active:01766 M:01728 S:00014 B:00024 D:000 O:00 N:000 Buffer:1766 0% step time = 2.6 ms C000 61% step 0420:H0014b14-15 Day +00 14:00 2017-01-01 14:30:00: Rel.: 1,907: Active:01907 M:01854 S:00032 B:00021 D:000 O:00 N:000 Buffer:1907 0% step time = 2.3 ms C000 65% step 0450:H0015b15-16 Day +00 15:00 2017-01-01 15:30:00: Rel.: 2,036: Active:02036 M:01942 S:00092 B:00002 D:000 O:00 N:000 Buffer:2036 0% step time = 2.3 ms C000 70% step 0480:H0016b16-17 Day +00 16:00 2017-01-01 16:30:00: Rel.: 2,164: Active:02164 M:02064 S:00100 B:00000 D:000 O:00 N:000 Buffer:2164 0% step time = 2.4 ms C000 74% step 0510:H0017b17-18 Day +00 17:00 2017-01-01 17:30:00: Rel.: 2,295: Active:02295 M:02185 S:00110 B:00000 D:000 O:00 N:000 Buffer:2295 0% step time = 2.5 ms C000 78% step 0540:H0018b18-19 Day +00 18:00 2017-01-01 18:30:00: Rel.: 2,424: Active:02424 M:02313 S:00110 B:00001 D:000 O:00 N:000 Buffer:2424 0% step time = 2.6 ms C000 83% step 0570:H0019b19-20 Day +00 19:00 2017-01-01 19:30:00: Rel.: 2,574: Active:02574 M:02467 S:00107 B:00000 D:000 O:00 N:000 Buffer:2574 1% step time = 2.4 ms C000 87% step 0600:H0020b20-21 Day +00 20:00 2017-01-01 20:30:00: Rel.: 2,717: Active:02717 M:02613 S:00099 B:00005 D:000 O:00 N:000 Buffer:2717 1% step time = 2.6 ms C000 91% step 0630:H0021b21-22 Day +00 21:00 2017-01-01 21:30:00: Rel.: 2,856: Active:02856 M:02810 S:00032 B:00014 D:000 O:00 N:000 Buffer:2856 1% step time = 2.4 ms C000 96% step 0660:H0022b22-23 Day +00 22:00 2017-01-01 22:30:00: Rel.: 2,992: Active:02992 M:02962 S:00014 B:00016 D:000 O:00 N:000 Buffer:2992 1% step time = 2.4 ms C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.0 sec C000 - Reading 1 time steps, for hindcast time steps 23:23, into ring buffer offsets 023:023 C000 - read 1 time steps in 0.1 sec C000 100% step 0690:H0023b23-00 Day +00 23:00 2017-01-01 23:30:00: Rel.: 3,016: Active:03016 M:03000 S:00002 B:00014 D:000 O:00 N:000 Buffer:3016 1% step time = 55.1 ms C000 >>> Note: Hydro-model is "3D" type "SCHISMreaderNCDF" C000 hint: Files found dir and sub-dirs of "../demos/demo_hindcast/schsim3D" C000 >>> Note: Hydro-model grid in metres, all cords should be in meters, e.g. release group locations, gridded_stats grid C000 >>> Note: Hydro-model grid in metres, all cords should be in meters, e.g. release group locations, gridded_stats grid C000 ---------------------------------------------------------------------- C000 - Finished case number 0, minimal_example started: 2024-09-04 08:34:23.872285, ended: 2024-09-04 08:34:37.403585 C000 Computational time =0:00:13.531300 C000 --- End case 0 ------------------------------------------------------- End --- Summary ---------------------------------------------------------- End >>> Note: Run summary with case file names in "*_runInfo.json" End >>> Note: to help with debugging, parameters as given by user are in "user_given_params.json" End >>> Note: No bottom_stress variable in in hydro-files, using near seabed velocity to calculate friction_velocity for resuspension End >>> Note: Run summary with case file names in "*_runInfo.json" End >>> Warning: Oceantracker is not yet compatible with Python 3.11, as not all imported packages have been updated, eg netcdf4 End >>> Warning: Deleted contents of existing output dir End ---------------------------------------------------------------------- End ---------------------------------------------------------------------- End OceanTracker summary: elapsed time =0:00:14.170425 End Cases - 0 errors, 0 warnings, 3 notes, check above End Main - 0 errors, 2 warnings, 3 notes, check above End Output in f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_example End ----------------------------------------------------------------------
plot tracks¶
from read_oceantracker.python import load_output_files
from IPython.display import HTML
from plot_oceantracker.plot_tracks import animate_particles
# read particle track data into a dictionary using case_info_file_name
tracks = load_output_files.load_track_data(case_info_file_name)
print(tracks.keys()) # show what is in tracks dictionary holds
ax= [1591000, 1601500, 5479500, 5491000] # area to plot
anim=animate_particles(tracks, axis_lims=ax, show_grid=True,show_dry_cells=True)
HTML(anim.to_html5_video())# this is slow to build!
dict_keys(['status_unknown', 'status_bad_cord', 'status_cell_search_failed', 'status_notReleased', 'status_dead', 'status_outside_open_boundary', 'status_stationary', 'status_stranded_by_tide', 'status_on_bottom', 'status_moving', 'file_created', 'total_num_particles_released', 'time_steps_written', 'dimensions', 'status', 'dry_cell_index', 'grid_release_row_col', 'ID', 'particles_written_per_time_step', 'x0', 'age', 'water_depth', 'time_released', 'particle_ID', 'A_Z_profile', 'IDpulse', 'num_part_released_so_far', 'IDrelease_group', 'hydro_model_gridID', 'tide', 'time_step_range', 'time', 'x', 'user_release_groupID', 'z', 'grid', 'particle_status_flags', 'particle_release_groups', 'axis_lim'])
