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= './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()
prelim: Starting package set up helper: ---------------------------------------------------------------------- helper: Starting OceanTrackerhelper class, version 0.50.0041-2025-03-10 helper: Python version: 3.11.9 | packaged by conda-forge | (main, Apr 19 2024, 18:27:10) [MSC v.1938 64 bit (AMD64)] helper: >>> Warning: Oceantracker is compatible with Python 3.11, however not all external imported packages have been updated to be compatible with 3.11 helper: hint: Down grade to python 3.10 if unexplained issues in external packages helper: ---------------------------------------------------------------------- helper: OceanTracker version 0.50.0041-2025-03-10 starting setup helper "main.py": helper: >>> Warning: Deleted contents of existing output dir helper: Output is in dir "f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_example" helper: hint: see for copies of screen output and user supplied parameters, plus all other output helper: >>> Note: to help with debugging, parameters as given by user are in "minimal_example_raw_user_params.json" helper: ---------------------------------------------------------------------- helper: Numba setup: applied settings, max threads = 32, physical cores = 32 helper: hint: cache code = False, fastmath= False helper: ---------------------------------------------------------------------- helper: - Built OceanTracker package tree, 0.831 sec helper: - Built OceanTracker sort name map, 0.000 sec helper: - Done package set up to setup ClassImporter, 0.831 sec setup: ---------------------------------------------------------------------- setup: OceanTracker version 0.50.0041-2025-03-10 setup: Starting user param. runner: "minimal_example" at 2025-03-10T13:10:54.865468 setup: ---------------------------------------------------------------------- setup: - Start field group manager and readers setup setup: - Found input dir "./demo_hindcast/schsim3D" setup: - Detected reader class_name = "oceantracker.reader.SCHISM_reader.SCHISMreader" setup: Hydro-model is "3D", type "SCHISMreader" setup: hint: Files found in dir and sub-dirs of "./demo_hindcast/schsim3D" setup: Geographic coords = "False" setup: Hindcast start: 2017-01-01T00:30:00 end: 2017-01-01T23:30:00 setup: time step = 0 days 1 hrs 0 min 0 sec, number of time steps= 24 setup: grid bounding box = [1589789.000 5479437.000] to [1603398.000 5501640.000] setup: - Starting grid setup setup: - built node to triangles map, 1.020 sec setup: - built triangle adjacency matrix, 0.164 sec setup: - found boundary triangles, 0.000 sec setup: - built domain and island outlines, 0.986 sec setup: - calculated triangle areas, 0.000 sec setup: - Finished grid setup setup: - built barycentric-transform matrix, 0.324 sec setup: - Finished field group manager and readers setup, 3.694 sec setup: - Added release groups and found run start and end times, 0.446 sec setup: - Done initial setup of all classes, 1.023 sec setup: ---------------------------------------------------------------------- setup: - Starting" minimal_example, duration: 0 days 23 hrs 0 min 0 sec setup: From 2017-01-01T00:30:00 to 2017-01-01T23:30:00 setup: - Reading 24 time steps, for hindcast time steps 00:23 into ring buffer offsets 000:023 setup: - read 24 time steps in 1.6 sec, from ./demo_hindcast/schsim3D setup: ---------------------------------------------------------------------- setup: - Starting time stepping: 2017-01-01T00:30:00 to 2017-01-01T23:30:00 , duration 0 days 23 hrs 0 min 0 sec S: - Opened tracks output and done written first time step in: "minimal_example_tracks_compact_000.nc", 0.017 sec S: 0000: 00%:H0000b00-01 Day +00 00:00 2017-01-01 00:30:00: Rel:30 : Active:30 Move:30 Bottom: 0 Strand:0 Dead: 0 Out: 0 Buffer: 1% step time = 13550.8 ms S: 0030: 04%:H0001b01-02 Day +00 01:00 2017-01-01 01:30:00: Rel:80 : Active:80 Move:72 Bottom: 8 Strand:0 Dead: 0 Out: 0 Buffer: 3% step time = 8.3 ms S: 0060: 09%:H0002b02-03 Day +00 02:00 2017-01-01 02:30:00: Rel:154 : Active:154 Move:137 Bottom: 14 Strand:3 Dead: 0 Out: 0 Buffer: 6% step time = 964.2 ms S: 0090: 13%:H0003b03-04 Day +00 03:00 2017-01-01 03:30:00: Rel:252 : Active:252 Move:227 Bottom: 2 Strand:23 Dead: 0 Out: 0 Buffer:11% step time = 10.8 ms S: 0120: 17%:H0004b04-05 Day +00 04:00 2017-01-01 04:30:00: Rel:350 : Active:350 Move:320 Bottom: 7 Strand:23 Dead: 0 Out: 0 Buffer:15% step time = 11.3 ms S: 0150: 22%:H0005b05-06 Day +00 05:00 2017-01-01 05:30:00: Rel:448 : Active:448 Move:420 Bottom: 5 Strand:23 Dead: 0 Out: 0 Buffer:20% step time = 9.3 ms S: 0180: 26%:H0006b06-07 Day +00 06:00 2017-01-01 06:30:00: Rel:546 : Active:546 Move:520 Bottom: 3 Strand:23 Dead: 0 Out: 0 Buffer:24% step time = 11.2 ms S: 0210: 30%:H0007b07-08 Day +00 07:00 2017-01-01 07:30:00: Rel:644 : Active:644 Move:620 Bottom: 1 Strand:23 Dead: 0 Out: 0 Buffer:29% step time = 13.8 ms S: 0240: 35%:H0008b08-09 Day +00 08:00 2017-01-01 08:30:00: Rel:742 : Active:742 Move:714 Bottom: 5 Strand:23 Dead: 0 Out: 0 Buffer:33% step time = 13.7 ms S: 0270: 39%:H0009b09-10 Day +00 09:00 2017-01-01 09:30:00: Rel:840 : Active:840 Move:831 Bottom: 6 Strand:3 Dead: 0 Out: 0 Buffer:37% step time = 11.3 ms S: 0300: 43%:H0010b10-11 Day +00 10:00 2017-01-01 10:30:00: Rel:938 : Active:938 Move:929 Bottom: 9 Strand:0 Dead: 0 Out: 0 Buffer:42% step time = 12.1 ms S: 0330: 48%:H0011b11-12 Day +00 11:00 2017-01-01 11:30:00: Rel:1,036: Active:1,036 Move:1,014 Bottom: 22 Strand:0 Dead: 0 Out: 0 Buffer:46% step time = 10.7 ms S: 0360: 52%:H0012b12-13 Day +00 12:00 2017-01-01 12:30:00: Rel:1,134: Active:1,134 Move:1,111 Bottom: 23 Strand:0 Dead: 0 Out: 0 Buffer:51% step time = 11.3 ms S: 0390: 57%:H0012b12-13 Day +00 13:00 2017-01-01 13:30:00: Rel:1,232: Active:1,232 Move:1,191 Bottom: 15 Strand:26 Dead: 0 Out: 0 Buffer:55% step time = 12.1 ms S: 0420: 61%:H0014b14-15 Day +00 14:00 2017-01-01 14:30:00: Rel:1,330: Active:1,330 Move:1,274 Bottom: 24 Strand:32 Dead: 0 Out: 0 Buffer:60% step time = 12.3 ms S: 0450: 65%:H0015b15-16 Day +00 15:00 2017-01-01 15:30:00: Rel:1,428: Active:1,428 Move:1,332 Bottom: 3 Strand:93 Dead: 0 Out: 0 Buffer:64% step time = 12.1 ms S: 0480: 70%:H0016b16-17 Day +00 16:00 2017-01-01 16:30:00: Rel:1,526: Active:1,526 Move:1,423 Bottom: 0 Strand:103 Dead: 0 Out: 0 Buffer:68% step time = 13.2 ms S: 0510: 74%:H0017b17-18 Day +00 17:00 2017-01-01 17:30:00: Rel:1,624: Active:1,624 Move:1,506 Bottom: 0 Strand:118 Dead: 0 Out: 0 Buffer:73% step time = 9.9 ms S: 0540: 78%:H0018b18-19 Day +00 18:00 2017-01-01 18:30:00: Rel:1,722: Active:1,722 Move:1,604 Bottom: 0 Strand:118 Dead: 0 Out: 0 Buffer:77% step time = 11.0 ms S: 0570: 83%:H0019b19-20 Day +00 19:00 2017-01-01 19:30:00: Rel:1,820: Active:1,820 Move:1,705 Bottom: 2 Strand:113 Dead: 0 Out: 0 Buffer:82% step time = 10.8 ms S: 0600: 87%:H0020b20-21 Day +00 20:00 2017-01-01 20:30:00: Rel:1,918: Active:1,918 Move:1,810 Bottom: 5 Strand:103 Dead: 0 Out: 0 Buffer:86% step time = 10.5 ms S: 0630: 91%:H0021b21-22 Day +00 21:00 2017-01-01 21:30:00: Rel:2,016: Active:2,016 Move:1,978 Bottom: 6 Strand:32 Dead: 0 Out: 0 Buffer:91% step time = 10.5 ms S: 0660: 96%:H0022b22-23 Day +00 22:00 2017-01-01 22:30:00: Rel:2,114: Active:2,114 Move:2,081 Bottom: 7 Strand:26 Dead: 0 Out: 0 Buffer:95% step time = 10.3 ms S: 0690: 100%:H0023b23-00 Day +00 23:00 2017-01-01 23:30:00: Rel:2,158: Active:2,158 Move:2,144 Bottom: 14 Strand:0 Dead: 0 Out: 0 Buffer:97% step time = 11.2 ms end: ---------------------------------------------------------------------- end: >>> Warning: Deleted contents of existing output dir end: end: >>> Warning: Oceantracker is compatible with Python 3.11, however not all external imported packages have been updated to be compatible with 3.11 end: hint: Down grade to python 3.10 if unexplained issues in external packages end: end: ---------------------------------------------------------------------- end: Error counts - 0 errors, 2 warnings, 1 notes, check above end: end: - Finished "minimal_example" started: 21784.9167612, ended: 2025-03-10 13:11:29.662167 end: Computational time =0:00:35.819533 end: Output in f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_example end: end: --- Finished Oceantracker run ---------------------------------------- end:
plot tracks¶
from oceantracker.read_output.python import load_output_files
from IPython.display import HTML
from oceantracker.plot_output import plot_tracks
# 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= plot_tracks.animate_particles(tracks, axis_lims=ax, show_grid=True,show_dry_cells=True)
# this line only used in note books, in python scripts use show = True above
# this is slow to build!
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'])
