4. Command Line Interface

Once planetMagFields is installed, the magfield command is available directly from the terminal without writing any Python code.

magfield --help

4.1. Basic usage

Plot the surface magnetic field of Earth (default):

magfield

Plot Jupiter’s field at 85 % of its radius using a different colormap:

magfield -p jupiter -r 0.85 -c viridis

Plot all planets at once:

magfield -p all

Save a plot to a file instead of opening an interactive window:

magfield -p saturn -s saturn_field.png

Compute field components along a spacecraft trajectory (outputs CSV to stdout):

magfield -p saturn --trajectory orbit.csv

Same but save the result to a file:

magfield -p saturn --trajectory orbit.csv -s orbit_field.csv

4.2. Full option reference

4.2.1. Planet Selection

-p <name>, --planet <name>

Planet to plot. Use all to plot every planet on one figure. (default: earth)

-o <model>, --model <model>

Magnetic field model to use. Uses the latest available model when omitted. Available models can be listed with get_models().

4.2.2. Data Options

-r <value>, --radius <value>

Radial level at which to evaluate the field, scaled to the planetary radius. Must be positive. (default: 1.0)

-u <unit>, --unit <unit>

Unit for the magnetic field values. Accepted values: muT, nT, Gauss. (default: muT)

--trajectory <file>

Path to a CSV file with columns r, theta, phi (co-latitude and longitude both in radians). When supplied, the CLI switches to trajectory mode: it computes Br, Btheta and Bphi along the path using Planet.orbit_path instead of producing a map plot.

Output is a CSV written to stdout, or to the file given by --save if that flag is also provided.

Note

orbit_path uses the SHTns library when available and falls back to SciPy otherwise. Install the optional potextra extra for best performance: pip install planetMagFields[potextra]

Example trajectory file (orbit.csv):

r,theta,phi
17.829,1.1865,4.7087
17.821,1.1863,4.7088
17.813,1.1861,4.7090

4.2.3. Plot Options

--dark

Use a dark background style for the figure.

-c <name>, --cmap <name>

Matplotlib colormap name. (default: RdBu_r)

-l <n>, --levels <n>

Number of contour levels. (default: 20)

-m <projection>, --mapproj <projection>

Map projection. See Projections for supported values. (default: Mollweide)

--vmin <value>

Fix the lower bound of the colorscale.

--vmax <value>

Fix the upper bound of the colorscale.

4.2.4. Output Options

-s <file>, --save <file>

Save the figure to file (e.g. field.png) instead of opening an interactive window. The parent directory is created automatically if needed.

-v, --verbose

Print debug-level information during execution.

--config <file>

Path to a JSON configuration file (see Config file below). Defaults to the config.json bundled with the package.

--version

Print the version number and exit.

4.3. Configuration file

All options can be set in a JSON file so you do not have to repeat long command lines. Values in the config file act as defaults; any flag supplied on the command line still takes precedence.

Pass a custom config file with --config:

magfield --config /path/to/myconfig.json

An example configuration file (matching the bundled planetmagfields/config.json):

{
    "_comment": "Copy and edit this file, then pass it with --config",

    "planet": "earth",
    "model": null,

    "r": 1.0,
    "unit": "muT",

    "cmap": "RdBu_r",
    "levels": 20,
    "proj": "Mollweide",
    "vmin": null,
    "vmax": null,

    "dark": false,
    "save_path": null,
    "verbose": false,
    "trajectory": null
}

Keys beginning with _ are treated as comments and ignored. Unknown keys produce a warning. null values leave the corresponding option at its built-in default.