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.

Simple Installation (Recommended)

For most users, a simple pip install will work:

pip install kamodo-ccmc

System Requirements:

• Python >= 3.10
• At least 16 GB RAM
• C compiler (gcc on Linux/Mac, MSVC on Windows) for compiling C extensions
  • SWMF-GM reader requires OCTREE_BLOCK_GRID C extension
  • GAMER-AM reader requires Tri2D C extension
• Fortran compiler (gfortran) for OpenGGCM reader (optional)

Note: If you don't have a C compiler installed, kamodo-ccmc will still install successfully, but SWMF-GM and GAMER-AM model readers will be unavailable. Other model readers will work normally. You'll see warnings during installation about which readers are unavailable.

Installation from Source (Developers)

For development or to get the latest version:

# Clone the repository
git clone https://github.com/nasa/Kamodo.git
cd Kamodo

# Option 1: Regular install (extensions auto-compiled)
pip install .

# Option 2: Editable install (recommended for active development)
# NOTE: With modern setuptools (64+), editable installs require a manual build step
python setup.py build_ext --inplace
pip install -e . --no-build-isolation

About editable installs: Due to PEP 660 changes in setuptools 64+, custom build commands (like our C/Fortran compilation) don't run automatically in editable mode. You must build extensions explicitly first with python setup.py build_ext --inplace.

After code changes: If you modify any C/Fortran source files during development, re-run:

python setup.py build_ext --inplace --force

Installing Compilers

Linux (Ubuntu/Debian):

sudo apt-get install gcc gfortran

macOS:

# Install Xcode Command Line Tools
xcode-select --install

# Install gfortran (optional, for OpenGGCM)
brew install gcc

Windows:

# Install mingw-w64 via conda
conda install -c conda-forge m2w64-gcc-fortran libpython

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. Darren De Zeeuw

• ORCiD: https://orcid.org/0000-0002-4313-5998
• NASA Staff Page: https://science.gsfc.nasa.gov/sci/bio/darren.dezeeuw

Dr. Lutz Rastaetter

• ORCiD: https://orcid.org/0000-0002-7343-4147
• NASA Staff Page: https://science.gsfc.nasa.gov/sci/bio/lutz.rastaetter-1

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