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)
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.609 sec Main - Built OceanTracker sort name map, 0.000 sec Main - Done package set up to setup ClassImporter, 0.609 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.009 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.032 sec prelim: Starting package set up prelim: - Built OceanTracker package tree, 0.009 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:38:54.763200 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.924 sec C000 - built triangle adjacency matrix, 0.167 sec C000 - found boundary triangles, 0.000 sec C000 - built domain and island outlines, 1.012 sec C000 - calculated triangle areas, 0.000 sec C000 - Finished grid setup C000 - built barycentric-transform matrix, 0.226 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.228 sec C000 - Added release groups and found run start and end times, 0.003 sec C000 - Done initial setup of all classes, 0.015 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.: 20: Active:00020 M:00020 S:00000 B:00000 D:000 O:00 N:000 Buffer:0020 0% step time = 3702.0 ms C000 04% step 0030:H0001b01-02 Day +00 01:00 2017-01-01 01:30:00: Rel.: 40: Active:00040 M:00038 S:00000 B:00002 D:000 O:00 N:000 Buffer:0040 0% step time = 1.8 ms C000 09% step 0060:H0002b02-03 Day +00 02:00 2017-01-01 02:30:00: Rel.: 60: Active:00060 M:00053 S:00000 B:00007 D:000 O:00 N:000 Buffer:0060 0% step time = 1.7 ms C000 13% step 0090:H0003b03-04 Day +00 03:00 2017-01-01 03:30:00: Rel.: 80: Active:00080 M:00063 S:00010 B:00007 D:000 O:00 N:000 Buffer:0080 0% step time = 1.7 ms C000 17% step 0120:H0004b04-05 Day +00 04:00 2017-01-01 04:30:00: Rel.: 100: Active:00100 M:00084 S:00010 B:00006 D:000 O:00 N:000 Buffer:0100 0% step time = 1.9 ms C000 22% step 0150:H0005b05-06 Day +00 05:00 2017-01-01 05:30:00: Rel.: 120: Active:00120 M:00106 S:00010 B:00004 D:000 O:00 N:000 Buffer:0120 0% step time = 1.8 ms C000 26% step 0180:H0006b06-07 Day +00 06:00 2017-01-01 06:30:00: Rel.: 140: Active:00140 M:00127 S:00010 B:00003 D:000 O:00 N:000 Buffer:0140 0% step time = 1.9 ms C000 30% step 0210:H0007b07-08 Day +00 07:00 2017-01-01 07:30:00: Rel.: 160: Active:00160 M:00147 S:00010 B:00003 D:000 O:00 N:000 Buffer:0160 0% step time = 1.7 ms C000 35% step 0240:H0008b08-09 Day +00 08:00 2017-01-01 08:30:00: Rel.: 180: Active:00180 M:00166 S:00010 B:00004 D:000 O:00 N:000 Buffer:0180 0% step time = 1.7 ms C000 39% step 0270:H0009b09-10 Day +00 09:00 2017-01-01 09:30:00: Rel.: 200: Active:00200 M:00195 S:00000 B:00005 D:000 O:00 N:000 Buffer:0200 0% step time = 1.8 ms C000 43% step 0300:H0010b10-11 Day +00 10:00 2017-01-01 10:30:00: Rel.: 220: Active:00220 M:00214 S:00000 B:00006 D:000 O:00 N:000 Buffer:0220 0% step time = 1.6 ms C000 48% step 0330:H0011b11-12 Day +00 11:00 2017-01-01 11:30:00: Rel.: 240: Active:00240 M:00236 S:00000 B:00004 D:000 O:00 N:000 Buffer:0240 0% step time = 1.7 ms C000 52% step 0360:H0012b12-13 Day +00 12:00 2017-01-01 12:30:00: Rel.: 260: Active:00260 M:00248 S:00000 B:00012 D:000 O:00 N:000 Buffer:0260 0% step time = 1.6 ms C000 57% step 0390:H0012b12-13 Day +00 13:00 2017-01-01 13:30:00: Rel.: 280: Active:00280 M:00263 S:00011 B:00006 D:000 O:00 N:000 Buffer:0280 0% step time = 1.6 ms C000 61% step 0420:H0014b14-15 Day +00 14:00 2017-01-01 14:30:00: Rel.: 300: Active:00300 M:00273 S:00020 B:00007 D:000 O:00 N:000 Buffer:0300 0% step time = 1.6 ms C000 65% step 0450:H0015b15-16 Day +00 15:00 2017-01-01 15:30:00: Rel.: 320: Active:00320 M:00255 S:00063 B:00002 D:000 O:00 N:000 Buffer:0320 0% step time = 1.7 ms C000 70% step 0480:H0016b16-17 Day +00 16:00 2017-01-01 16:30:00: Rel.: 340: Active:00340 M:00271 S:00069 B:00000 D:000 O:00 N:000 Buffer:0340 0% step time = 1.7 ms C000 74% step 0510:H0017b17-18 Day +00 17:00 2017-01-01 17:30:00: Rel.: 360: Active:00360 M:00284 S:00076 B:00000 D:000 O:00 N:000 Buffer:0360 0% step time = 1.7 ms C000 78% step 0540:H0018b18-19 Day +00 18:00 2017-01-01 18:30:00: Rel.: 380: Active:00380 M:00304 S:00076 B:00000 D:000 O:00 N:000 Buffer:0380 0% step time = 1.9 ms C000 83% step 0570:H0019b19-20 Day +00 19:00 2017-01-01 19:30:00: Rel.: 400: Active:00400 M:00324 S:00076 B:00000 D:000 O:00 N:000 Buffer:0400 0% step time = 1.8 ms C000 87% step 0600:H0020b20-21 Day +00 20:00 2017-01-01 20:30:00: Rel.: 420: Active:00420 M:00350 S:00070 B:00000 D:000 O:00 N:000 Buffer:0420 0% step time = 1.8 ms C000 91% step 0630:H0021b21-22 Day +00 21:00 2017-01-01 21:30:00: Rel.: 440: Active:00440 M:00412 S:00020 B:00008 D:000 O:00 N:000 Buffer:0440 0% step time = 1.7 ms C000 96% step 0660:H0022b22-23 Day +00 22:00 2017-01-01 22:30:00: Rel.: 460: Active:00460 M:00438 S:00011 B:00011 D:000 O:00 N:000 Buffer:0460 0% step time = 1.7 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.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.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.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.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.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.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.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.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.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 100% step 0690:H0023b23-00 Day +00 23:00 2017-01-01 23:30:00: Rel.: 460: Active:00460 M:00442 S:00000 B:00018 D:000 O:00 N:000 Buffer:0460 0% step time = 53.9 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:38:54.748684, ended: 2024-09-04 08:39:06.763004 C000 Computational time =0:00:12.014320 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:12.700537 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 ---------------------------------------------------------------------- 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_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', 'A_Z_profile', 'water_depth', 'time_step_range', 'IDrelease_group', 'ID', 'user_release_groupID', 'hydro_model_gridID', 'time', 'x0', 'particle_ID', 'x', 'dry_cell_index', 'tide', 'IDpulse', 'age', 'time_released', 'particles_written_per_time_step', 'num_part_released_so_far', '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 is slow to build!
HTML(anim.to_html5_video())
