Merge pull request #988 from cbegeman/new-ocn-conservation-task

New ocean conservation task

Author: xylar

docs/developers_guide/api.rst

@@ -61,6 +61,7 @@ Ocean tasks
 .. autosummary::
    :toctree: generated/
 
+   ConservationTask
    ClimatologyMapSST
    ClimatologyMapSSS
    ClimatologyMapMLD
@@ -75,6 +76,7 @@ Ocean tasks
    ClimatologyMapWaves
    IndexNino34
    MeridionalHeatTransport
+   OceanHistogram
    StreamfunctionMOC
    TimeSeriesOHCAnomaly
    TimeSeriesTemperatureAnomaly

docs/users_guide/analysis_tasks.rst

@@ -37,6 +37,7 @@ Analysis Tasks
    tasks/oceanRegionalProfiles
    tasks/regionalTSDiagrams
    tasks/oceanHistogram
+   tasks/conservation
 
    tasks/climatologyMapSeaIceConcNH
    tasks/climatologyMapSeaIceThickNH

docs/users_guide/tasks/conservation.rst

@@ -0,0 +1,63 @@
+.. _task_conservation:
+
+conservation
+============
+
+An analysis task for plotting histograms of 2-d variables of climatologies
+in ocean regions.
+
+Component and Tags::
+
+  component: ocean
+  tags: timeseries, conservation
+
+Configuration Options
+---------------------
+
+The following configuration options are available for this task:
+
+.. code-block:: cfg
+
+    [conservation]
+    ## options related to producing time series plots, often to compare against
+    ## observations and previous runs
+    
+    # the year from which to compute anomalies if not the start year of the
+    # simulation.  This might be useful if a long spin-up cycle is performed and
+    # only the anomaly over a later span of years is of interest.
+    # anomalyRefYear = 249
+    
+    # start and end years for timeseries analysis. Use endYear = end to indicate
+    # that the full range of the data should be used.  If errorOnMissing = False,
+    # the start and end year will be clipped to the valid range.  Otherwise, out
+    # of bounds values will lead to an error.  In a "control" config file used in
+    # a "main vs. control" analysis run, the range of years must be valid and
+    # cannot include "end" because the original data may not be available.
+    startYear = 1
+    endYear = end
+    
+    # Plot types to generate. The following plotTypes are supported:
+    #    total_energy_flux : Total energy flux
+    #    absolute_energy_error : Energy error
+    #    ice_salt_flux : Salt flux related to land ice and sea ice
+    #    absolute_salt_error : Salt conservation error
+    #    total_mass_flux : Total mass flux
+    #    total_mass_change : Total mass anomaly
+    #    land_ice_mass_change : Mass anomaly due to land ice fluxes
+    #    land_ice_ssh_change : SSH anomaly due to land ice fluxes
+    #    land_ice_mass_flux_components : Mass fluxes from land ice
+    plotTypes = 'land_ice_mass_flux_components'
+    
+    # line colors for the main, control and obs curves
+    # see https://matplotlib.org/stable/gallery/color/named_colors.html
+    # and https://matplotlib.org/stable/tutorials/colors/colors.html
+    mainColor = black
+    controlColor = tab:red
+
+
+Example Result
+--------------
+
+.. image:: examples/total_mass_flux.png
+   :width: 500 px
+   :align: center

docs/users_guide/tasks/examples/total_mass_flux.png

@@ -172,6 +172,9 @@ def build_analysis_list(config, controlConfig):
         config, oceanClimatologyTasks['avg'], oceanRegionMasksTask,
         controlConfig))
 
+    analyses.append(ocean.ConservationTask(
+        config, controlConfig))
+
     analyses.append(ocean.RegionalTSDiagrams(
         config, oceanClimatologyTasks['avg'], oceanRegionMasksTask,
         controlConfig))

mpas_analysis/__main__.py

@@ -171,6 +171,7 @@ logsSubdirectory = logs
 mpasClimatologySubdirectory = clim/mpas
 mappingSubdirectory = mapping
 timeSeriesSubdirectory = timeseries
+conservationSubdirectory = timeseries
 histogramSubdirectory = histograms
 profilesSubdirectory = profiles
 maskSubdirectory = masks
@@ -322,6 +323,24 @@ obsColor5 = tab:cyan
 
 fitColor1 = tab:blue
 
+
+[timeSeriesConservation]
+## options related to producing time series plots from the conservation
+## analysis member, often to compare previous runs
+
+# Plot types to generate. The following plotTypes are supported:
+#    total_energy_flux : Total energy flux
+#    absolute_energy_error : Energy error
+#    ice_salt_flux : Salt flux related to land ice and sea ice
+#    absolute_salt_error : Salt conservation error
+#    total_mass_flux : Total mass flux
+#    total_mass_change : Total mass anomaly
+#    land_ice_mass_change : Mass anomaly due to land ice fluxes
+#    land_ice_ssh_change : SSH anomaly due to land ice fluxes
+#    land_ice_mass_flux_components : Mass fluxes from land ice
+plotTypes = ['absolute_energy_error', 'absolute_salt_error', 'total_mass_change']
+
+
 [index]
 ## options related to producing nino index.
 

mpas_analysis/default.cfg

@@ -23,6 +23,8 @@
 from mpas_analysis.ocean.climatology_map_argo import \
     ClimatologyMapArgoTemperature, ClimatologyMapArgoSalinity
 
+from mpas_analysis.ocean.conservation import ConservationTask
+
 from mpas_analysis.ocean.time_series_temperature_anomaly import \
     TimeSeriesTemperatureAnomaly
 from mpas_analysis.ocean.time_series_salinity_anomaly import \