Hello, ocean example #1181

glwagner · 2020-11-14T13:41:04Z

This PR adds a new minimal example that simulates and plots a rising buoyant bubble:

# # Hello, ocean!
#
# > How inappropriate to call this planet Earth, when it is quite clearly _Ocean_.
#
#   --Arthur C. Clark

using Oceananigans, Oceananigans.Grids, Plots

grid = RegularCartesianGrid(size = (1, 64, 64),
                            x = (0, 1), y = (-4, 4), z = (-4, 4),
                            topology = (Periodic, Bounded, Bounded))

model = IncompressibleModel(grid = grid,
                            architecture = CPU(),
                            advection = Oceananigans.Advection.WENO5(),
                            tracers = :b,
                            buoyancy = BuoyancyTracer(),
                            closure = IsotropicDiffusivity(ν=1e-3, κ=1e-3))

@info "Simulating a rising buoyant bubble with" model

set!(model, b = (x, y, z) -> exp(-y^2 - z^2))

run!(Simulation(model, Δt=0.01, stop_iteration=800))

# Analyze the data

b = model.tracers.b

plt = contourf(ynodes(b), znodes(b), interior(b)[1, :, :]',
               xlabel = "y", ylabel = "z", title = "Buoyancy",
               xlim = (grid.yF[1], grid.yF[end]), ylim = (grid.zF[1], grid.zF[end]),
               aspectratio = :equal, linewidth = 0)

display(plt) # hide

If we do think an example like this would be nice to have, it might make sense to replace the README example with this one (and perhaps otherwise improve the README).

I didn't add it to the list of examples in the docs, but it is set up (in it's minimal way) for Literate-ing. Or we can un-literate it.

Suggest away and I shall commit!

The script produces

Could also add a pkg"add Oceananigans, Plots" at the top per the discussion on #1149, but it might better to unify all the examples at once in a dedicated PR.

codecov · 2020-11-14T14:20:14Z

Codecov Report

Merging #1181 (c717dd5) into master (03a6f85) will decrease coverage by 6.95%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #1181      +/-   ##
==========================================
- Coverage   56.99%   50.03%   -6.96%     
==========================================
  Files         162      161       -1     
  Lines        3916     3849      -67     
==========================================
- Hits         2232     1926     -306     
- Misses       1684     1923     +239

Impacted Files	Coverage Δ
src/Grids/vertically_stretched_cartesian_grid.jl	`0.00% <0.00%> (-93.11%)`	⬇️
src/Solvers/box_pressure_solver.jl	`0.00% <0.00%> (-86.37%)`	⬇️
src/Coriolis/non_traditional_f_plane.jl	`0.00% <0.00%> (-62.50%)`	⬇️
src/Advection/weno_reconstruction.jl	`0.00% <0.00%> (-60.00%)`	⬇️
src/Coriolis/beta_plane.jl	`0.00% <0.00%> (-58.83%)`	⬇️
src/Solvers/batched_tridiagonal_solver.jl	`0.00% <0.00%> (-58.07%)`	⬇️
src/Coriolis/non_traditional_beta_plane.jl	`0.00% <0.00%> (-54.17%)`	⬇️
src/Fields/reduced_field.jl	`28.94% <0.00%> (-50.01%)`	⬇️
src/Advection/weno_fifth_order.jl	`0.00% <0.00%> (-44.28%)`	⬇️
src/Buoyancy/Buoyancy.jl	`47.36% <0.00%> (-32.64%)`	⬇️
... and 49 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 03a6f85...c717dd5. Read the comment docs.

navidcy

I like it.

The way it's written though is not ready to go into the literated examples list. But we should include be literating it (even if we decide that we should not include it in the docs) to make sure it can run as the code keeps changing.

I'm a bit conflicted whether we should keep this as simple as is and include it in the README or whether we should add more explanations and include it in the list of literated docs examples... Probably I'd vote for the former since I don't see anything that this example has to offer in terms of demonstrating Oceananigans.jl functionality.

navidcy · 2020-11-15T02:11:49Z

examples/hello_ocean.jl

+
+using Oceananigans, Oceananigans.Grids, Plots
+
+grid = RegularCartesianGrid(size = (1, 64, 64),


why not x and z? I think that's more natural

because using y, z generalizes to GPU

and x, z does not?

no, not if x is bounded

you are saying that

grid = RegularCartesianGrid(size = (1, 64, 64), x = (-4, 4), y = (0, 1), z = (-4, 4), topology = (Bounded, Periodic, Bounded))

won't run on GPU?

Yeah topology = (Bounded, Periodic, Bounded) won't even run on the CPU right now for the same reason as #1007.

I'm working on supporting all topologies in the ali/pressure-solver-tlc branch so topology = (Bounded, Periodic, Bounded) works on the CPU there, but still needs more work and TLC for the GPU to support all topologies.

examples/hello_ocean.jl

navidcy · 2020-11-15T02:12:54Z

examples/hello_ocean.jl

+
+@info "Simulating a rising buoyant bubble with" model
+
+set!(model, b = (x, y, z) -> exp(-y^2 - z^2))


Is, perhaps, exp(-(y^2 + z^2)) more soothing for the eye?

that's more characters!

my question was whether it's more soothing for the eye not whether it's easier for the fingers of the person who types it...

characters strain the eye, as well as typing fingers...

ok, fair enough.

But it bothers me that y kisses the minus sign before it while there is some distance between - and z... Seems like y and z are not treated equally..

navidcy · 2020-11-15T02:13:57Z

examples/hello_ocean.jl

+
+b = model.tracers.b
+
+plt = contourf(ynodes(b), znodes(b), interior(b)[1, :, :]',


Why not an animation?
Or if we just plot, then I suggest we plot both the initial + final snapshot?

animation is too much for "hello, ocean"... ?

could plot initial, yes

i think plotting the initial conditions would add information for sure. however, it would create 3 additional lines at least

hmm, if we make the plot (but don't save the data), and then just combine the plots after, it is just 2 additional lines. perhaps worth it.

I'm definitely on board for more animation but a nice plot should be enough for the first introductory example (initial conditions would be pretty useful I think).

I think the bigger issue with doing animation is it would complicate the example since it either requires an output writer (probably a good thing to show although all the Literate.jl examples show how to use output writers). Without an output writer, the plotting has to happen in a loop that keeps extending simulation.stop_time which is not a nice pattern.

examples/hello_ocean.jl

glwagner · 2020-11-15T02:30:09Z

Probably I'd vote for the former since I don't see anything that this example has to offer in terms of demonstrating Oceananigans.jl functionality.

The purpose of a hello, ocean is to illustrate syntax in a "minimal" example. It's a teaser, something to draw you in. Eg

https://en.wikipedia.org/wiki/%22Hello,_World!%22_program

glwagner · 2020-11-15T02:33:55Z

@navidcy what do you think about the thermal bubble as the "canonical minimal example" ? Is there something better, more striking, simpler, more fun?

navidcy · 2020-11-15T02:33:57Z

julia> minimum(interior(b)[1, :, :])
-0.0009534228444548004

Is this OK?

glwagner · 2020-11-15T02:35:03Z

Is this OK?

oscillatory errors?

navidcy · 2020-11-15T02:35:35Z

@navidcy what do you think about the thermal bubble as the "canonical minimal example" ? Is there something better, more striking, simpler, more fun?

Exactly! I agree! That's why I voted for the former, i.e., leave it as is and include it in the README.

glwagner · 2020-11-15T02:36:50Z

Exactly! I agree! That's why I voted for the former, i.e., leave it as is and include it in the README.

But can we think of other possibilities?

An initial value problem seems good, as well as one where "something" happens. It might be more ocean-y if it was convection or something... hmm.

glwagner · 2020-11-15T02:38:48Z

https://www.youtube.com/watch?v=95zljDYHSqU&feature=emb_title

https://grenouillebouillie.wordpress.com/2010/07/24/hello-world/

"Only 23 lines..." but looks like we are at 35 (and no spinning Earth)

navidcy · 2020-11-15T02:50:18Z

Is this OK?

oscillatory errors?

Probably you are correct...

The minimum value reduces by a factor of 4 if I use 128x128 points.
It also reduces by a factor of 40 if I use half the time-step + use RK3.

So let's leave it as is.

glwagner · 2020-11-15T02:51:50Z

It also reduces by a factor of 40 if I use half the time-step + use RK3

Ah, let's do that!

glwagner · 2020-11-15T02:54:15Z

It would be a few more lines, but a forcing that creates an internal wave (eg St. Andrews Cross) might be "more canonical"... ?

navidcy · 2020-11-15T02:59:47Z

It would be a few more lines, but a forcing that creates an internal wave (eg St. Andrews Cross) might be "more canonical"... ?

That's another good idea.

glwagner · 2020-11-15T14:05:44Z

I think a really cool one would be some kind of breaking internal pattern that looks like a breaking wave (our signature emoji)

glwagner · 2020-11-15T14:31:41Z

Not quite right but going in the right direction

Maybe need a bona fide wave pattern :-/

navidcy · 2020-11-15T22:04:47Z

I actually think I prefer the bubble...

glwagner · 2020-11-16T03:11:33Z

I actually think I prefer the bubble...

Do you have any ideas for producing a nice looking breaking wave pattern?

glwagner · 2020-11-16T03:16:08Z

The way it's written though is not ready to go into the literated examples list.

Can you elaborate? What isn't ready about it? If there are ways to make it shorter or better, we should definitely do that in this PR rather than later!

navidcy · 2020-11-16T04:32:41Z

The way it's written though is not ready to go into the literated examples list.

Can you elaborate? What isn't ready about it? If there are ways to make it shorter or better, we should definitely do that in this PR rather than later!

I can elaborate. What I meant is that this example, although it's Literate-ready, it does not provide any explanation to the reader about what's coming. All other examples come with remarks of the sort "we now build the grid"... "Next, let's form a model with two tracers...", "now all what's left to do is to run the simulation"... On the other hand, this example just list down the commands without any explanation.

I'm not saying that's bad. It's just different from the rest of the examples. I think it's perfect for the README file but. in my opinion, you don't wanna see this as your first example if you are reading the docs because it doesn't really take you from the hand and guide you to feel welcome in all this new Oceananigans.jl terminology.

To conclude: I think we should add it to the Literate examples list, e.g., in docs/make.jl

examples = [
    "hello_ocean.jl",
    "one_dimensional_diffusion.jl",
    "two_dimensional_turbulence.jl",
    "internal_wave.jl",
    "convecting_plankton.jl",
    "ocean_wind_mixing_and_convection.jl",
    "langmuir_turbulence.jl",
    "eady_turbulence.jl",
    "kelvin_helmholtz_instability.jl"
]

for example in examples
    example_filepath = joinpath(EXAMPLES_DIR, example)
    Literate.markdown(example_filepath, OUTPUT_DIR, documenter=true)
end

This way, docs will fail if the code cannot run the hello_ocean.jl. But we shouldn't add it in th e
but don't in the example_pages list. Rather, we should include this as part of the README.

That's all what I meant. My 2 cents have been now deposited in this PR. :)

glwagner · 2020-11-16T14:17:33Z

What I meant is that this example, although it's Literate-ready, it does not provide any explanation to the reader about what's coming. All other examples come with remarks of the sort "we now build the grid"... "Next, let's form a model with two tracers...", "now all what's left to do is to run the simulation"... On the other hand, this example just list down the commands without any explanation.

But this example is our "hello, ocean", which has a different purpose than the others... ?

I suspect that different people may want different types of examples, but I'm not sure. I personally like short, revelatory bits of code, especially if I can read the code (using my knowledge of julia and physics) and infer what's going on. Certainly the detailed explanations are nice too, in a different way.

Curious what @ali-ramadhan thinks...

navidcy · 2020-11-29T23:01:40Z

@ali-ramadhan? :)

ali-ramadhan

My understanding is that this example would replace the rising thermal bubble example in the README https://github.com/CliMA/Oceananigans.jl#more-interesting-example (and maybe also have a corresponding version in the docs?).

I think 43 lines might be a bit much for the introductory README example but should be easy to trim down to ~25 lines I think.

ali-ramadhan · 2020-12-31T15:08:41Z

examples/hello_ocean.jl

@@ -0,0 +1,43 @@
+# # Hello, ocean!
+#
+# > How inappropriate to call this planet Earth, when it is quite clearly _Ocean_.


ali-ramadhan · 2020-12-31T15:09:31Z

examples/hello_ocean.jl

+#
+#   --Arthur C. Clark
+
+using Oceananigans, Oceananigans.Grids, Plots


Would be ideal to not have Oceananigans.Grids in the introductory README example (same with Oceananigans.Advection.WENO5) but we already agreed to fix this in the future so it's good for now.

ali-ramadhan · 2020-12-31T15:24:39Z

examples/hello_ocean.jl

+Σ(ξ) = (1 - tanh(ξ)) / 2
+Π(ξ, δ=1) = (Σ(ξ - δ) - Σ(ξ + δ)) / 2
+
+set!(model,
+     u = (x, y, z) -> Σ(-z),
+     b = (x, y, z) -> - Π(4x, 1) * Σ(32z))


I might give these more self-explanatory names as I imagine they look quite cryptic, especially to new users.

glwagner · 2021-01-04T14:47:10Z

The shorter, the better for hello ocean!

This example does a bit more because it adds a plot and uses different numerics (could avoid the need to specify good numerical manually by changing defaults?)

I think hello ocean should plot (otherwise there's no "hello") but we could combine some lines for sure.

Still not sure the best problem. A rising hot patch produces decent viz but not particularly oceanic.

glwagner · 2021-11-15T22:04:14Z

Closing as this is stale, but maybe we'll revise this idea someday.

glwagner added 3 commits November 14, 2020 08:38

Hello, ocean

6420e0a

Slightly less minimal whitespace

89b48bd

Label your axes

82c087f

glwagner requested review from navidcy and ali-ramadhan November 14, 2020 14:05

navidcy requested changes Nov 15, 2020

View reviewed changes

navidcy reviewed Nov 15, 2020

View reviewed changes

examples/hello_ocean.jl Outdated Show resolved Hide resolved

Experiments with a wavy hello ocean

58d47e3

Wavy hello ocean

48c5f13

navidcy added the documentation 📜 The sacred scrolls label Nov 15, 2020

adds hello_ocean.jl in the to-be-literated list

c717dd5

ali-ramadhan approved these changes Dec 31, 2020

View reviewed changes

glwagner closed this Nov 15, 2021


		using Oceananigans, Oceananigans.Grids, Plots

		grid = RegularCartesianGrid(size = (1, 64, 64),


		@info "Simulating a rising buoyant bubble with" model

		set!(model, b = (x, y, z) -> exp(-y^2 - z^2))


		b = model.tracers.b

		plt = contourf(ynodes(b), znodes(b), interior(b)[1, :, :]',

Hello, ocean example #1181

Hello, ocean example #1181

Conversation

glwagner commented Nov 14, 2020 • edited Loading

codecov bot commented Nov 14, 2020 • edited Loading

Codecov Report

navidcy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glwagner Nov 15, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glwagner commented Nov 15, 2020

glwagner commented Nov 15, 2020

navidcy commented Nov 15, 2020 • edited Loading

glwagner commented Nov 15, 2020

navidcy commented Nov 15, 2020

glwagner commented Nov 15, 2020

glwagner commented Nov 15, 2020 • edited Loading

navidcy commented Nov 15, 2020

glwagner commented Nov 15, 2020

glwagner commented Nov 15, 2020 • edited Loading

navidcy commented Nov 15, 2020

glwagner commented Nov 15, 2020

glwagner commented Nov 15, 2020

navidcy commented Nov 15, 2020

glwagner commented Nov 16, 2020

glwagner commented Nov 16, 2020 • edited Loading

navidcy commented Nov 16, 2020

glwagner commented Nov 16, 2020 • edited Loading

navidcy commented Nov 29, 2020

ali-ramadhan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glwagner commented Jan 4, 2021

glwagner commented Nov 15, 2021

glwagner commented Nov 14, 2020 •

edited

Loading

codecov bot commented Nov 14, 2020 •

edited

Loading

glwagner Nov 15, 2020 •

edited

Loading

navidcy commented Nov 15, 2020 •

edited

Loading

glwagner commented Nov 15, 2020 •

edited

Loading

glwagner commented Nov 15, 2020 •

edited

Loading

glwagner commented Nov 16, 2020 •

edited

Loading

glwagner commented Nov 16, 2020 •

edited

Loading