Kamodo Quick Start¶
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
Test install 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']'
Other testing¶
Additional quick tests can be performed by running 'pytest' in the Kamodo root directory. Note that this will download some reduced size sample datasets that may still take significant time and disk space.
Plotly interactive plots¶
The default plotting built into Kamodo uses plotly. Plotly (https://plotly.com/python/) is an open-source interactive plotting library supporting a wide range of plotting options. It enables web-based visualizations that can be displayed in Jupyter notebooks, as well as exported to html, png, and pdf. Below is a self contained html file to visualize model output in 3D you can interact with.
from IPython.display import IFrame
IFrame(src='Files/GITM_3D_500km.html', width="100%", height="650")