Data

Tools

Indexes

Applications

Experiments

Open Source Science

jaxparrow

A package for computing the inversion of the cyclogeostrophic balance based on a variational formulation approach, using JAX.

https://github.com/meom-group/jaxparrow

Science Score: 67.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ✓
    CITATION.cff file
    Found CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 6 DOI reference(s) in README
  • ✓
    Academic publication links
    Links to: zenodo.org
  • ○
    Academic email domains
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (14.4%) to scientific vocabulary

Keywords

cyclogeostrophy eddy flow geostrophy jax swirl velocity
Last synced: 6 months ago · JSON representation ·

Repository

A package for computing the inversion of the cyclogeostrophic balance based on a variational formulation approach, using JAX.

Basic Info
Statistics
  • Stars: 8
  • Watchers: 4
  • Forks: 1
  • Open Issues: 4
  • Releases: 13
Topics
cyclogeostrophy eddy flow geostrophy jax swirl velocity
Created over 2 years ago · Last pushed 7 months ago
Metadata Files
Readme Contributing License Citation

README.md

jaxparrow

Python PyPi Tests Docs DOI

jaxparrow implements a novel approach based on a variational formulation to compute the inversion of the cyclogeostrophic balance.

It leverages the power of JAX, to efficiently solve the inversion as an optimization problem. Given the Sea Surface Height (SSH) field of an ocean system, jaxparrow estimates the velocity field that best satisfies the cyclogeostrophic balance.

See the full documentation!

Installation

jaxparrow is Pip-installable: shell pip install jaxparrow

However, users with access to GPUs or TPUs should first install JAX separately in order to fully benefit from its high-performance computing capacities. See JAX instructions. \ By default, jaxparrow will install a CPU-only version of JAX if no other version is already present in the Python environment.

Usage

As a package

The function you are most probably looking for is cyclogeostrophy. It computes the cyclogeostrophic velocity field (returned as two 2darray) from: - a SSH field (a 2darray), - the latitude and longitude grids at the T points (two 2darray).

In a Python script, assuming that the input grids have already been initialised / imported, estimating the cyclogeostrophic velocities for a single timestamp would resort to:

```python from jaxparrow import cyclogeostrophy

ucyclo2d, vcyclo2d = cyclogeostrophy(ssh2d, lat2d, lon_2d) ```

Because jaxparrow uses C-grids the velocity fields are represented on two grids (U and V), and the tracer fields (such as SSH) on one grid (T). \ We provide functions computing some kinematics (such as velocities magnitude, normalized relative vorticity, or kinematic energy) accounting for these gridding system:

```python from jaxparrow.tools.kinematics import magnitude

uvcyclo2d, vcyclo2d = magnitude(ucyclo2d, vcyclo2d, interpolate=True) ```

To vectorise the estimation of the cyclogeostrophy across a first time dimension, one aims to use jax.vmap.

```python import jax

vmapcyclogeostrophy = jax.vmap(cyclogeostrophy, inaxes=(0, None, None)) ucyclo3d, vcyclo3d = vmapcyclogeostrophy(ssh3d, lat2d, lon2d) ```

By default, the cyclogeostrophy function relies on our variational method. Its method argument provides the ability to use an iterative method instead, either the one described by Penven et al., or the one by Ioannou et al.. Additional arguments also give a finer control over the three approaches hyperparameters. \ See jaxparrow API documentation for more details.

Notebooks are available as step-by-step examples.

As an executable

jaxparrow is also available from the command line: shell jaxparrow --conf_path conf.yml The YAML configuration file conf.yml instruct where input netCDF files are locally stored, and how to retrieve variables and coordinates from them. It also provides the path of the output netCDF file. Optionally, it can specify which cyclogeostrophic approach should be applied and its hyperparameters.

An example configuration file detailing all the required and optional entries can be found here.

Contributing

Contributions of all sorts are welcomed! See CONTRIBUTING.md and CONDUCT.md to get started.

How to cite

If you use this software, please cite it as specified in CITATION.cff. Thank you!

Owner

  • Name: MEOM Research Group
  • Login: meom-group
  • Kind: organization
  • Location: Grenoble, France

Data-driven computational oceanography

Citation (CITATION.cff) 

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: "Bertrand"
    given-names: "Vadim"
  - family-names: "E V Z De Almeida"
    given-names: "Victor"
  - family-names: "Le Sommer"
    given-names: "Julien"
  - family-names: "Cosme"
    given-names: "Emmanuel"
title: "jaxparrow"
version: 0.2.3
doi: 10.5281/zenodo.13886070
date-released: 2024-08-23
url: "https://github.com/meom-group/jaxparrow"

GitHub Events

Total
  • Create event: 2
  • Release event: 1
  • Issues event: 2
  • Watch event: 1
  • Issue comment event: 2
  • Push event: 8
  • Pull request event: 5
Last Year
  • Create event: 2
  • Release event: 1
  • Issues event: 2
  • Watch event: 1
  • Issue comment event: 2
  • Push event: 8
  • Pull request event: 5

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 0
  • Total pull requests: 2
  • Average time to close issues: N/A
  • Average time to close pull requests: 5 minutes
  • Total issue authors: 0
  • Total pull request authors: 1
  • Average comments per issue: 0
  • Average comments per pull request: 0.0
  • Merged pull requests: 2
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 0
  • Pull requests: 2
  • Average time to close issues: N/A
  • Average time to close pull requests: 5 minutes
  • Issue authors: 0
  • Pull request authors: 1
  • Average comments per issue: 0
  • Average comments per pull request: 0.0
  • Merged pull requests: 2
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • vadmbertr (6)
  • rcaneill (4)
  • lesommer (1)
  • AnthonyBosse (1)
  • weisslisa (1)
Pull Request Authors
  • vadmbertr (27)
Top Labels
Issue Labels
enhancement (4) bug (1) documentation (1)
Pull Request Labels

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 125 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 0
  • Total versions: 13
  • Total maintainers: 1
pypi.org: jaxparrow

Computes the inversion of the cyclogeostrophic balance based on a variational formulation approach, using JAX

  • Versions: 13
  • Dependent Packages: 0
  • Dependent Repositories: 0
  • Downloads: 125 Last month
Rankings
Dependent packages count: 9.8%
Forks count: 29.9%
Average: 36.6%
Stargazers count: 38.9%
Dependent repos count: 67.8%
Maintainers (1)
vadimb
Last synced: 6 months ago

Dependencies

.github/workflows/python-documentation.yml actions
  • actions/checkout v4 composite
  • actions/setup-python v4 composite
.github/workflows/python-package.yml actions
  • actions/checkout v4 composite
  • actions/setup-python v4 composite
.github/workflows/python-publish.yml actions
  • actions/checkout v4 composite
  • actions/setup-python v4 composite
  • pypa/gh-action-pypi-publish release/v1 composite
docs/requirements.txt pypi
  • myst_parser *
  • sphinx *
  • sphinx-rtd-theme *
pyproject.toml pypi
  • jax *
  • jaxlib *
  • jaxtyping *
  • netCDF4 *
  • numpy *
  • optax *
  • pyyaml *
  • tqdm *
  • xarray *