Minimal example¶
[This note-book is in oceantracker/tutorials_how_to/]
Main steps are
build parameters, ie. provide users settings and add “classes” with their specific settings, to the computational pipeline.
run oceantracker with these parameters
plot results
See next notebook for more details on the process.
This example uses helper methods of OceanTracker class to build parameters. The example is part of a a 3D Schisim model, where particles always re-suspend if the land on the bottom. Particles stranded by the falling tide in dry cells are frozen, until the cell becomes wet.
# minimal_example.py using class helper method
#------------------------------------------------
from oceantracker.main import OceanTracker
# make instance of oceantracker to use to set parameters using code, then run
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 release locations from two points,
# (ie locations where particles are released at the same times and locations)
# note : can add multiple release groups
ot.add_class('release_groups',
points= [[1595000, 5482600], #[x,y] pairs of release locations
[1599000, 5486200]], # must be an N by 2 or 3 or list, convertible to a numpy array
release_interval= 3600, # seconds between releasing particles
pulse_size= 10, # number of particles released each release_interval
)
# run oceantracker
case_info_file_name = ot.run()
# output now in folder output/minimal_example
# case_info_file_name the name a json file with useful info for post processing, eg output file names
print(case_info_file_name)
prelim: Starting package set up helper: ---------------------------------------------------------------------- helper: Starting OceanTrackerhelper class, version 0.50.0030-2025-01-28 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, but > 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.0030-2025-01-28 starting setup helper "main.py": 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 "user_given_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, 2.310 sec helper: - Built OceanTracker sort name map, 0.000 sec helper: - Done package set up to setup ClassImporter, 2.310 sec setup: ---------------------------------------------------------------------- setup: OceanTracker version 0.50.0030-2025-01-28 setup: Starting user param. runner: "minimal_example" at 2025-02-20T12:10:17.173416 setup: ---------------------------------------------------------------------- setup: - Start field group manager and readers setup setup: - Found input dir "../demos/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 "../demos/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.434 sec setup: - built triangle adjacency matrix, 0.211 sec setup: - found boundary triangles, 0.000 sec setup: - built domain and island outlines, 1.104 sec setup: - calculated triangle areas, 0.000 sec setup: - Finished grid setup setup: - built barycentric-transform matrix, 0.480 sec setup: - Finished field group manager and readers setup, 4.999 sec setup: - Added release groups and found run start and end times, 0.005 sec setup: - Done initial setup of all classes, 0.017 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.9 sec, from ../demos/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.nc", 0.134 sec S: 0000: 00%:H0000b00-01 Day +00 00:00 2017-01-01 00:30:00: Rel:20 : Active:20 Move:20 Bottom: 0 Strand:0 Dead: 0 Out: 0 Buffer: 4% step time = 13988.8 ms S: 0030: 04%:H0001b01-02 Day +00 01:00 2017-01-01 01:30:00: Rel:40 : Active:40 Move:38 Bottom: 2 Strand:0 Dead: 0 Out: 0 Buffer: 8% step time = 5.9 ms S: 0060: 09%:H0002b02-03 Day +00 02:00 2017-01-01 02:30:00: Rel:60 : Active:60 Move:58 Bottom: 2 Strand:0 Dead: 0 Out: 0 Buffer:12% step time = 5.5 ms S: 0090: 13%:H0003b03-04 Day +00 03:00 2017-01-01 03:30:00: Rel:80 : Active:80 Move:68 Bottom: 2 Strand:10 Dead: 0 Out: 0 Buffer:16% step time = 6.4 ms S: 0120: 17%:H0004b04-05 Day +00 04:00 2017-01-01 04:30:00: Rel:100 : Active:100 Move:85 Bottom: 5 Strand:10 Dead: 0 Out: 0 Buffer:20% step time = 5.9 ms S: 0150: 22%:H0005b05-06 Day +00 05:00 2017-01-01 05:30:00: Rel:120 : Active:120 Move:107 Bottom: 3 Strand:10 Dead: 0 Out: 0 Buffer:25% step time = 5.9 ms S: 0180: 26%:H0006b06-07 Day +00 06:00 2017-01-01 06:30:00: Rel:140 : Active:140 Move:129 Bottom: 1 Strand:10 Dead: 0 Out: 0 Buffer:29% step time = 5.6 ms S: 0210: 30%:H0007b07-08 Day +00 07:00 2017-01-01 07:30:00: Rel:160 : Active:160 Move:147 Bottom: 3 Strand:10 Dead: 0 Out: 0 Buffer:33% step time = 6.7 ms S: 0240: 35%:H0008b08-09 Day +00 08:00 2017-01-01 08:30:00: Rel:180 : Active:180 Move:169 Bottom: 1 Strand:10 Dead: 0 Out: 0 Buffer:37% step time = 5.9 ms S: 0270: 39%:H0009b09-10 Day +00 09:00 2017-01-01 09:30:00: Rel:200 : Active:200 Move:195 Bottom: 5 Strand:0 Dead: 0 Out: 0 Buffer:41% step time = 6.2 ms S: 0300: 43%:H0010b10-11 Day +00 10:00 2017-01-01 10:30:00: Rel:220 : Active:220 Move:219 Bottom: 1 Strand:0 Dead: 0 Out: 0 Buffer:45% step time = 5.5 ms S: 0330: 48%:H0011b11-12 Day +00 11:00 2017-01-01 11:30:00: Rel:240 : Active:240 Move:235 Bottom: 5 Strand:0 Dead: 0 Out: 0 Buffer:50% step time = 7.1 ms S: 0360: 52%:H0012b12-13 Day +00 12:00 2017-01-01 12:30:00: Rel:260 : Active:260 Move:255 Bottom: 5 Strand:0 Dead: 0 Out: 0 Buffer:54% step time = 5.6 ms S: 0390: 57%:H0012b12-13 Day +00 13:00 2017-01-01 13:30:00: Rel:280 : Active:280 Move:263 Bottom: 7 Strand:10 Dead: 0 Out: 0 Buffer:58% step time = 5.8 ms S: 0420: 61%:H0014b14-15 Day +00 14:00 2017-01-01 14:30:00: Rel:300 : Active:300 Move:277 Bottom: 12 Strand:11 Dead: 0 Out: 0 Buffer:62% step time = 5.8 ms S: 0450: 65%:H0015b15-16 Day +00 15:00 2017-01-01 15:30:00: Rel:320 : Active:320 Move:286 Bottom: 1 Strand:33 Dead: 0 Out: 0 Buffer:66% step time = 5.8 ms S: 0480: 70%:H0016b16-17 Day +00 16:00 2017-01-01 16:30:00: Rel:340 : Active:340 Move:302 Bottom: 1 Strand:37 Dead: 0 Out: 0 Buffer:70% step time = 7.6 ms S: 0510: 74%:H0017b17-18 Day +00 17:00 2017-01-01 17:30:00: Rel:360 : Active:360 Move:308 Bottom: 0 Strand:52 Dead: 0 Out: 0 Buffer:75% step time = 6.2 ms S: 0540: 78%:H0018b18-19 Day +00 18:00 2017-01-01 18:30:00: Rel:380 : Active:380 Move:328 Bottom: 0 Strand:52 Dead: 0 Out: 0 Buffer:79% step time = 6.0 ms S: 0570: 83%:H0019b19-20 Day +00 19:00 2017-01-01 19:30:00: Rel:400 : Active:400 Move:352 Bottom: 1 Strand:47 Dead: 0 Out: 0 Buffer:83% step time = 6.1 ms S: 0600: 87%:H0020b20-21 Day +00 20:00 2017-01-01 20:30:00: Rel:420 : Active:420 Move:372 Bottom: 5 Strand:43 Dead: 0 Out: 0 Buffer:87% step time = 6.4 ms S: 0630: 91%:H0021b21-22 Day +00 21:00 2017-01-01 21:30:00: Rel:440 : Active:440 Move:426 Bottom: 3 Strand:11 Dead: 0 Out: 0 Buffer:91% step time = 6.9 ms S: 0660: 96%:H0022b22-23 Day +00 22:00 2017-01-01 22:30:00: Rel:460 : Active:460 Move:449 Bottom: 1 Strand:10 Dead: 0 Out: 0 Buffer:95% step time = 5.8 ms S: 0690: 100%:H0023b23-00 Day +00 23:00 2017-01-01 23:30:00: Rel:460 : Active:460 Move:455 Bottom: 5 Strand:0 Dead: 0 Out: 0 Buffer:95% step time = 7.8 ms end: ---------------------------------------------------------------------- end: >>> Warning: Oceantracker is compatible with Python 3.11, but > 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, 1 warnings, 1 notes, check above end: end: - Finished "minimal_example" started: 19307.5486575, ended: 2025-02-20 12:10:49.547132 end: Computational time =0:00:35.097785 end: Output in f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_example end: end: --- Finished Oceantracker run ---------------------------------------- end: f:H_Local_driveParticleTrackingoceantrackertutorials_how_tooutputminimal_exampleminimal_example_caseInfo.json
Read and plot output¶
A first basic plot of particle tracks
from read_oceantracker.python import load_output_files
# 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
from plot_oceantracker.plot_tracks import plot_tracks
ax= [1591000, 1601500, 5479500, 5491000] # area to plot
plot_tracks(tracks, axis_lims=ax, show_grid=True)
dict_keys(['status_unknown', 'status_bad_coord', 'status_cell_search_failed', 'status_notReleased', 'status_dead', 'status_hit_dry_cell', 'status_outside_domain', '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', 'user_release_groupID', 'x', 'hydro_model_gridID', 'ID', 'tide', 'particles_written_per_time_step', 'IDrelease_group', 'particle_ID', 'water_depth', 'dry_cell_index', 'IDpulse', 'age', 'time_released', 'time_step_range', 'num_part_released_so_far', 'x0', 'time', 'z', 'grid', 'particle_status_flags', 'particle_release_groups', 'axis_lim'])
Add aminations¶
play movie when done
animations require additional install of ffpeg, after activating oceantracker conda environment run
conda install -c conda-forge ffmpeg
In animation, sand colored area shows dry cells, blue particles are moving, green are stranded by the tide in dry cells, gray are on the sea bed, from which they resupend in this example.
By default particles are blocked from moving from a wet cell to a dry cell and will not be released if the release location lies within a dry cell.
from matplotlib import pyplot as plt
from plot_oceantracker.plot_tracks import animate_particles
from IPython.display import HTML
# animate particles
anim = animate_particles(tracks, axis_lims=ax,title='Minimal OceanTracker example',
show_dry_cells=True, show_grid=True, show=False) # use ipython to show video, rather than matplotlib plt.show()
# this line only used in note books, in python scripts use show = True above
# this is slow to build!
HTML(anim.to_html5_video())
