esgvoc 2.0.2__py3-none-any.whl

esgvoc/__init__.py

@@ -0,0 +1,3 @@
+import esgvoc.core.logging_handler  # noqa
+
+__version__ = "2.0.2"

esgvoc/api/__init__.py

@@ -0,0 +1,91 @@
+from esgvoc.api.project_specs import (
+                                      DrsPart,
+                                      DrsSpecification,
+                                      DrsType,
+                                      ProjectSpecs,
+)
+from esgvoc.api.projects import (
+                                      find_collections_in_project,
+                                      find_items_in_project,
+                                      find_terms_in_all_projects,
+                                      find_terms_in_collection,
+                                      find_terms_in_project,
+                                      get_all_collections_in_project,
+                                      get_all_projects,
+                                      get_all_terms_in_all_projects,
+                                      get_all_terms_in_collection,
+                                      get_all_terms_in_project,
+                                      get_collection_from_data_descriptor_in_all_projects,
+                                      get_collection_from_data_descriptor_in_project,
+                                      get_collection_in_project,
+                                      get_project,
+                                      get_term_in_collection,
+                                      get_term_in_project,
+                                      valid_term,
+                                      valid_term_in_all_projects,
+                                      valid_term_in_collection,
+                                      valid_term_in_project,
+)
+from esgvoc.api.report import (
+                                      ProjectTermError,
+                                      UniverseTermError,
+                                      ValidationError,
+                                      ValidationErrorVisitor,
+                                      ValidationReport,
+)
+from esgvoc.api.search import MatchingTerm
+from esgvoc.api.universe import (
+                                      find_data_descriptors_in_universe,
+                                      find_items_in_universe,
+                                      find_terms_in_data_descriptor,
+                                      find_terms_in_universe,
+                                      get_all_data_descriptors_in_universe,
+                                      get_all_terms_in_data_descriptor,
+                                      get_all_terms_in_universe,
+                                      get_data_descriptor_in_universe,
+                                      get_term_in_data_descriptor,
+                                      get_term_in_universe,
+)
+
+__all__ = [
+    "DrsPart",
+    "DrsSpecification",
+    "DrsType",
+    "find_collections_in_project",
+    "find_data_descriptors_in_universe",
+    "find_items_in_project",
+    "find_items_in_universe",
+    "find_terms_in_all_projects",
+    "find_terms_in_collection",
+    "find_terms_in_data_descriptor",
+    "find_terms_in_project",
+    "find_terms_in_universe",
+    "get_all_collections_in_project",
+    "get_all_data_descriptors_in_universe",
+    "get_all_projects",
+    "get_all_terms_in_all_projects",
+    "get_all_terms_in_collection",
+    "get_all_terms_in_data_descriptor",
+    "get_all_terms_in_project",
+    "get_all_terms_in_universe",
+    "get_collection_from_data_descriptor_in_all_projects",
+    "get_collection_from_data_descriptor_in_project",
+    "get_collection_in_project",
+    "get_data_descriptor_in_universe",
+    "get_project",
+    "get_term_in_collection",
+    "get_term_in_data_descriptor",
+    "get_term_in_project",
+    "get_term_in_universe",
+    "MatchingTerm",
+    "ProjectSpecs",
+    "ProjectTermError",
+    "UniverseTermError",
+    "valid_term",
+    "valid_term_in_all_projects",
+    "valid_term_in_collection",
+    "valid_term_in_project",
+    "ValidationError",
+    "ValidationErrorVisitor",
+    "ValidationReport"
+          ]

esgvoc/api/data_descriptors/EMD_models/__init__.py

@@ -0,0 +1,66 @@
+"""
+EMD (Essential Model Documentation) Pydantic Models - Version 1.0
+
+This package implements the EMD v1.0 specification.
+For specification details, see: Essential Model Documentation (EMD) - version 1.0.docx
+
+Major changes from v0.993:
+- Horizontal grid changed from flat to nested 3-level structure
+  (HorizontalComputationalGrid → HorizontalSubgrid → HorizontalGridCells)
+- Field renames: coordinate → vertical_coordinate, native_*_grid → *_computational_grid
+- New required description fields in Model, ModelComponent, and grids
+- New spatial_refinement field in HorizontalGridCells
+"""
+
+# Core EMD models
+from .model import Model
+from .model_component import EMDModelComponent
+from .reference import Reference
+
+# Grid models (v1.0 nested structure)
+from .horizontal_computational_grid import HorizontalComputationalGrid
+from .horizontal_grid_cells import HorizontalGridCells
+from .horizontal_subgrid import HorizontalSubgrid
+from .vertical_computational_grid import VerticalComputationalGrid
+from .vertical_units import VerticalUnits
+
+# Supporting models
+from .resolution import EMDResolution
+
+# Controlled Vocabulary (CV) models - EMD Section 7
+from .arrangement import Arrangement
+from .calendar import Calendar
+from .cell_variable_type import CellVariableType
+from .component_type import ComponentType
+from .coordinate import Coordinate
+from .grid_mapping import GridMapping
+from .grid_region import GridRegion
+from .grid_type import GridType
+from .temporal_refinement import TemporalRefinement
+from .truncation_method import TruncationMethod
+
+__all__ = [
+    # Core models
+    "Model",
+    "EMDModelComponent",
+    "Reference",
+    # Grid models
+    "HorizontalComputationalGrid",
+    "HorizontalSubgrid",
+    "HorizontalGridCells",
+    "VerticalComputationalGrid",
+    "VerticalUnits",
+    # Supporting
+    "EMDResolution",
+    # CV models (Section 7)
+    "Arrangement",
+    "Calendar",
+    "CellVariableType",
+    "ComponentType",
+    "Coordinate",
+    "GridMapping",
+    "GridRegion",
+    "GridType",
+    "TemporalRefinement",
+    "TruncationMethod",
+]

esgvoc/api/data_descriptors/EMD_models/arrangement.py

@@ -0,0 +1,21 @@
+"""
+EMD v1.0 Section 7.3 - arrangement CV
+
+Horizontal grid arrangement types (Arakawa grids).
+"""
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class Arrangement(PlainTermDataDescriptor):
+    """
+    Horizontal grid arrangement (EMD v1.0 Section 7.3).
+
+    Options: arakawa_a, arakawa_b, arakawa_c, arakawa_d, arakawa_e
+
+    A grid arrangement describes the relative locations of mass- and velocity-related quantities
+    on the computed grid (for instance Collins et al. (2013), and for unstructured grids
+    Thuburn et al. (2009)).
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/calendar.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class Calendar(PlainTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/EMD_models/cell_variable_type.py

@@ -0,0 +1,20 @@
+"""
+EMD v1.0 Section 7.4 - cell_variable_type CV
+
+Types of physical variables carried at grid cells.
+"""
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class CellVariableType(PlainTermDataDescriptor):
+    """
+    Cell variable type (EMD v1.0 Section 7.4).
+
+    Options: mass, x_velocity, y_velocity, velocity
+
+    Types of physical variables that are carried at, or representative of conditions at,
+    cells of a horizontal subgrid.
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/component_type.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class ComponentType(PlainTermDataDescriptor):
+    pass

esgvoc/api/data_descriptors/EMD_models/coordinate.py

@@ -0,0 +1,52 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class Coordinate(PlainTermDataDescriptor):
+    """
+    Native vertical grid coordinate type. The coordinate types are all CF standard names (except where indicated) with the same definitions. See section 5.2 Native vertical grid properties.
+    Options for the native vertical grid Coordinate property:
+        • none
+            ◦ (Not a standard name) There is no vertical dimension.
+        • height
+            ◦ Height is the vertical distance above the earth's surface.
+        • geopotential_height
+            ◦ Geopotential height is the geopotential divided by the standard acceleration due to gravity.
+        • air_pressure
+            ◦ Air pressure is the pressure that exists in the medium of air.
+        • air_potential_temperature
+            ◦ Air potential temperature is the temperature a parcel of air would have if moved dry adiabatically to a standard pressure.
+        • atmosphere_ln_pressure_coordinate
+            ◦ Parametric atmosphere natural log pressure coordinate.
+        • atmosphere_sigma_coordinate
+            ◦ Parametric atmosphere sigma coordinate.
+        • atmosphere_hybrid_sigma_pressure_coordinate
+            ◦ Parametric atmosphere hybrid sigma pressure coordinate.
+        • atmosphere_hybrid_height_coordinate
+            ◦ Parametric atmosphere hybrid height coordinate.
+        • atmosphere_sleve_coordinate
+            ◦ Parametric atmosphere smooth vertical level coordinate.
+        • depth
+            ◦ Depth is the vertical distance below the earth's surface.
+        • sea_water_pressure
+            ◦ Sea water pressure is the pressure that exists in the medium of sea water.
+        • sea_water_potential_temperature
+            ◦ Sea water potential temperature is the temperature a parcel of sea water would have if moved adiabatically to sea level pressure.
+        • ocean_sigma_coordinate
+            ◦ Parametric ocean sigma coordinate.
+        • ocean_s_coordinate
+            ◦ Parametric ocean s-coordinate.
+        • ocean_s_coordinate_g1
+            ◦ Parametric ocean s-coordinate, generic form 1.
+        • ocean_s_coordinate_g2
+            ◦ Parametric ocean s-coordinate, generic form 2.
+        • ocean_sigma_z_coordinate
+            ◦ Parametric ocean sigma over z coordinate.
+        • ocean_double_sigma_coordinate
+            ◦ Parametric ocean double sigma coordinate.
+        • land_ice_sigma_coordinate
+            ◦ Land ice (glaciers, ice-caps and ice-sheets resting on bedrock and also includes ice-shelves) sigma coordinate.
+        • z*
+            ◦ (Not a standard name) The z* coordinate of Adcroft and Campin (2004).
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/grid_mapping.py

@@ -0,0 +1,19 @@
+"""
+EMD v1.0 Section 7.7 - grid_mapping CV
+
+Grid mapping (coordinate reference system) types.
+"""
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class GridMapping(PlainTermDataDescriptor):
+    """
+    Grid mapping (EMD v1.0 Section 7.7).
+
+    Options: latitude_longitude, lambert_conformal_conic, etc.
+
+    The name of the coordinate reference system of the horizontal coordinates.
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/grid_region.py

@@ -0,0 +1,19 @@
+"""
+EMD v1.0 Section 7.5 - region CV
+
+Horizontal grid region types.
+"""
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class GridRegion(PlainTermDataDescriptor):
+    """
+    Horizontal grid region (EMD v1.0 Section 7.5).
+
+    Options: global, antarctica, greenland, limited_area, 30S-90S, etc.
+
+    A region is a contiguous part of the Earth's surface which spans the horizontal grid cells.
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/grid_type.py

@@ -0,0 +1,19 @@
+"""
+EMD v1.0 Section 7.6 - grid_type CV
+
+Horizontal grid types.
+"""
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class GridType(PlainTermDataDescriptor):
+    """
+    Horizontal grid type (EMD v1.0 Section 7.6).
+
+    Options: regular_latitude_longitude, regular_gaussian, reduced_gaussian, tripolar, etc.
+
+    A grid type describes the method for distributing grid points over the sphere.
+    """
+
+    pass

esgvoc/api/data_descriptors/EMD_models/horizontal_computational_grid.py

@@ -0,0 +1,56 @@
+"""
+Horizontal computational grid description (EMD v1.0 Section 4.1.1).
+
+A model component's horizontal computational grid is composed of one or more
+horizontal subgrids, on which different sets of variables are calculated.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pydantic import Field, field_validator
+
+from esgvoc.api.data_descriptors.data_descriptor import DataDescriptor
+
+from .arrangement import Arrangement
+from .horizontal_subgrid import HorizontalSubgrid
+
+
+class HorizontalComputationalGrid(DataDescriptor):
+    """
+    Horizontal computational grid description (EMD v1.0 Section 4.1.1).
+
+    A model component's horizontal computational grid is composed of one or more
+    horizontal subgrids, on which different sets of variables are calculated.
+    When the computational grid relies on more than one subgrid, it is referred to
+    as a "staggered" grid. For most staggered grids, the velocity-related variables
+    are calculated on a subgrid offset from the mass-related variables (e.g. pressure,
+    temperature, water vapour and other mass constituents).
+    """
+
+    arrangement: str | Arrangement = Field(
+        description="A characterisation of the grid staggering defining the relative positions of computed "
+        "mass-related and velocity-related variables. Taken from 7.3 arrangement CV. "
+        "Options: 'arakawa_a', 'arakawa_b', 'arakawa_c', 'arakawa_d', 'arakawa_e'. "
+        "E.g. 'arakawa_c'"
+    )
+
+    horizontal_subgrids: List[HorizontalSubgrid] = Field(
+        description="All of the subgrids, of which there must be at least one, used to construct the "
+        "horizontal computational grid. Each subgrid is associated with one or more variable types "
+        "(mass-related, velocity-related, etc.), consistent with the arrangement property.",
+        min_length=1,
+    )
+
+    @field_validator("horizontal_subgrids")
+    @classmethod
+    def validate_at_least_one_subgrid(cls, v):
+        """Validate that there is at least one horizontal subgrid."""
+        if not v or len(v) < 1:
+            raise ValueError("At least one horizontal subgrid must be provided")
+        return v
+
+    def accept(self, visitor):
+        """Accept a data descriptor visitor."""
+        return visitor.visit_plain_term(self)

esgvoc/api/data_descriptors/EMD_models/horizontal_grid_cells.py

@@ -0,0 +1,230 @@
+"""
+Horizontal grid cells description (EMD v1.0 Section 4.1.3).
+
+Horizontal grid cells are described by a coordinate system, cell resolutions,
+as well as a number of other grid features.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+from esgvoc.api.data_descriptors.region import Region
+
+from .grid_mapping import GridMapping
+from .grid_type import GridType
+from .temporal_refinement import TemporalRefinement
+from .truncation_method import TruncationMethod
+
+
+class HorizontalGridCells(PlainTermDataDescriptor):
+    """
+    Horizontal grid cells description (EMD v1.0 Section 4.1.3).
+
+    Horizontal grid cells are described by a coordinate system, cell resolutions,
+    as well as a number of other grid features. The description does not include
+    any information on whether or not the grid cells form part of a model component's
+    computational grid, and so may be used to describe an arbitrary output grid.
+    """
+
+    region: Region | str = Field(
+        description="The geographical region, or regions, over which the component is simulated. "
+        "A region is a contiguous part of the Earth's surface, and may include areas for which "
+        "no calculations are made (such as ocean areas for a land surface component). "
+        "Taken from 7.5 region CV. E.g. 'global', 'antarctica', 'greenland', 'limited_area'"
+    )
+
+    grid_type: str | GridType = Field(
+        description="The horizontal grid type, i.e. the method of distributing grid cells over the region. "
+        "Taken from 7.6 grid_type CV. E.g. 'regular_latitude_longitude', 'tripolar'"
+    )
+
+    description: Optional[str] = Field(
+        default=None,
+        description="A description of the grid. A description is only required if there is information "
+        "that is not covered by any of the other properties. Omit when not required.",
+    )
+
+    grid_mapping: Optional[str | GridMapping] = Field(
+        default=None,
+        description="The name of the coordinate reference system of the horizontal coordinates. "
+        "Taken from 7.7 grid_mapping CV. E.g. 'latitude_longitude', 'lambert_conformal_conic'. "
+        "Can be None or empty for certain grid types (e.g., tripolar grids).",
+    )
+
+    temporal_refinement: str | TemporalRefinement = Field(
+        description="The grid temporal refinement, indicating how the distribution of grid cells varies with time. "
+        "Taken from 7.8 temporal_refinement CV. E.g. 'static'"
+    )
+
+    spatial_refinement: Optional[str] = Field(
+        default=None,
+        description="The grid spatial refinement, indicating how the distribution of grid cells varies with space. "
+        "NEW in EMD v1.0. Omit when not applicable.",
+    )
+
+    x_resolution: Optional[float] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The size of grid cells in the X direction.
+
+            Cells for which no calculations are made are included (such as ocean areas
+            for a land surface component).
+
+            The X direction for a grid defined by spherical polar coordinates is longitude.
+
+            The value's physical units are given by the horizontal_units property.
+
+            Report only when cell sizes are identical or else reasonably uniform (in their given units).
+            When cells sizes in the X direction are not identical, a representative value should be
+            provided and this fact noted in the description property.
+            If the cell sizes vary by more than 25%, set this to None.
+            """
+        ),
+        gt=0,
+    )
+
+    y_resolution: Optional[float] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The size of grid cells in the Y direction.
+
+            Cells for which no calculations are made are included (such as ocean areas
+            for a land surface component).
+
+            The Y direction for a grid defined by spherical polar coordinates is latitude.
+
+            The value's physical units are given by the horizontal_units property.
+
+            Report only when cell sizes are identical or else reasonably uniform (in their given units).
+            When cells sizes in the Y direction are not identical, a representative value should be
+            provided and this fact noted in the description property.
+            If the cell sizes vary by more than 25%, set this to None.
+            """
+        ),
+        gt=0,
+    )
+
+    horizontal_units: Optional[str] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The physical units of the x_resolution and y_resolution property values.
+
+            If x_resolution and y_resolution are None, set this to None.
+            """
+        ),
+    )
+
+    southernmost_latitude: Optional[float] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The southernmost grid cell latitude, in degrees north.
+
+            Cells for which no calculations are made are included.
+            The southernmost latitude may be shared by multiple cells.
+
+            If the southernmost latitude is not known (e.g. the grid is adaptive), use None.
+            """
+        ),
+        ge=-90.0,
+        le=90.0,
+    )
+
+    westernmost_longitude: Optional[float] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The westernmost grid cell longitude, in degrees east, of the southernmost grid cell(s).
+
+            Cells for which no calculations are made are included.
+            The westernmost longitude is the smallest longitude value of the cells
+            that share the latitude given by the southernmost_latitude.
+
+            If the westernmost longitude is not known (e.g. the grid is adaptive), use None.
+            """
+        ),
+        ge=0.0,
+        le=360.0,
+    )
+
+    n_cells: Optional[int] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The total number of cells in the horizontal grid.
+
+            If the total number of grid cells is not constant, set to None.
+            """
+        ),
+        ge=1,
+    )
+
+    truncation_method: Optional[str | TruncationMethod] = Field(
+        default=None,
+        description="The method for truncating the spherical harmonic representation of a spectral model "
+        "when reporting on this grid. If the grid is not used for reporting spherical harmonic "
+        "representations, set to None.",
+    )
+
+    truncation_number: Optional[int] = Field(
+        default=None,
+        description="The zonal (east-west) wave number at which a spectral model is truncated when "
+        "reporting on this grid. If the grid is not used for reporting spectral models, set to None.",
+    )
+
+    resolution_range_km: Optional[list[float]] = Field(
+        default=None,
+        description=textwrap.dedent(
+            """
+            The minimum and maximum resolution (in km) of cells of the horizontal grid.
+
+            Should be calculated according to the algorithm implemented by
+            https://github.com/PCMDI/nominal_resolution/blob/master/lib/api.py
+            You need to take the min and max of the array that is returned
+            when using the returnMaxDistance of the mean_resolution function.
+            """
+        ),
+        min_length=2,
+        max_length=2,
+    )
+
+    @field_validator("horizontal_units", mode="after")
+    @classmethod
+    def validate_horizontal_units(cls, v, info):
+        """Validate horizontal_units."""
+        resolution_fields = {"x_resolution", "y_resolution"}
+        has_resolution = any(info.data.get(field) is not None for field in resolution_fields)
+        if has_resolution:
+            if not v:
+                raise ValueError("horizontal_units is required when x_resolution or y_resolution are set")
+
+            allowed_values = {"km", "degree"}
+            if v not in allowed_values:
+                msg = f"horizontal_units must be one of {allowed_values}. Received: {v}"
+                raise ValueError(msg)
+        elif v:
+            msg = f"If all of {resolution_fields} are None, then horizontal_units must also be None. Received: {v}"
+            raise ValueError(msg)
+
+        return v
+
+    @field_validator("resolution_range_km")
+    @classmethod
+    def validate_resolution_range(cls, v):
+        """Validate that resolution range has exactly 2 values and min <= max."""
+        if v is not None:
+            if len(v) != 2:
+                raise ValueError("resolution_range_km must contain exactly 2 values [min, max]")
+            if v[0] > v[1]:
+                raise ValueError("resolution_range_km: minimum must be <= maximum")
+            if any(val <= 0 for val in v):
+                raise ValueError("resolution_range_km values must be > 0")
+        return v

esgvoc/api/data_descriptors/EMD_models/horizontal_subgrid.py

@@ -0,0 +1,41 @@
+"""
+Horizontal subgrid description (EMD v1.0 Section 4.1.2).
+
+A horizontal subgrid describes the grid cells at one of the stagger positions
+of a horizontal computational grid.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pydantic import BaseModel, Field
+
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+from .cell_variable_type import CellVariableType
+from .horizontal_grid_cells import HorizontalGridCells
+
+
+class HorizontalSubgrid(PlainTermDataDescriptor):
+    """
+    Horizontal subgrid description (EMD v1.0 Section 4.1.2).
+
+    A horizontal subgrid describes the grid cells at one of the stagger positions
+    of a horizontal computational grid. Often the locations of mass-related and
+    velocity-related variables differ, so more than one horizontal subgrid will
+    be defined as part of a horizontal computational grid.
+    """
+
+    cell_variable_type: List[str | CellVariableType] = Field(
+        description="The types of physical variables that are carried at, or representative of conditions at, "
+        "the cells described by this horizontal subgrid. Taken from 7.4 cell_variable_type CV. "
+        "Options: 'mass', 'x_velocity', 'y_velocity', 'velocity'. "
+        "E.g. ['mass'], ['x_velocity'], ['mass', 'x_velocity', 'y_velocity'], ['mass', 'velocity']. "
+        "Can be an empty list in certain cases.",
+        default_factory=list,
+    )
+
+    horizontal_grid_cells: HorizontalGridCells = Field(
+        description="A description of the characteristics and location of the grid cells of this subgrid."
+    )

esgvoc/api/data_descriptors/EMD_models/horizontal_units.py

@@ -0,0 +1,5 @@
+from esgvoc.api.data_descriptors.data_descriptor import PlainTermDataDescriptor
+
+
+class HorizontalUnits(PlainTermDataDescriptor):
+    pass