CCMC Kamodo

The CCMC Kamodo Analysis Suite

Online Documentation

https://nasa.github.io/Kamodo/

Vision Statement

Kamodo is an official NASA open-source python package built upon the functionalization of datasets. Once a dataset is functionalized in Kamodo, several important capabilities are then available to the user, including data analysis via function composition, automatic unit conversions, and publication quality graphics all using intuitive and simplistic syntax. By applying these capabilities to heliophysics model outputs, we aim to:

Drastically simplify the currently complex data utilization process for model outputs,
Provide interactive access to functionalized model outputs for users ranging in programming skill from beginners – via code-free interfaces and video tutorials – to advanced users – via thorough documentation, Jupyter notebook examples and sample workflows,
Layer multiple functionalities on top of the functionalized model outputs, all with model-agnostic and uniform syntax, including but not limited to:
- Flythrough tools,
- Vector field tracing (including magnetic field mapping),
- Coordinate conversions,
- Domain-specific interactive plots of publication quality,
- Modular driver swapping,
- Satellite constellation mission planning tools,
- Simulated imagery, and
- A line of sight calculation tool,
Greatly reduce the programming skill currently required outside of Kamodo to perform model validation studies and model-data comparisons,
Enable model output utilization both on the cloud and on personal laptops in a variety of methods (e.g. through HAPI and interactive calls from the command line),
Streamline the CCMC user workflow by becoming interoperable with other CCMC services (e.g. CAMEL and the various scoreboards),
And become the next generation interface for CCMC users to interact with and analyze model outputs (e.g. through ROR and IR),

...all while keeping the developed software open-source and freely available. The Kamodo team also supports the heliophysics community by pursuing interoperability with commonly-used python packages, collaborating with community members to add model outputs and new functionalities, and remaining involved with community events (e.g. conferences, challenges, and research support). As the library of supported model outputs types expands and new model-agnostic tools are added, Kamodo will become a staple software package in the heliophysics community to transform current workflows into a more efficient and productive process. We are building the next generation of capability with Kamodo. Join us!

Kamodo currently supports:

ADELPHI: AMPERE-Derived ELectrodynamic Properties of the High-latitude Ionosphere, https://doi.org/10.1029/2020SW002677
AMGeO: Assimilative Mapping of Geospace Observations, https://doi.org/10.5281/zenodo.3564914
CTIPe: Coupled Thermosphere Ionosphere Plasmasphere Electrodynamics Model, https://doi.org/10.1029/2007SW000364
DTM: The Drag Temperature Model, https://doi.org/10.1051/swsc/2015001
GITM: Global Ionosphere Thermosphere Model, https://doi.org/10.1016/j.jastp.2006.01.008
IRI: International Reference Ionosphere Model, https://doi.org/10.5194/ars-16-1-2018
OpenGGCM_GM: The Open Geospace General Circulation Model - GM outputs only, https://doi.org/10.1023/A:1014228230714
SuperDARN_uni: SuperDARN uniform grid output ,https://doi.org/10.1029/2010JA016017
SuperDARN_equ: SuperDARN equal area grid output, https://doi.org/10.1029/2010JA016017
SWMF_IE: Space Weather Modeling Framework - IE outputs, https://doi.org/10.1029/2006SW000272
SWMF_GM: Space Weather Modeling Framework - GM outputs, https://doi.org/10.1029/2006SW000272
TIEGCM: Thermosphere Ionosphere Electrodynamics General Circulation Model, https://doi.org/10.1029/2012GM001297
WACCMX: Whole Atmosphere Community Climate Model With Thermosphere and Ionosphere Extension, https://doi.org/10.1002/2017MS001232
WAMIPE: The coupled Whole Atmosphere Model - Ionosphere Plasmasphere Model, https://doi.org/10.1002/2015GL067312 and https://doi.org/10.1029/2022SW003193
Weimer: Weimer Ionosphere model, https://doi.org/10.1029/2005JA011270
It also supports any data available through the HAPI interface.

Kamodo Installation Instructions

Kamodo is built to run with at least 16 GB of RAM. Attempting to run Kamodo with less memory may result in errors.

Conda prompt commands:

Move to the directory where you want the Kamodo package to be stored or if you wish to create a new environment, use this command:

conda create -n Kamodo_env python=3.7

Add the packages needed by the CCMC readers to the desired environment (replace 'Kamodo_env' with your environment name):

conda install -n Kamodo_env -c conda-forge netCDF4 cdflib astropy ipython jupyter h5py sgp4

Activate the desired environment.

conda activate Kamodo_env

Install remaining dependencies:

python -m pip install --upgrade spacepy
python -m pip install hapiclient

Download CCMC Kamodo to the current directory:

git clone https://github.com/nasa/Kamodo.git

Install the CCMC Kamodo package. (Check the directory structure before using this command. The ./Kamodo directory should contain the kamodo_ccmc directory.)

python -m pip install ./Kamodo

Note: Developers should install CCMC Kamodo with the -e option

Testing commands from an ipython or notebook session

from kamodo import Kamodo
k = Kamodo()  
import kamodo_ccmc.flythrough.model_wrapper as MW  
MW.Model_Variables('OpenGGCM_GM')

The OpenGGCM_GM model accepts the standardized variable names listed below.
-----------------------------------------------------------------------------------
B_x : '['x component of magnetic field', 0, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'nT']'
B_y : '['y component of magnetic field', 1, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'nT']'
B_z : '['z component of magnetic field', 2, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'nT']'
E_x : '['x component of electric field', 6, 'GSE', 'car', ['time', 'x', 'x', 'x'], 'mV/m']'
E_y : '['y component of electric field', 7, 'GSE', 'car', ['time', 'y', 'y', 'y'], 'mV/m']'
E_z : '['z component of electric field', 8, 'GSE', 'car', ['time', 'z', 'z', 'z'], 'mV/m']'
N_plasma : '['number density of plasma (hydrogen equivalent)', 12, 'GSE', 'car', ['time', 'x', 'y', 'z'], '1/cm**3']'
P_plasma : '['plasma pressure', 14, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'pPa']'
eta : '['resistivity', 13, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'm**2/s']'
j_x : '['current density, x component', 15, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'muA/m**2']'
j_y : '['current density, y component', 16, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'muA/m**2']'
j_z : '['current density, z component', 17, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'muA/m**2']'
v_plasmax : '['x component of plasma velocity', 9, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'km/s']'
v_plasmay : '['y component of plasma velocity', 10, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'km/s']'
v_plasmaz : '['z component of plasma velocity', 11, 'GSE', 'car', ['time', 'x', 'y', 'z'], 'km/s']'

Citing Kamodo

When publishing research which used Kamodo, please provide appropriate credit to the CCMC and the Kamodo team via citation or acknowledgment. Please also let the team know of publications or presentations that use Kamodo. Below is list of publications for Kamodo.

Pembroke, A., D. De Zeeuw, L. Rastaetter, R. Ringuette, O. Gerland, D. Patel and M. Contreras (2022). Kamodo: A functional API for space weather models and data. JOSS 7, 75, 4053, https://doi.org/10.21105/joss.04053.
Ringuette, R., D. De Zeeuw, L. Rastaetter, A. Pembroke, O. Gerland, K. Garcia-Sage (2022). Kamodo’s model-agnostic satellite flythrough: Lowering the utilization barrier for heliophysics model outputs, Frontiers in Astronomy and Space Sciences, vol 9. http://dx.doi.org/10.3389/fspas.2022.1005977.
Ringuette, R., L. Rastaetter, D. De Zeeuw, K. Garcia-Sage, R. Robinson, and O. Gerland (2022). Kamodo's Satellite Constellation Mission Planning Tool, poster presentation presented by L. Rastaetter at the 2022 Fall meeting of AGU, Dec 12-16, Chicago, IL, USA. https://doi.org/10.22541/essoar.167214257.73153757/v1.
Ringuette, R., L. Rastaetter, D. De Zeeuw, A. Pembroke, and O. Gerland (2023). Simplifying model data access and utilization. Adv. Space. Res. under review.

Resources

CCMC's Kamodo Official website - https://ccmc.gsfc.nasa.gov/tools/kamodo/
CCMC's Kamodo Documentation page - https://nasa.github.io/Kamodo/
Sample model outputs - https://ccmc.gsfc.nasa.gov/RoR_WWW/output_files/KAMODO_DEMO/
Youtube tutorial channel - https://www.youtube.com/playlist?list=PLBWJQ5-pik_yBBcrpDRPM2hLluh-jreFa

The Kamodo team

Dr. Lutz Rastaetter

ORCiD: https://orcid.org/0000-0002-7343-4147
NASA Staff Page: https://ccmc.gsfc.nasa.gov/staff/lutz-rastaetter/

Dr. Darren De Zeeuw

ORCiD: https://orcid.org/0000-0002-4313-5998
NASA Staff Page: https://ccmc.gsfc.nasa.gov/staff/darren-de-zeeuw/

Dr. Katherine Garcia-Sage

ORCiD: https://orcid.org/0000-0001-6398-8755
NASA Staff Page: https://ccmc.gsfc.nasa.gov/staff/katherine-garcia-sage/

Open-Source License

Kamodo is an official NASA open source software package. Kamodo's official source code is hosted on github under a permissive NASA open source license: For more details, go here: https://github.com/nasa/Kamodo/blob/master/LICENSE

nasa / Kamodo

readme