diff --git a/docs/src/model_setup/lagrangian_particles.md b/docs/src/model_setup/lagrangian_particles.md index f7deb6b515..5c0db8a0e4 100644 --- a/docs/src/model_setup/lagrangian_particles.md +++ b/docs/src/model_setup/lagrangian_particles.md @@ -108,43 +108,17 @@ Particle properties can be written to disk using JLD2 or NetCDF. When writing to JLD2 you can pass `model.particles` as part of the named tuple of outputs. -```@meta -DocTestFilters = r"└── file size: [0-9]*.[0-9]* KiB" -``` - -```jldoctest particles +```@example particles JLD2OutputWriter(model, (particles=model.particles,), filename="particles", schedule=TimeInterval(15)) - -# output -JLD2OutputWriter scheduled on TimeInterval(15 seconds): -├── filepath: ./particles.jld2 -├── 1 outputs: particles -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 17.6 KiB ``` When writing to NetCDF you should write particles to a separate file as the NetCDF dimensions differ for particle trajectories. You can just pass `model.particles` straight to `NetCDFOutputWriter`: -```jldoctest particles +```@example particles NetCDFOutputWriter(model, model.particles, filename="particles.nc", schedule=TimeInterval(15)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(15 seconds): -├── filepath: ./particles.nc -├── dimensions: particle_id(10), time(0) -├── 1 outputs: particles -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 9.9 KiB ``` !!! warn "Outputting custom particle properties to NetCDF" NetCDF does not support arbitrary data types. If you need to write custom particle properties to disk that are not supported by NetCDF then you should use JLD2 (which should support almost any Julia data type). - -```@meta -DocTestFilters = nothing -``` diff --git a/docs/src/model_setup/output_writers.md b/docs/src/model_setup/output_writers.md index fd9428128d..2d7698c5a7 100644 --- a/docs/src/model_setup/output_writers.md +++ b/docs/src/model_setup/output_writers.md @@ -50,7 +50,7 @@ passing it a dictionary of (label, field) pairs and any indices for slicing if y Saving the u velocity field and temperature fields as full 3D fields, surface 2D slices, and 1D columns to separate NetCDF files: -```jldoctest netcdf1 +```@example netcdf1 using Oceananigans grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1)) @@ -63,53 +63,26 @@ fields = Dict("u" => model.velocities.u, "c" => model.tracers.c) simulation.output_writers[:field_writer] = NetCDFOutputWriter(model, fields, filename="more_fields.nc", schedule=TimeInterval(60)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./more_fields.nc -├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0) -├── 2 outputs: (c, u) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.9 KiB ``` -```jldoctest netcdf1 +```@example netcdf1 simulation.output_writers[:surface_slice_writer] = NetCDFOutputWriter(model, fields, filename="another_surface_xy_slice.nc", schedule=TimeInterval(60), indices=(:, :, grid.Nz)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./another_surface_xy_slice.nc -├── dimensions: zC(1), zF(1), xC(16), yF(16), xF(16), yC(16), time(0) -├── 2 outputs: (c, u) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.9 KiB ``` -```jldoctest netcdf1 +```@example netcdf1 simulation.output_writers[:averaged_profile_writer] = NetCDFOutputWriter(model, fields, filename = "another_averaged_z_profile.nc", schedule = AveragedTimeInterval(60, window=20), indices = (1, 1, :)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./another_averaged_z_profile.nc -├── dimensions: zC(16), zF(17), xC(1), yF(1), xF(1), yC(1), time(0) -├── 2 outputs: (c, u) averaged on AveragedTimeInterval(window=20 seconds, stride=1, interval=1 minute) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 17.6 KiB ``` `NetCDFOutputWriter` also accepts output functions that write scalars and arrays to disk, provided that their `dimensions` are provided: -```jldoctest +```@example using Oceananigans Nx, Ny, Nz = 16, 16, 16 @@ -147,22 +120,13 @@ simulation.output_writers[:things] = NetCDFOutputWriter(model, outputs, schedule=IterationInterval(1), filename="things.nc", dimensions=dims, verbose=true, global_attributes=global_attributes, output_attributes=output_attributes) - -# output -NetCDFOutputWriter scheduled on IterationInterval(1): -├── filepath: ./things.nc -├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0) -├── 3 outputs: (profile, slice, scalar) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 17.8 KiB ``` `NetCDFOutputWriter` can also be configured for `outputs` that are interpolated or regridded to a different grid than `model.grid`. To use this functionality, include the keyword argument `grid = output_grid`. -```jldoctest +```@example using Oceananigans using Oceananigans.Fields: interpolate! @@ -179,15 +143,6 @@ output_writer = NetCDFOutputWriter(model, outputs; grid = coarse_grid, filename = "coarse_u.nc", schedule = IterationInterval(1)) - -# output -NetCDFOutputWriter scheduled on IterationInterval(1): -├── filepath: ./coarse_u.nc -├── dimensions: zC(4), zF(5), xC(1), yF(1), xF(1), yC(1), time(0) -├── 1 outputs: u -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.6 KiB ``` See [`NetCDFOutputWriter`](@ref) for more information. @@ -208,7 +163,7 @@ of the function will be saved to the JLD2 file. Write out 3D fields for u, v, w, and a tracer c, along with a horizontal average: -```jldoctest jld2_output_writer +```@example jld2_output_writer using Oceananigans using Oceananigans.Utils: hour, minute @@ -229,36 +184,17 @@ simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocitie filename = "some_more_data.jld2", schedule = TimeInterval(20minute), init = init_save_some_metadata!) - -# output -JLD2OutputWriter scheduled on TimeInterval(20 minutes): -├── filepath: ./some_more_data.jld2 -├── 3 outputs: (u, v, w) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 29.1 KiB ``` and a time- and horizontal-average of tracer `c` every 20 minutes of simulation time to a file called `some_more_averaged_data.jld2` -```jldoctest jld2_output_writer +```@example jld2_output_writer simulation.output_writers[:avg_c] = JLD2OutputWriter(model, (; c=c_avg), filename = "some_more_averaged_data.jld2", schedule = AveragedTimeInterval(20minute, window=5minute)) - -# output -JLD2OutputWriter scheduled on TimeInterval(20 minutes): -├── filepath: ./some_more_averaged_data.jld2 -├── 1 outputs: c averaged on AveragedTimeInterval(window=5 minutes, stride=1, interval=20 minutes) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 17.9 KiB ``` - See [`JLD2OutputWriter`](@ref) for more information. ## Time-averaged output @@ -293,7 +229,7 @@ AveragedTimeInterval(window=1 day, stride=1, interval=4 days) An `AveragedTimeInterval` schedule directs an output writer to time-average its outputs before writing them to disk: -```jldoctest averaged_time_interval +```@example averaged_time_interval using Oceananigans using Oceananigans.Units @@ -304,13 +240,4 @@ simulation = Simulation(model, Δt=10minutes, stop_time=30days) simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities, filename = "even_more_averaged_velocity_data.jld2", schedule = AveragedTimeInterval(4days, window=1day, stride=2)) - -# output -JLD2OutputWriter scheduled on TimeInterval(4 days): -├── filepath: ./even_more_averaged_velocity_data.jld2 -├── 3 outputs: (u, v, w) averaged on AveragedTimeInterval(window=1 day, stride=2, interval=4 days) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 27.1 KiB ``` diff --git a/src/OutputWriters/jld2_output_writer.jl b/src/OutputWriters/jld2_output_writer.jl index 5f2afd2b03..0cc4d77998 100644 --- a/src/OutputWriters/jld2_output_writer.jl +++ b/src/OutputWriters/jld2_output_writer.jl @@ -110,7 +110,7 @@ Example Write out 3D fields for ``u``, ``v``, ``w``, and a tracer ``c``, along with a horizontal average: -``` +```@example using Oceananigans using Oceananigans.Utils: hour, minute @@ -131,33 +131,15 @@ simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocitie filename = "some_data.jld2", schedule = TimeInterval(20minute), init = init_save_some_metadata!) - -# output -JLD2OutputWriter scheduled on TimeInterval(20 minutes): -├── filepath: ./some_data.jld2 -├── 3 outputs: (u, v, w) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 28.0 KiB ``` and a time- and horizontal-average of tracer ``c`` every 20 minutes of simulation time to a file called `some_averaged_data.jld2` -``` +```@example simulation.output_writers[:avg_c] = JLD2OutputWriter(model, (; c=c_avg), filename = "some_averaged_data.jld2", schedule = AveragedTimeInterval(20minute, window=5minute)) - -# output -JLD2OutputWriter scheduled on TimeInterval(20 minutes): -├── filepath: ./some_averaged_data.jld2 -├── 1 outputs: c averaged on AveragedTimeInterval(window=5 minutes, stride=1, interval=20 minutes) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 17.8 KiB ``` """ function JLD2OutputWriter(model, outputs; filename, schedule, diff --git a/src/OutputWriters/netcdf_output_writer.jl b/src/OutputWriters/netcdf_output_writer.jl index 60ef6cc512..a9ddd937da 100644 --- a/src/OutputWriters/netcdf_output_writer.jl +++ b/src/OutputWriters/netcdf_output_writer.jl @@ -265,7 +265,7 @@ Examples Saving the ``u`` velocity field and temperature fields, the full 3D fields and surface 2D slices to separate NetCDF files: -```jldoctest netcdf1 +```@example netcdf1 using Oceananigans grid = RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1)) @@ -278,53 +278,26 @@ fields = Dict("u" => model.velocities.u, "c" => model.tracers.c) simulation.output_writers[:field_writer] = NetCDFOutputWriter(model, fields, filename="fields.nc", schedule=TimeInterval(60)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./fields.nc -├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0) -├── 2 outputs: (c, u) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.9 KiB ``` -```jldoctest netcdf1 +```@example netcdf1 simulation.output_writers[:surface_slice_writer] = NetCDFOutputWriter(model, fields, filename="surface_xy_slice.nc", schedule=TimeInterval(60), indices=(:, :, grid.Nz)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./surface_xy_slice.nc -├── dimensions: zC(1), zF(1), xC(16), yF(16), xF(16), yC(16), time(0) -├── 2 outputs: (c, u) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.9 KiB ``` -```jldoctest netcdf1 +```@example netcdf1 simulation.output_writers[:averaged_profile_writer] = NetCDFOutputWriter(model, fields, filename = "averaged_z_profile.nc", schedule = AveragedTimeInterval(60, window=20), indices = (1, 1, :)) - -# output -NetCDFOutputWriter scheduled on TimeInterval(1 minute): -├── filepath: ./averaged_z_profile.nc -├── dimensions: zC(16), zF(17), xC(1), yF(1), xF(1), yC(1), time(0) -├── 2 outputs: (c, u) averaged on AveragedTimeInterval(window=20 seconds, stride=1, interval=1 minute) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 17.6 KiB ``` `NetCDFOutputWriter` also accepts output functions that write scalars and arrays to disk, provided that their `dimensions` are provided: -```jldoctest +```@example using Oceananigans Nx, Ny, Nz = 16, 16, 16 @@ -361,22 +334,13 @@ simulation.output_writers[:things] = NetCDFOutputWriter(model, outputs, schedule=IterationInterval(1), filename="things.nc", dimensions=dims, verbose=true, global_attributes=global_attributes, output_attributes=output_attributes) - -# output -NetCDFOutputWriter scheduled on IterationInterval(1): -├── filepath: ./things.nc -├── dimensions: zC(16), zF(17), xC(16), yF(16), xF(16), yC(16), time(0) -├── 3 outputs: (profile, slice, scalar) -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 17.8 KiB ``` `NetCDFOutputWriter` can also be configured for `outputs` that are interpolated or regridded to a different grid than `model.grid`. To use this functionality, include the keyword argument `grid = output_grid`. -```jldoctest +```@example using Oceananigans using Oceananigans.Fields: interpolate! @@ -393,15 +357,6 @@ output_writer = NetCDFOutputWriter(model, outputs; grid = coarse_grid, filename = "coarse_u.nc", schedule = IterationInterval(1)) - -# output -NetCDFOutputWriter scheduled on IterationInterval(1): -├── filepath: ./coarse_u.nc -├── dimensions: zC(4), zF(5), xC(1), yF(1), xF(1), yC(1), time(0) -├── 1 outputs: u -└── array type: Array{Float64} -├── file_splitting: NoFileSplitting -└── file size: 14.6 KiB ``` """ function NetCDFOutputWriter(model, outputs; diff --git a/src/OutputWriters/windowed_time_average.jl b/src/OutputWriters/windowed_time_average.jl index c36a7cf528..11f8be5682 100644 --- a/src/OutputWriters/windowed_time_average.jl +++ b/src/OutputWriters/windowed_time_average.jl @@ -59,7 +59,7 @@ AveragedTimeInterval(window=2 days, stride=1, interval=4 days) An `AveragedTimeInterval` schedule directs an output writer to time-average its outputs before writing them to disk: -```jldoctest averaged_time_interval +```@example averaged_time_interval using Oceananigans using Oceananigans.Units @@ -70,15 +70,6 @@ simulation = Simulation(model, Δt=10minutes, stop_time=30days) simulation.output_writers[:velocities] = JLD2OutputWriter(model, model.velocities, filename= "averaged_velocity_data.jld2", schedule = AveragedTimeInterval(4days, window=2days, stride=2)) - -# output -JLD2OutputWriter scheduled on TimeInterval(4 days): -├── filepath: ./averaged_velocity_data.jld2 -├── 3 outputs: (u, v, w) averaged on AveragedTimeInterval(window=2 days, stride=2, interval=4 days) -├── array type: Array{Float64} -├── including: [:grid, :coriolis, :buoyancy, :closure] -├── file_splitting: NoFileSplitting -└── file size: 27.6 KiB ``` """ function AveragedTimeInterval(interval; window=interval, stride=1)