ugants package#

UG-ANTS: A library for generating ancillary files targeting unstructured grids.

Subpackages#

Submodules#

ugants.abc module#

Abstract base classes for UG-ANTS.

class ugants.abc.Application(*args, **kwargs)[source]#

Bases: ABC

Abstract base class for creating UG-ANTS applications.

The Application base class provides a common interface for writing applications for generating unstructured grid ancillaries, providing functionality common to most applications:

A standardised command line interface is automatically generated from the application signature
Load and save methods are provided by the base class. These are intended to provide a sensible default, but can be overridden in specific applications if necessary.

The __init__() and run() methods must be provided when subclassing Application. See the documentation for these methods for more detail.

results: CubeList = None#: A CubeList containing the results from running the application. This attribute is set when the run() method is called.

output: str = None#: Filepath to which the results will be written upon calling save(). If the application has been instantiated using the from_command_line() method, then this attribute will be set to the output command line argument.

abstract __init__(*args, **kwargs)[source]#

Initialise an instance of the class.

Subclasses of Application must provide an __init__ method.

The __init__ must be appropriately type hinted in order for the command line argument parser to be constructed correctly.

For example:

from iris.cube import CubeList

class ApplicationClass:
    def __init__(self, source: CubeList, scheme: str, number: int = 0):
        self.source = source
        self.scheme = scheme
        self.number = number

See also

from_command_line(): for more information about how the type hints are used to construct the command line argument parser.

abstract run()[source]#

Run the application.

Subclasses of ugants.abc.Application must provide a run method.

This method should make use of the inputs specified in the __init__() method, and assign the results CubeList to results.

save()[source]#

Save results to UGrid netcdf.

Saves the results to the file location specfied by output.

results should be set by running run().
output should have been set from the command line, if the application instance has been created using the from_command_line() method, or by explicitly setting output on the application instance.

Raises:

ValueError – If no output file location is specified at output.
ValueError – If no results are specified at results.

classmethod from_command_line(args: Sequence[str] | None = None)[source]#

Create an application instance from the command line.

The parameter names and type hints from the __init__ method are used to construct a command line argument parser. The command line arguments are then parsed and passed to the __init__ method to create an instance of the class. An output command line argument is also added, which is mapped to the output attribute when instantiating an application via the from_command_line() method.

Returns:: An instance of the class initialised with the command line arguments.

Notes

Some parameter type hints have special effects on how the parser is constructed and the class instantiated:

Type hint	Interpretation
`CubeList`	Add a command line positional argument representing the path to the UGrid data to be loaded. The loaded data will be passed to the `__init__` method to create an instance of the class. For example, `source_data: CubeList` adds a positional command line argument `source_data`.
`Mesh`	Add command line arguments representing the path to the mesh file to be loaded and the name of the mesh to extract. The loaded mesh will be passed to the `__init__` method to create an instance of the class. For example, `target_mesh: Mesh` adds two command line arguments: `--target-mesh` (the path to the mesh file) and `--target-mesh-name` (the name of the mesh to extract).
`typing.Literal`	Add a command line argument with a limited set of choices. For example, `regrid_scheme: Literal["conservative", "bilinear"]` adds a command line argument `--regrid-scheme` with choices `{conservative, bilinear}`.
`bool`	Add a command line flag that stores True if provided, or False if not provided. For example, `a_flag: bool` adds a command line flag `--a-flag` which sets `a_flag` to True if provided, or False if not provided.
Parameter with default argument	Add an optional command line argument with a default value. For example, `number: int = 0` adds an optional command line argument `--number` with default value `0`.

ugants.exceptions module#

Exceptions specific to UG-ANTS.

exception ugants.exceptions.ProvisionalWarning[source]#

Bases: UserWarning

A warning to inform users that results are provisional.