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… .. code:: ipython3 # Notes for debugging if the scripts below fail: # * These scripts assume that you already installed oceantracker. If you didn't take a look at https://oceantracker.github.io/oceantracker/_build/html/info/installing.html # * Paths in this directory are relative to the location of the ipython notebook. # I.e. On Linux or Mac, running a cell with "!ls" should return a list containing the notebook you are running. # Checks if the hindcast data is available and downloads them if not from oceantracker.util.download_data import download_hindcast_data_for_tutorials download_hindcast_data_for_tutorials() .. parsed-literal:: Hindcast data found locally at ./demo_hindcast .. code:: ipython3 # 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='release_groups', # 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() .. parsed-literal:: helper: ---------------------------------------------------------------------- helper: Starting OceanTracker helper class, version 0.50.03.0100-2025-08-13 helper: Python version: 3.10.18 | packaged by conda-forge | (main, Jun 4 2025, 14:45:41) [GCC 13.3.0] helper: ---------------------------------------------------------------------- helper: OceanTracker version 0.50.03.0100-2025-08-13 starting setup helper "main.py": helper: Output is in dir "/mnt/c/Users/Laurin.Steidle/OneDrive - Cawthron/Documents/projects/oceantracker_dev/oceantracker/tutorials_how_to/output/release_groups" 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 "release_groups_raw_user_params.json" helper: >>> Warning: Numba has already been imported, some numba options may not be used (ignore SVML warning) helper: hint: Ensure any code using Numba is imported after Oceantracker is run, eg Oceantrackers "load_output_files.py" and "read_ncdf_output_files.py" helper: ---------------------------------------------------------------------- helper: Numba setup: applied settings, max threads = 8, physical cores = 8 helper: hint: cache code = False, fastmath= False helper: ---------------------------------------------------------------------- helper: - Built OceanTracker package tree, 0.332 sec helper: - Built OceanTracker sort name map, 0.000 sec helper: - Done package set up to setup ClassImporter, 0.333 sec setup: ---------------------------------------------------------------------- setup: OceanTracker version 0.50.03.0100-2025-08-13 setup: Starting user param. runner: "release_groups" at 2025-08-27T10:05:42.682727 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: has: A_Z profile=True bottom stress=False setup: ---------------------------------------------------------------------- setup: - Starting grid setup setup: - built node to triangles map, 0.000 sec setup: - built triangle adjacency matrix, 0.000 sec setup: - found boundary triangles, 0.000 sec setup: - built domain and island outlines, 0.464 sec setup: - calculated triangle areas, 0.000 sec setup: - Finished grid setup setup: - built barycentric-transform matrix, 0.000 sec setup: - Loading reader fields ['water_depth', 'water_velocity', 'tide'] setup: - Finished field group manager and readers setup, 1.694 sec setup: ---------------------------------------------------------------------- setup: - Added 3 release group(s) and found run start and end times, 0.683 sec setup: - Done initial setup of all classes, 0.482 sec setup: ---------------------------------------------------------------------- setup: - Starting "release_groups", duration: 0 days 23 hrs 0 min 0 sec setup: From 2017-01-01T00:30:00 to 2017-01-01T23:30:00 setup: Time step 120.0 sec setup: using: A_Z_profile = False bottom_stress = False setup: ---------------------------------------------------------------------- setup: - Reading 24 time steps, for hindcast time steps 00:23 into ring buffer offsets 000:023 , for run "release_groups" setup: - read 24 time steps in 0.2 sec, from ./demo_hindcast/schsim3D setup: - Starting time stepping: 2017-01-01T00:30:00 to 2017-01-01T23:30:00 setup: duration 0 days 23 hrs 0 min 0 sec, time step= 0 days 0 hrs 2 min 0 sec S: - Opened tracks output and done written first time step in: "release_groups_tracks_compact_000.nc", 0.015 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 = 258.1 ms S: 0001: 00%:H0000b00-01 Day +00 00:02 2017-01-01 00:32:00: Rel:30 : Active:30 Move:30 Bottom:0 Strand:0 Dead:0 Out: 0 Buffer: 1% step time = 1.3 ms S: 0031: 04%:H0001b01-02 Day +00 01:02 2017-01-01 01:32:00: Rel:80 : Active:80 Move:80 Bottom:0 Strand:0 Dead:0 Out: 0 Buffer: 3% step time = 1.6 ms S: 0061: 09%:H0002b02-03 Day +00 02:02 2017-01-01 02:32:00: Rel:153 : Active:153 Move:152 Bottom:0 Strand:1 Dead:0 Out: 0 Buffer: 6% step time = 3.8 ms S: 0091: 13%:H0003b03-04 Day +00 03:02 2017-01-01 03:32:00: Rel:240 : Active:240 Move:218 Bottom:0 Strand:22 Dead:0 Out: 0 Buffer:10% step time = 3.5 ms S: 0121: 18%:H0004b04-05 Day +00 04:02 2017-01-01 04:32:00: Rel:318 : Active:318 Move:295 Bottom:0 Strand:23 Dead:0 Out: 0 Buffer:14% step time = 1.8 ms S: 0151: 22%:H0005b05-06 Day +00 05:02 2017-01-01 05:32:00: Rel:393 : Active:393 Move:367 Bottom:0 Strand:26 Dead:0 Out: 0 Buffer:17% step time = 2.5 ms S: 0181: 26%:H0006b06-07 Day +00 06:02 2017-01-01 06:32:00: Rel:470 : Active:470 Move:444 Bottom:0 Strand:26 Dead:0 Out: 0 Buffer:21% step time = 1.9 ms S: 0211: 31%:H0007b07-08 Day +00 07:02 2017-01-01 07:32:00: Rel:546 : Active:546 Move:523 Bottom:0 Strand:23 Dead:0 Out: 0 Buffer:24% step time = 4.4 ms S: 0241: 35%:H0008b08-09 Day +00 08:02 2017-01-01 08:32:00: Rel:623 : Active:623 Move:601 Bottom:0 Strand:22 Dead:0 Out: 0 Buffer:28% step time = 3.4 ms S: 0271: 39%:H0009b09-10 Day +00 09:02 2017-01-01 09:32:00: Rel:710 : Active:710 Move:709 Bottom:0 Strand:1 Dead:0 Out: 0 Buffer:32% step time = 9.2 ms S: 0301: 44%:H0010b10-11 Day +00 10:02 2017-01-01 10:32:00: Rel:807 : Active:807 Move:807 Bottom:0 Strand:0 Dead:0 Out: 0 Buffer:36% step time = 7.1 ms S: 0331: 48%:H0011b11-12 Day +00 11:02 2017-01-01 11:32:00: Rel:903 : Active:903 Move:903 Bottom:0 Strand:0 Dead:0 Out: 0 Buffer:40% step time = 3.4 ms S: 0361: 52%:H0012b12-13 Day +00 12:02 2017-01-01 12:32:00: Rel:1,001: Active:1,001 Move:1,001 Bottom:0 Strand:0 Dead:0 Out: 0 Buffer:45% step time = 7.1 ms S: 0391: 57%:H0013b13-14 Day +00 13:02 2017-01-01 13:32:00: Rel:1,098: Active:1,098 Move:1,068 Bottom:0 Strand:30 Dead:0 Out: 0 Buffer:49% step time = 3.1 ms S: 0421: 61%:H0014b14-15 Day +00 14:02 2017-01-01 14:32:00: Rel:1,194: Active:1,194 Move:1,154 Bottom:0 Strand:40 Dead:0 Out: 0 Buffer:53% step time = 5.7 ms S: 0451: 65%:H0015b15-16 Day +00 15:02 2017-01-01 15:32:00: Rel:1,282: Active:1,282 Move:1,155 Bottom:0 Strand:127 Dead:0 Out: 0 Buffer:57% step time = 2.9 ms S: 0481: 70%:H0016b16-17 Day +00 16:02 2017-01-01 16:32:00: Rel:1,360: Active:1,360 Move:1,211 Bottom:0 Strand:149 Dead:0 Out: 0 Buffer:61% step time = 1.9 ms S: 0511: 74%:H0017b17-18 Day +00 17:02 2017-01-01 17:32:00: Rel:1,437: Active:1,437 Move:1,280 Bottom:0 Strand:157 Dead:0 Out: 0 Buffer:64% step time = 2.1 ms S: 0541: 78%:H0018b18-19 Day +00 18:02 2017-01-01 18:32:00: Rel:1,515: Active:1,515 Move:1,358 Bottom:0 Strand:157 Dead:0 Out: 0 Buffer:68% step time = 1.8 ms S: 0571: 83%:H0019b19-20 Day +00 19:02 2017-01-01 19:32:00: Rel:1,593: Active:1,593 Move:1,438 Bottom:0 Strand:155 Dead:0 Out: 0 Buffer:72% step time = 2.0 ms S: 0601: 87%:H0020b20-21 Day +00 20:02 2017-01-01 20:32:00: Rel:1,671: Active:1,671 Move:1,538 Bottom:0 Strand:133 Dead:0 Out: 0 Buffer:75% step time = 2.0 ms S: 0631: 91%:H0021b21-22 Day +00 21:02 2017-01-01 21:32:00: Rel:1,755: Active:1,755 Move:1,715 Bottom:0 Strand:40 Dead:0 Out: 0 Buffer:79% step time = 3.8 ms S: 0661: 96%:H0022b22-23 Day +00 22:02 2017-01-01 22:32:00: Rel:1,853: Active:1,853 Move:1,823 Bottom:0 Strand:30 Dead:0 Out: 0 Buffer:83% step time = 2.8 ms S: --- Closing all classes ---------------------------------------------- S: Converting compact track files to rectangular format (to disable set reader param convert=False) S: - Finished "release_groups_tracks_rectangular_000.nc", 0.753 sec S: - Conversion complete, 0.753 sec end: ---------------------------------------------------------------------- end: Finished "release_groups", started: 2025-08-27 10:05:42.299862, ended: 2025-08-27 10:05:53.097317 end: Computational time =0:00:10.797479 end: Timings: total = 10.8 sec end: Setup 2.77 s 25.7% end: Reading hindcast 1.29 s 11.9% end: Initial cell guess 1.63 s 15.1% end: RK integration 3.81 s 35.3% end: Find horizontal cell 1.95 s 18.1% end: Find vertical cell 1.19 s 11.0% end: Interpolate fields 1.31 s 12.1% end: Update statistics 0.00 s 0.0% end: Update custom particle prop. 0.01 s 0.1% end: resuspension 0.02 s 0.1% end: dispersion 0.05 s 0.4% end: tracks_writer 0.22 s 2.0% end: 0 errors, 1 warnings, 1 notes end: --- Finished: output in "/mnt/c/Users/Laurin.Steidle/OneDrive - Cawthron/Documents/projects/oceantracker_dev/oceantracker/tutorials_how_to/output/release_groups" plot tracks =========== .. code:: ipython3 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, colour_using_data= tracks['IDrelease_group']) # 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! .. parsed-literal:: Merging rectangular track files Reading rectangular track file "release_groups_tracks_rectangular_000.nc" dict_keys(['particles_written_per_time_step', 'time_step_range', 'time', 'num_part_released_so_far', 'x', 'x0', 'status', 'status_last_good', 'age', 'ID', 'IDrelease_group', 'user_release_groupID', 'IDpulse', 'hydro_model_gridID', 'time_released', 'grid_release_row_col', 'water_depth', 'tide', 'dry_cell_index', 'grid', 'particle_status_flags', 'particle_release_groups', 'axis_lim']) animate_particles: color map limits None None .. image:: C_release_groups_files/C_release_groups_4_1.png .. raw:: html