Add elevation profile in NetCDF output

[skip ci][ci skip]

docs/src/diagnostics.md

@@ -175,6 +175,17 @@ Given a timestep `dt`, a `ScheduledDiagnosticIterations` can be obtained from a
 `ScheduledDiagnosticTime` `sd` simply by calling
 ``ScheduledDiagnosticIterations(sd, dt)`.
 
+## The NetCDF output
+
+The NetCDF writer in `ClimaAtmos` saves different diagnostics to different files
+in the same output folder. Files are named after a combination of the diagnostic
+variable `short_name`, and the details of the temporal reduction. Inside each
+NetCDF file, there is only one diagnostic variable, along with the various
+dimensions (e.g., `lat`, `lon`, and `z`). For simulations with topography, the
+variable `z` is no longer a simple vector `z[k]`, but it is a full
+multidimensional array `z[i, j, k]` which defines the elevation on the sea level
+of the point of indices `[i, j, k]`.
+
 ## I want to add a new diagnostic variable
 
 Diagnostic variables are represented in `ClimaAtmos` with a `DiagnosticVariable`

src/diagnostics/hdf5_writer.jl

@@ -0,0 +1,65 @@
+##############
+# HDF5Writer #
+##############
+
+"""
+    HDF5Writer()
+
+
+Save a `ScheduledDiagnostic` to a HDF5 file inside the `output_dir` of the simulation.
+
+
+TODO: This is a very barebone HDF5Writer. Do not consider this implementation as the "final
+word".
+
+We need to implement the following features/options:
+- Toggle for write new files/append
+- Checks for existing files
+- Check for new subfolders that have to be created
+- More meaningful naming conventions (keeping in mind that we can have multiple variables
+  with different reductions)
+- All variables in one file/each variable in its own file
+- All timesteps in one file/each timestep in its own file
+- Writing the correct attributes
+- Overriding simulation.output_dir (e.g., if the path starts with /)
+- ...more features/options
+
+"""
+struct HDF5Writer end
+
+
+"""
+    close(writer::HDF5Writer)
+
+Close all the files open in `writer`. (Currently no-op.)
+"""
+close(writer::HDF5Writer) = nothing
+
+function write_field!(writer::HDF5Writer, field, diagnostic, integrator)
+    var = diagnostic.variable
+    time = integrator.t
+
+    output_path = joinpath(
+        integrator.p.simulation.output_dir,
+        "$(diagnostic.output_short_name)_$(time).h5",
+    )
+
+    hdfwriter = InputOutput.HDF5Writer(output_path, integrator.p.comms_ctx)
+    InputOutput.write!(hdfwriter, field, "$(diagnostic.output_short_name)")
+    attributes = Dict(
+        "time" => time,
+        "long_name" => diagnostic.output_long_name,
+        "variable_units" => var.units,
+        "standard_variable_name" => var.standard_name,
+    )
+
+    # TODO: Use directly InputOutput functions
+    InputOutput.HDF5.h5writeattr(
+        hdfwriter.file.filename,
+        "fields/$(diagnostic.output_short_name)",
+        attributes,
+    )
+
+    Base.close(hdfwriter)
+    return nothing
+end