kamodo 23.3.0

A functional api for scientific data

Kamodo

Kamodo originated as a CCMC tool for access, interpolation, and visualization of space weather models and data in python. Kamodo allows model developers to represent simulation results as mathematical functions which may be manipulated directly by end users. This general approach allows observational data to be represented functionally, through the use of interpolators. Kamodo handles unit conversion transparently and supports interactive science discovery in a low coding environment through jupyter notebooks. These features allow Kamodo to be used in other fields of study and as a teaching tool for working with real world physical data.

This repository hosts the core Kamodo libraries under a permissive NASA open source license. The core library supports function registration, composition, unit conversion, automated plotting, LaTeX I/O, and remote procedure call (RPC) interfaces.

Space weather simulation readers are implemented as subclasses of the Kamodo base class and are developed and maintained by the Community Coordinated Modeling Center, located at NASA Goddard Space Flight Center. CCMC's Kamodo readers may be found here https://ccmc.gsfc.nasa.gov/Kamodo/

Usage

Suppose we have a vector field defined by a function of positions in the x-y plane:

from kamodo import kamodofy
import numpy as np

x = np.linspace(-np.pi, np.pi, 25)
y = np.linspace(-np.pi, np.pi, 30)
xx, yy = np.meshgrid(x,y)
points = np.array(list(zip(xx.ravel(), yy.ravel())))

@kamodofy(units = 'km/s')
def fvec(rvec = points):
    ux = np.sin(rvec[:,0])
    uy = np.cos(rvec[:,1])
    return np.vstack((ux,uy)).T

The @kamodofy decorator lets us register this field with units to enable unit-conversion downstream:

from kamodo import Kamodo

kamodo = Kamodo(fvec = fvec)
kamodo

When run in a jupyter notebook, the above kamodo object will render as a set of equations:

$$\vec{f}{\left (\vec{r} \right )} [km/s] = \lambda{\left (\vec{r} \right )}$$

We can now evaluate our function using dot notation:

kamodo.fvec(np.array([[-1,1]]))

array([[-0.84147098,  0.54030231]])

We can perform unit conversion by function composition:

kamodo['gvec[m/s]'] = 'fvec'

kamodo automatically generates the appropriate multiplicative factors: $$\vec{g}{\left (\vec{r} \right )} [m/s] = 1000 \vec{f}{\left (\vec{r} \right )}$$ we can verify these results through evaluation

kamodo.gvec(np.array([[-1,1]]))

array([[-841.47098481,  540.30230587]])

Kamodo also generates quick-look graphics via function inspection.

import plotly.io as pio

fig = kamodo.plot('fvec')
pio.write_image(fig, 'images/fig2d-usage.svg')

Head over to the Introduction page for more details.

Getting started

Kamodo may be installed from pip

pip install kamodo

Kamodo is now maintained by Ensemble Government Services. To get the latest version, install from the Ensemble git repo:

pip install git+https://github.com/EnsembleGovServices/kamodo-core.git

Kamodo Environment

We strongly recommend using the conda environment system to avoid library conflicts with your host machine's python.

Download and install miniconda from here. The advantage to using miniconda is that each new environment includes the bare-minimum for a project. This allows you to keep many different projects on a single work station.

Create Kamodo environment

Create a new environment for kamodo

conda create -n kamodo python=3.7
conda activate kamodo
(kamodo) pip install kamodo

!!! note The leading (kamodo) in your prompt indicates that you have activated the kamodo environment. From here on, anything you install will be isolated to the kamodo environment.

Loading example notebooks

If you want to run any of the notebooks in docs, you will need to install jupyter:

(kamodo) conda install jupyter

Navigate to the top-level of the kamodo repo, then point jupyter to docs/notebooks:

(kamodo) jupyter notebook docs/notebooks

This should open a browser window that will allow you to load any of the example notebooks.

Requirements

The following (minimum) requirements are obtained by running pip install kamodo

• decorator>=4.4.2
• numpy
• scipy
• sympy==1.5.1
• pandas
• plotly
• pytest
• hydra-core==0.11.3
• Flask==1.1.2
• flask-cors
• flask-restful==0.3.8
• antlr4-python3-runtime==4.7
• python-forge
• requests
• incremental
• pycapnp
• pyOpenSSL

The antlr package may be necessary for rendering latex in a notebook

conda install antlr-python-runtime

Plotly-orca may be needed for proper image export

conda install -c plotly plotly-orca (for writing images)

!!! note plotly version in flux

Test Suite

Kamodo's unit tests are run with pytest. To install pytest with code coverage

python -m pip install flake8 pytest
pip install pytest-cov

Then, from the base of the git repo:

pytest --cov kamodo.kamodo --cov kamodo.util --cov plotting kamodo/test_plotting.py kamodo/test_kamodo.py kamodo/test_utils.py

This will generate a test report and coverage of the kamodo module.

To run RPC tests, you must first generate a self-signed certificate.

python kamodo/rpc/gen_self_signed_cert.py certfile
# certfile.key and certfile.cert will be placed in your local directory
pytest kamodo/rpc/test_rpc_threaded.py