# Field & Fieldset proposed changes to support xarray and uxarray natively

## The Field Class
The Field class holds scalar field data alongside associated grid information. The `Field` object is a wrapper around a `xarray.DataArray` or `uxarray.UxDataArray` object. Additionally, it holds a dynamic Callable procedure as an attribute (`Field.interp_method`) that is used to interpolate the field data. During initialization, the user can supply a custom interpolation method that is used to interpolate the field data, so long as the interpolation method has the correct signature.

### Public Attributes
* `name: str`
* (**New!**)`data: xr.DataArray | ux.UxDataArray`
* ~~`fieldtype: str | None = None` - ?? Carried over from previous `Field` class definition~~
* (**New!**) `interp_method: Callable | None = None`,
* `allow_time_extrapolation: bool | None = None`
* `igrid: int` - Integer used to index the `particle.ei` attribute. Helps relate the `particle.ei` index to a specific `Field`.
* (*Potentially remove*) `fieldset: FieldSet` - pointer to the parent `Fieldset` object
* `units: parcels.tools.converters.UnitConverter` - object for handling unit conversions

### Private Attributes

* `_parent_mesh` - a pointer to the `self.data.attributes["mesh"]` used as a quick reference to identify the parent model the data is associated with
* `_location` - a pointer to the `self.data.attributes["location"]` used as a quick reference to identify which pair of latitude,longitude mesh points the data values reside on.

### Public Functions

### Private Functions

### Schema requirements for `xarray.DataArray` and `uxarray.UxDatArray`
The `xarray.DataArray` or `uxarray.UxDataArray` object contains the field data (values) and associated metadata, including the dimensions, coordinates, and attributes.

For either object type, the dimensions are required to use the following naming convention

| Time | Depth | Latitude | Longitude |
| ---- | ----- | -------- | --------- |
| `time` | `nz1` or `nz` | `n_face`, `n_node` | `face_lon`, `node_lon`, or `edge_lon`|

This naming convention is adopted from the uxarray project and in the context of "dimensions" have the following meaning

* `nz1` - the number of vertical positions on the vertical face of a grid cell.
* `nz` - the number of vertical positions within a grid cell center. Note that`nz1 = nz+1`
* `face_lat` - the number of latitude positions at the center of a face
* `node_lat` - the number of latitude positions at a corner node of a face
* `edge_lat` - the number of latitude positions at an edge center of a face
* `face_lon` - the number of longitude positions at the center of a face
* `node_lon` - the number of longitude positions at a corner node of a face
* `edge_lon` - the number of longitude positions at an edge center of a face

For either object type, the coordinates are required to be defined

| Time | Depth | Latitude | Longitude |
| ---- | ----- | -------- | --------- |
| `time` | `nz1` or `nz` | `face_lat`, `node_lat`, or `edge_lat` | `face_lon`, `node_lon`, or `edge_lon`|

For either object type, the following attributes are required

* `location` - This is a string that indicates which point type in the mesh the data array is associated with. On unstructured grids, this is either `node`,`edge`, or `face`. On structured grids this is either `node`, `x_edge`, `y_edge`, or `face`.
* `mesh` - This is a string that indicates the mesh type or parent model the field data is associated with. Note that this attribute name is chosen due to the naming convention used in `uxarray`
* `mesh_type` - This must be set to either "spherical" or "flat". This is meant to replace the `Field.grid.mesh` attribute.

#### Variable names for Velocity components

When specifying the velocity fields through `uxarray.UxDataset` or `xarray.Dataset` objects, the `UxDataArray` or `xarray.DataArray` objects for the velocity field components must match the following :

| Data Array Name | Name explained | Field Description |
| --------------- | -------------- | ----------------- |
|`u` | Lower case letter "u" | Zonal/x-component of velocity |
|`v` | Lower case letter "v" | Meridional/y-component of velocity |
|`w` | Lower case letter "w" | Vertical/z-component of velocity |

#### Xarray Schema Requirements
When using a xarray.DataArray object,
* The `xarray.DataArray` object must have the `location` and `mesh` attributes set.
* The `location` attribute must be set to one of the following to define which pairing of points a field is associated with:
* `node`
* `face`
* `x_edge`
* `y_edge`
* For an Arakawa A-Grid, the `location` attribute must be set to / is assumed to be`node` (`node_lat`,`node_lon`) and data values are registered to the corner nodes of elements in a mesh.
* For an Arakawa B-Grid, the `location` setting for a field has the following interpretation:
* XX
* For a C-Grid, the `location` setting for a field has the following interpretation:
* `node` - the field is associated with the vorticity points (`node_lat, node_lon`)
* `face` - the field is associated with the tracer points (`face_lat, face_lon`)
* `x_edge` - the field is associated with the u-velocity points (`face_lat, node_lon`)
* `y_edge` - the field is associated with the v-velocity points (`node_lat, face_lon`)

* For all structured grid types,
* `*_lat` and `*_lon` dimensions can be 1-D or 2-D (Curvilinear)

#### UXArray Schema Requirements

When using a `uxarray.UxDataArray` object,
* The `uxarray.UxDataArray.UxGrid` object must have the `Conventions` attribute set to "UGRID-1.0" and the `uxarray.UxDataArray` object must comply with the [UGRID conventions](https://ugrid-conventions.github.io/ugrid-conventions/).