Add documentation for 1D Column Hydrostatic Balance and Ekman Layer examplesExpdoc #2325

Snowdog85123 · 2025-05-15T05:06:55Z

They complement the existing 1D column examples and provide more atmospheric physics use cases.

This new PR replaces the previous one and includes only the intended changes.

Code follows the style guidelines OR N/A.
Unit tests are included OR N/A.
Code is exercised in an integration test OR N/A.
Documentation has been added/updated OR N/A.

Hello, following up on the idea I previously shared in the issue, I've added documentation [docs/src/examples.md](https://github.com/CliMA/ClimaCore.jl/blob/main/docs/src/examples.md) for the two 1D column examples: the hydrostatic balance and the Ekman layer. Please let me know if this contribution aligns with your goals for the documentation or if any revisions are needed. I'd be happy to make changes!

Add 1D Column Examples for Hydrostatic Balance and Ekman Layer

docs/src/examples.md

Snowdog85123 · 2025-05-15T05:37:35Z

@valeriabarra I've reordered the examples and removed the root-level file as requested. Please let me know if anything else needs adjustment.

valeriabarra · 2025-05-16T01:55:21Z

docs/src/examples.md

+The application of boundary conditions is implemented through the operators:
+
+1. For the u-momentum equation:
+   - Top boundary: `Operators.SetValue(FT(ug))` sets u to the geostrophic value


Suggested change

- Top boundary: `Operators.SetValue(FT(ug))` sets u to the geostrophic value

- Top boundary: `Operators.SetValue(FT(ug))` sets $u$ to the geostrophic value

valeriabarra · 2025-05-16T01:58:12Z

docs/src/examples.md

+   - Bottom boundary: `Operators.SetValue(Geometry.WVector(Cd * u_wind * u_1))` applies the drag condition
+
+2. For the v-momentum equation:
+   - Top boundary: `Operators.SetValue(FT(vg))` sets v to the geostrophic value


Suggested change

- Top boundary: `Operators.SetValue(FT(vg))` sets v to the geostrophic value

- Top boundary: `Operators.SetValue(FT(vg))` sets $v$ to the geostrophic value

valeriabarra · 2025-05-16T02:00:06Z

docs/src/examples.md

+   - Top boundary: `Operators.SetValue(FT(vg))` sets v to the geostrophic value
+   - Bottom boundary: `Operators.SetValue(Geometry.WVector(Cd * u_wind * v_1))` applies the drag condition
+
+3. DSS (Direct Stiffness Summation) is applied implicitly through the operators to ensure continuity of the solution at element boundaries and reduction of unnecessary multiplicity


Suggested change

3. DSS (Direct Stiffness Summation) is applied implicitly through the operators to ensure continuity of the solution at element boundaries and reduction of unnecessary multiplicity

valeriabarra · 2025-05-16T02:03:13Z

docs/src/examples.md

+
+This test case is set up in a vertical column domain from $z=0$ m to $z=30$ km with 30 vertical elements. The column is initialized with a decaying temperature profile, where:
+
+- The virtual temperature starts at $T_{virt\_surf} = 280$ K at the surface


Suggested change

- The virtual temperature starts at $T_{virt\_surf} = 280$ K at the surface

- The virtual temperature starts at $T_{\textrm{virt}\_\textrm{surf}} = 280$ K at the surface

Please double check that the suggested \textrm syntax works as intended in the subscript mode.
Also, please post screenshot of the rendered built docs to ease reviews. Thank you

valeriabarra · 2025-05-16T02:06:41Z

docs/src/examples.md

+This test case is set up in a vertical column domain from $z=0$ m to $z=30$ km with 30 vertical elements. The column is initialized with a decaying temperature profile, where:
+
+- The virtual temperature starts at $T_{virt\_surf} = 280$ K at the surface
+- It asymptotically approaches $T_{min\_ref} = 230$ K with height


Suggested change

- It asymptotically approaches $T_{min\_ref} = 230$ K with height

- It asymptotically approaches $T_{\textrm{min}\_\textrm{ref}} = 230$ K with height

Same as above. Thank yoy

Snowdog85123 · 2025-05-16T04:28:27Z

screenshot of the rendered built docs:

valeriabarra · 2025-05-16T17:39:04Z

docs/src/examples.md

+\frac{\partial u}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(u)\right) + f(v - v_g) - A(w, u) \\
+\frac{\partial v}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(v)\right) - f(u - u_g) - A(w, v)


Hi @Snowdog85123 , it is best to keep consistent notation with the rest of the document (see examples above and below yours already present in the file) . Hence, here it is best to not use the subscripts specifications for c2f and f2c, as they are explained below anyways.

Suggested change

\frac{\partial u}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(u)\right) + f(v - v_g) - A(w, u) \\

\frac{\partial v}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(v)\right) - f(u - u_g) - A(w, v)

\frac{\partial u}{\partial t} &\approx D\left(\nu G(u)\right) + f(v - v_g) - A(w, u) \\

\frac{\partial v}{\partial t} &\approx D\left(\nu G(v)\right) - f(u - u_g) - A(w, v)

valeriabarra · 2025-05-16T17:42:42Z

docs/src/examples.md

+- `G_{c2f}` is the [gradient operator from cell centers to faces](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.GradientC2F), called `gradc2f` in the example code.
+- `D_{f2c}` is the [divergence operator from faces to centers](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.DivergenceF2C), called `divf2c` in the example code.


Similar to my above comment.

Suggested change

- `G_{c2f}` is the [gradient operator from cell centers to faces](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.GradientC2F), called `gradc2f` in the example code.

- `D_{f2c}` is the [divergence operator from faces to centers](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.DivergenceF2C), called `divf2c` in the example code.

- ``D`` is the [face-to-center divergence](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.DivergenceF2C) operator, called `divf2c` in the example code

- ``G`` is the [center-to-face gradient](https://clima.github.io/ClimaCore.jl/dev/operators/#ClimaCore.Operators.GradientC2F) operator, called `gradc2f` in the example code

valeriabarra · 2025-05-16T17:44:12Z

docs/src/examples.md

+
+- `G_{c2f}` is the [gradient operator from cell centers to faces](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.GradientC2F), called `gradc2f` in the example code.
+- `D_{f2c}` is the [divergence operator from faces to centers](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.DivergenceF2C), called `divf2c` in the example code.
+- `A` is the [advection operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.AdvectionC2C), called `A` in the example code.


Suggested change

- `A` is the [advection operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.AdvectionC2C), called `A` in the example code.

- ``A`` is the [center-to-center vertical advection](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.AdvectionC2C) operator, called `A` in the example code.

valeriabarra · 2025-05-16T17:45:07Z

docs/src/examples.md

+
+##### Reconstructions
+
+**$I^f$** is the [center-to-face reconstruction operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.InterpolateC2F), called `If` in the example code.  


Suggested change

**$I^f$** is the [center-to-face reconstruction operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.InterpolateC2F), called `If` in the example code.

**$I^f$** is the [center-to-face reconstruction](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.InterpolateC2F) operator, called `If` in the example code.

Snowdog85123 · 2025-05-17T22:22:51Z

Hi @valeriabarra , I just modified as you suggested.

Snowdog85123 added 8 commits April 18, 2025 12:55

Merge pull request #1 from Snowdog85123/Snowdog85123-patch-1

1298ecf

Add 1D Column Examples for Hydrostatic Balance and Ekman Layer

Add files via upload

673af0b

Merge branch 'CliMA:main' into main

223000d

Merge branch 'CliMA:main' into main

43aafdd

Add 1D Column Hydrostatic Balance and Ekman Layer examples documentation

88929f2

Merge branch 'CliMA:main' into main

d930fc9

Add 1D Column Hydrostatic Balance and Ekman Layer examples documentation

fd3c717

valeriabarra requested changes May 15, 2025

View reviewed changes

docs/src/examples.md Show resolved Hide resolved

Reorder examples and remove root-level examples.md

b59e19b

valeriabarra reviewed May 16, 2025

View reviewed changes

Snowdog85123 added 2 commits May 15, 2025 21:13

refine as suggested

e20c01f

modified

02e3d08

valeriabarra reviewed May 16, 2025

View reviewed changes

modified as suggested

ef96f6f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for 1D Column Hydrostatic Balance and Ekman Layer examplesExpdoc #2325

Add documentation for 1D Column Hydrostatic Balance and Ekman Layer examplesExpdoc #2325

Snowdog85123 commented May 15, 2025

Snowdog85123 commented May 15, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

Snowdog85123 commented May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

valeriabarra May 16, 2025

Snowdog85123 commented May 17, 2025

	- Top boundary: `Operators.SetValue(FT(ug))` sets u to the geostrophic value
	- Top boundary: `Operators.SetValue(FT(ug))` sets $u$ to the geostrophic value

	- Top boundary: `Operators.SetValue(FT(vg))` sets v to the geostrophic value
	- Top boundary: `Operators.SetValue(FT(vg))` sets $v$ to the geostrophic value


		This test case is set up in a vertical column domain from $z=0$ m to $z=30$ km with 30 vertical elements. The column is initialized with a decaying temperature profile, where:

		- The virtual temperature starts at $T_{virt\_surf} = 280$ K at the surface

	- It asymptotically approaches $T_{min\_ref} = 230$ K with height
	- It asymptotically approaches $T_{\textrm{min}\_\textrm{ref}} = 230$ K with height

		\frac{\partial u}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(u)\right) + f(v - v_g) - A(w, u) \\
		\frac{\partial v}{\partial t} &\approx D_{f2c}\left(\nu G_{c2f}(v)\right) - f(u - u_g) - A(w, v)

		- `G_{c2f}` is the [gradient operator from cell centers to faces](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.GradientC2F), called `gradc2f` in the example code.
		- `D_{f2c}` is the [divergence operator from faces to centers](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.DivergenceF2C), called `divf2c` in the example code.

	- `A` is the [advection operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.AdvectionC2C), called `A` in the example code.
	- ``A`` is the [center-to-center vertical advection](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.AdvectionC2C) operator, called `A` in the example code.


		##### Reconstructions

		$I^f$ is the [center-to-face reconstruction operator](https://clima.github.io/ClimaCore.jl/stable/operators/#ClimaCore.Operators.InterpolateC2F), called `If` in the example code.

Add documentation for 1D Column Hydrostatic Balance and Ekman Layer examplesExpdoc #2325

Are you sure you want to change the base?

Add documentation for 1D Column Hydrostatic Balance and Ekman Layer examplesExpdoc #2325

Conversation

Snowdog85123 commented May 15, 2025

Snowdog85123 commented May 15, 2025

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

Snowdog85123 commented May 16, 2025

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

Snowdog85123 commented May 17, 2025