abstract: JaxoDraw is a Feynman graph plotting tool written in Java. It has a complete graphical user interface that allows all actions to be carried out via mouse click-and-drag operations in a WYSIWYG fashion. Graphs may be exported to postscript/EPS format and can be saved in XML files to be used in later sessions. One of the main features of JaxoDraw is the possibility to produce LaTeX code that may be used to generate graphics output, thus combining the powers of TeX/LaTeX with those of a modern day drawing program. With JaxoDraw it becomes possible to draw even complicated Feynman diagrams with just a few mouse clicks, without the knowledge of any programming language.
author: D. Binosi and L. Theußl
Departamento de Fı́sica Teórica, Universidad de Valencia,
E-46100 Burjassot (Valencia), Spain
date: September 1, 2003
title:
  .
  JaxoDraw:
  A graphical user interface for drawing Feynman diagrams

# Introduction

It is a widely accepted convention today in the scientific community to write scientific papers using the TeX and LaTeX environments. The high quality, publication-style typesetting of LaTeX has made it now a de facto standard, to such an extent that some scientific journals only accept submission of papers in electronic form anymore. The portability goal of TeX  has however the drawback that graphical representations are only possible in very rudimentary form (using the LaTeX `picture` environment or packages using a similar approach). Useful as they are, mostly they are too simple to draw complicated Feynman diagrams as needed in wide parts of theoretical nuclear and particle physics today.

This problem has led to the development of more sophisticated programs in the past. The http://www.tex.ac.uk/cgi-bin/texfaq2html?label=drawFeyn lists four possibilities to draw Feynman diagrams in conjunction with LaTeX: Michael Levine's `feynman`  bundle; Jos Vermaseren's `axodraw`  package which uses PostScript specials and is thus slightly less portable but much more powerful; Thorsten Ohl's `feynmf`  package for LaTeX2e which uses `METAFONT` (or `MetaPost`) to combine flexibility and portability; and Norman Gray's package. These are all available from the archives.

Powerful as they are, all these methods have the common drawback that they require some 'hard-coding' from the user side, there does not exist any graphical user interface while modern day drawing programs do not include special options that are necessary to draw Feynman diagrams with the same quality as the one achieved by TeX/LaTeX.

Our program JaxoDraw is an attempt to close that gap. As the name suggests, it was initially meant to be a graphical user interface for Jos Vermaseren's `axodraw` package, but it may be used independently of it. However, it is in conjunction with `axodraw` that JaxoDraw develops its main capabilities because of the possibility to combine the powers of TeX/LaTeX with a modern drawing program. The main design goal of JaxoDraw was convenience and ease-of-use; it should be possible for anybody to draw even complicated Feynman diagrams with just a few mouse clicks, without the knowledge of any programming language. JaxoDraw was written in Java, which means that (in principle) it can be used on any platform where a Java Runtime Environment is installed. This makes it completely portable, even though in the present version, the program includes the execution of some external commands that are inherently system dependent and currently only work under certain operating systems.

This paper attempts to give a complete overview of JaxoDraw from installation and usage instructions to documentation issues and possible developments.

## Overview

JaxoDraw is a Feynman graph plotting tool written in Java. It has a complete graphical user interface that allows all actions to be carried out via mouse point-and-click-and-drag operations. Graphs may be exported to postscript / EPS format and can be saved in XML files to be used for later sessions. One of JaxoDraw's main features is the possibility to create LaTeX files which make use of J. Vermaseren's `axodraw` package to create a Feynman diagram via `latex` and `dvips`. It was in fact the main motivation to write JaxoDraw, to create a graphical user interface for the `axodraw` package.

A few of JaxoDraw's main features are:

-   Complete point-and-click graphical user interface.

-   Pre-defined line styles for common particle representations.

-   Saving and reading of sessions in XML format.

-   Export to Postscript, EPS and LaTeXformat.

-   Setting of permanent preferences.

The home of JaxoDraw sources and documentation is:

`http://altair.ific.uv.es/~JaxoDraw/home.html`,

please refer to this page for (hopefully) up to date information.
There is also a direct link to the JaxoDraw home page in the web page of the Physics Department of the University of Valencia:

## Installation

You may download JaxoDraw in three different forms (`xxx` denotes the version number and platform type):

|  |  |  |
|:---|:--:|:---|
| `JaxoDraw-xxx-src.tar.gz` | : | A gzipped tar file ($\sim$`<!-- -->`{=html}0.4 Mb) containing the JaxoDraw sources |
| `JaxoDraw-xxx-bin.tar.gz` | : | A gzipped tar file ($\sim$`<!-- -->`{=html}0.6 Mb) containing precompiled binaries |
| `JaxoDraw-xxx-jre.tar.gz` | : | A gzipped tar file ($\sim$`<!-- -->`{=html}22 Mb) containing precompiled binaries and a Java Runtime Environment |

If you have a Java Developer Kit installed on your system and you want to compile JaxoDraw yourself from sources, you may download the `src.tar.gz` file above. Check the prerequisites section  and the compiling from sources section  below.

If you have a Java Runtime Environment installed on your system (or a Developer Kit which includes the Runtime Environment), you may download the `bin.tar.gz` file. Check the prerequisites section  and section  for information on how to start the program.

If you don't have Java installed or you are not sure about it, you should get the `jre.tar.gz` file. This one contains a complete Java Runtime Environment (`jre`) so you won't need anything else anymore to run JaxoDraw. Note however the larger size of this last file. Check section  for information on how to start the program.

### Prerequisites

**Note:** The following paragraph about the Java environment only applies if you downloaded either the source code `src.tar.gz` or precompiled binaries `bin.tar.gz`. The `jre` version of JaxoDraw includes a Java Runtime Environment, just make sure then that you have enough disc space and memory to run Java programs (a minimum of 128Mb RAM is recommended).

Compilation and execution of JaxoDraw requires an installed and configured Java environment on your system. To execute JaxoDraw you need a Java Runtime Environment (`jre`), while for compilation you need the Java Developer Kit (`jdk`, which includes the `jre`). The program was written with the SUN J2SDK developer kit, version `1.4.1_01`, using the SUN `javac` compiler. We do not guarantee that the program compiles or runs with any earlier version or any other compiler (but we would like to hear from people who have succeeded to compile and run it on different systems). The Java Developer Kit and Runtime Environment are free software and may be obtained from . Please refer to SUN's Java pages for information on how to install and configure the Java environment on your system.

In order to profit from the LaTeX export file format, you need (apart from a working LaTeX distribution, we use TeTeX 1.0.7) J. Vermaseren's package. This is now distributed along with JaxoDraw (with kind permission of the author) but you have to install `axodraw` on your system independently of JaxoDraw as described in appendix . Please refer to the `axodraw` user guide for documentation on the package.

**Note**: If you have already an `axodraw.sty` installed on your system, make sure to have a recent version (as the one included in the downloads). Earlier versions did not include some color macros that are necessary for the use with JaxoDraw (see the Bugs section ).

If you want to use the postscript preview option of JaxoDraw, you need to specify an external postscript viewer.

### Unpacking the archives

Any of the packages available for download are unpacked with the command

`tar -zxf JaxoDraw-xxx-zzz.tar.gz `

under Linux or with the `unzip` utility under Windows. Here `xxx` is the version number and `zzz` is either `src`, `bin` or `jre`. This will create a directory named `JaxoDraw-xxx` (the JaxoDraw home directory) in the current directory. For the `src` distribution the JaxoDraw home directory has the following structure:

|                   |                                       |
|:------------------|:--------------------------------------|
| `src/`            | Source Files                          |
| `JaxoDraw/`       | Binaries                              |
| `JaxoDraw/icons/` | Icons                                 |
| `JaxoDraw/doc/`   | Documentation (User guide, man pages) |
| `javadoc/`        | API Specification                     |

where the `JaxoDraw/` and `javadoc/` directories contain no regular files in the beginning. There are a number of files, like `README`, `BUGS`, etc., and some bash shell scripts that may be used to compile and run the program (see below).

The binary `bin` distribution does not contain any sub-directories but includes an executable `.jar` file in the JaxoDraw home directory. Also, with respect to the `src` distribution there are a few files missing that are only required for compilation/documentation issues.

The `jre` distribution has the same structure as the `bin` distribution but there is an additional directory `j2re1.4.1_03` (under Linux) or an executable `j2re-1_4_1_03-windows-i586.exe` (under Windows) containing the Java Runtime Environment.

### Compiling the sources

If you have downloaded the source distribution of JaxoDraw, the `JaxoDraw/` and `javadoc/` directories in the JaxoDraw home directory will contain no regular files in the beginning. Under Linux, you compile the sources with

`javac -d . src/*.java `

This creates the binary `.class` files in the `JaxoDraw/` sub-directory. In order to create an executable `.jar` file, issue the command

`jar -cmf mainclass JaxoDraw.jar JaxoDraw/`

This creates an executable `JaxoDraw.jar` file in the JaxoDraw home directory.

Under Windows, the procedure is basically the same as above, just replace the Unix file separator `/` by the one of Windows: $\backslash$, and you may have to give the absolute path to the `javac` and `jar` executables.

### Creating the javadoc API specification

**Note:** This is only needed if you are interested in the structure of the JaxoDraw source code, it is not required in order to run the program.

To create javadoc:

`javadoc -d javadoc/ [-link Java-API] -link . src/*.java`

where the optional `Java-API` could be `http://java.sun.com/j2se/1.4/docs/api` to link against the online Java documentation from SUN, or a local directory if the javadoc is installed locally, for instance:

`javadoc -d javadoc/ -link /usr/java/j2sdk1.4.1_01/docs/api/ -link . src/*.java`

In any case, the command has to be run twice in order to get the cross-references right. This will create the javadoc API specification in the `javadoc/` sub-directory.

### Running the program

If you compiled the package yourself from sources (see sect.  above), you can start JaxoDraw with the command line

`java JaxoDraw/JaxoDraw`

in the distribution home directory, or by

`java -jar JaxoDraw.jar`

if you want to use the binary `.jar` file.

If you downloaded the precompiled binary distribution (`.bin`), just type

`java -jar JaxoDraw.jar`

or under Windows simply double click on the `jar` file icon.

If you downloaded the `.jre` distribution and you are using Linux, you have to give the path to the java executable in the j2re directory, typically:

`./j2re1.4.1_03/bin/java -jar JaxoDraw.jar`.

Under Windows you simply double click on the `j2re-1_4_1_03-windows-i586.exe` file to install the Java Runtime Environment, followed by a double click on the `jar` file icon to start JaxoDraw.

### Using the shell scripts under Linux

Alternatively to the above procedure, under Linux you may use the bash shell scripts in the JaxoDraw home directory to compile and run the program (provided you have bash and Java installed on your system):

To compile the sources and create the binary classes:

`./compile.bsh`

To create the API specification:

`./doc.bsh [-link Java-API]`

where `Java-API` is the same as in section .

Use the clean.bsh script to delete all binaries and javadoc files:

`./clean.bsh`

You may give a `-all` option to this script which will also remove the `JaxoDraw.jar` file (this may be recreated with the `./compile.bsh` script).

Note that `compile.bsh`, `doc.bsh ` and `clean.bsh` are only included in the `src` distribution.

To run the program:

`./runme.bsh`

or simply

`./jaxodraw`

(which is a symlink to `./runme.bsh`).

### Installing JaxoDraw system wide

**Note**: You need root privileges to install JaxoDraw system wide.

Execute the install shell script

`./install.bsh`

This will put a `JaxoDraw-xxx` directory into `/usr/local`, a symlink to the executable bash script into `/usr/local/bin` and a man page into `/usr/local/man/man1` (you may specify different locations by editing the `./install.bsh` file). Provided, `/usr/local/bin` is in your `PATH`, any user will then be able to run JaxoDraw just by typing `jaxodraw`. To uninstall, just use the script

`./uninstall.bsh`

## Comments and bug reports

Please send your comments, questions or bug reports to any of our e-mail addresses:

-
-

When reporting bugs, you should be as specific as possible about the problem so that we can easily reproduce it. Include some information about your operating system and the version of JaxoDraw that you are using. Include for instance the output of the

`java JaxoDraw/JaxoDraw ``--``info`

and

`java JaxoDraw/JaxoDraw ``--``version`

commands (this information is also available under the Help menu of the graphical user interface). If you are having problems with the LaTeX compilation process, also include detailed information about your LaTeX distribution, the version of `dvips`, your postscript viewer and any other information that may be relevant. Note in particular that there seem to several versions of the `axodraw.sty` around that are not distinguished by a version number. Some of them present problems when used with JaxoDraw, please try to use the one that we distribute with our program before reporting problems regarding `axodraw`. Since we do not maintain a mailing list, we will try to make all messages of general interest available on our Web-site

`http://altair.ific.uv.es/~JaxoDraw/home.html`

Please check these pages and also the FAQ and Known problems sections of this document before reporting any bugs.

## License

    Copyright (C) 2003 Daniele Binosi and Lukas Theussl

    JaxoDraw is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any later version.

    JaxoDraw is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    See the GNU General Public License for more details.

    A copy of the GNU General Public License can be found in the
    file GNU-LICENSE that is distributed along with this program.

    JaxoDraw includes a copy of J. Vermaseren's axodraw.sty file
    (with the kind permission of the author).
    The file FORM-LICENSE in the distribution home directory reproduces
    the author's license agreement as published at

`http://www.nikhef.nl/~form/license.html`

    The .jre version of JaxoDraw includes a copy of the Java Runtime Environment.
    This is redistributed under the terms of conditions as published at

`http://java.sun.com/j2se/1.4.1/j2re-1_4_1_03-license.html`

    This product includes code licensed from RSA Security, Inc.
    Some portions licensed from IBM are available at

`http://oss.software.ibm.com/icu4j/`

    PostScript is a trademark of Adobe Systems Incorporated.

# Using JaxoDraw

## Terminology

-   **Object**
    An object is the collection of points, with optional associated values, that makes up one entity of a Feynman diagram. Examples are blobs, lines, arcs, boxes, loops, etc. The associated values can be used to change the appearance of an object, like color, line width, photon amplitude, and several other features.

-   **Graph**
    A graph is the collection of objects (lines, arcs, ...), together with titles, comments, layout options, etc. drawn to display the Feynman diagram.

-   **Parameters**
    Parameters are the settings of symbols, line styles, colors, fonts, etc. used to define graphs and the display of the active objects.

-   **Handles**
    When the program goes into Edit mode (any mode that allows the modification of any parameters of any object) little red squares are displayed on certain points of every object (for instance on the end points of lines). When the user clicks on one of these handles, the corresponding edit operation is being carried out on the chosen object.

## Execution

The most convenient way to start JaxoDraw depends on your operating system and on how you installed the program. See the Installation section  for generic instructions to run JaxoDraw.

In general, if you compiled the package yourself from sources and put all the binary `.class` files (together with the `doc/` and `icons/` sub-folders) in a sub-directory called `JaxoDraw/`, you can start JaxoDraw by the command

`java JaxoDraw/JaxoDraw`

in the current directory. Supposing you have Java installed on your system, this will work on any platform.

## Command line parameters

The current version supports the following command line parameters:

-   **`--`version**
    Prints out the version number of JaxoDraw.

-   **`--`help**
    Prints out some usage info on the standard output.

-   **`--`info**
    Prints out some information about your system.

-   **`-`verbose**
    Turns on verbose error messaging (default in the current version).

-   **`-`quiet**
    Turns off verbose error messaging.

By default, all parameters starting with **`--`** do not pop up the graphical user interface of JaxoDraw.

Furthermore, if you have saved an XML file with a JaxoGraph in an earlier session, you may read in this graph directly on the command line by supplying the file name as an argument (the extension of the file has to be `.xml`).

## Drawing

Drawing Feynman diagrams with JaxoDraw is pretty easy and self-explaining. The program has been designed with the main strategy to be easy to use. In particular, if you are familiar with the program, you will have little problems to get used to JaxoDraw (even though there are a few differences, in particular when drawing arcs, see below). In general, to draw an element of a Feynman diagram, you first choose the drawing mode by clicking on the corresponding button in the button panel, and then draw the object by left mouse-clicking and dragging on the canvas. Drawn objects may then be moved/resized or edited by choosing the corresponding button in the edit button panel and then clicking on one of the handles specifying the object.

A few things to note:

-   Arcs are always drawn first with a default angle of 180 (a different default angle may be chosen in the Preferences dialog). The angle can then only be changed via the editing menu.

-   Any operation that changes any attribute of an object (move, resize, edit, ...) will automatically put the object in the foreground.

-   It is a good idea to use the refresh button from time to time, especially if there are a lot of objects on the screen and if you are using antialising.

## Setting resources

JaxoDraw allows the permanent setting of preferences via the Preferences menu. If you press the "Save" button for the first time in the Preferences dialog, a corresponding preferences file called `.Jaxorc` will be created in your home directory. This file is read automatically every time JaxoDraw is started. It is in an XML format that may be edited manually if you know what you are doing, the preferred way of editing it is via the above mentioned Preferences menu dialog of the graphical user interface. See the Preferences menu item of section  for more information on the items that may be saved on a permanent basis.

## Colors

In the current version of JaxoDraw, the user may choose from a set of 84 colors that are presented in a convenient color chooser panel if the user clicks an object in color mode. The colors include all the 68 colors defined by the `colordvi` LaTeX class (on a standard TeTeX distribution, these may be found in `/usr/share/texmf/tex/plain/dvips/colordvi.tex`) and 16 gray scales. If you produce figures with color via the `latex ``->`` dvips` commands of JaxoDraw, these colors will be used as defined in the `colordvi` style file. For direct postscript output, we have tried to reproduce as closely as possible the RGB values of these colors, but since there are no complete RGB specifications (for free), the output will not be exactly the same as in the LaTeX case.

As a reference, we include two files in the source distribution of JaxoDraw, that illustrate the differences. The `latexcolor.ps` file in the `JaxoDraw/doc/` directory gives a collection of all the colors present in `colordvi` as produced by `latex ``->`` dvips`. The file `pscolor.ps` in the same directory gives the corresponding collection as produced by direct postscript output.

## Text

There are two ways of entering text in JaxoDraw: Postscript text mode and LaTeX text mode. Even though they may be used at the same time in a graph, they will appear mutually exclusive in any derived output.

-   **Postscript text mode**
    When entering the postscript text mode, the user may enter a text string that will appear directly on the screen and in any direct postscript output (i.e., also in any printer output). It will not appear in any output created via `latex ``->`` dvips`. In edit mode, the user may choose the text size and font of the text object. A set of Greek characters is available via a syntax that is derived from the corresponding LaTeX commands:

    |  |  |  |  |  |  |  |  |
    |:--:|:---|:--:|:---|:--:|:---|:--:|:---|
    | $\alpha$ | `\alpha` | $\lambda$ | `\lambda` | $\upsilon$ | `\upsilon` | $\Lambda$ | `\Lambda` |
    | $\beta$ | `\beta` | $\mu$ | `\mu` | $\phi$ | `\phi` | $\Xi$ | `\Xi` |
    | $\gamma$ | `\gamma` | $\nu$ | `\nu` | $\chi$ | `\chi` | $\Pi$ | `\Pi` |
    | $\delta$ | `\delta` | $\xi$ | `\xi` | $\psi$ | `\psi` | $\Sigma$ | `\Sigma` |
    | $\epsilon$ | `\epsilon` | $o$ | `o` | $\omega$ | `\omega` | $\Phi$ | `\Phi` |
    | $\zeta$ | `\zeta` | $\pi$ | `\pi` | $\vartheta$ | `\vartheta` | $\Psi$ | `\Psi` |
    | $\eta$ | `\eta` | $\rho$ | `\rho` | $\varphi$ | `\varphi` | $\Omega$ | `\Omega` |
    | $\theta$ | `\theta` | $\varsigma$ | `\varsigma` | $\Gamma$ | `\Gamma` |  |  |
    | $\iota$ | `\iota` | $\sigma$ | `\sigma` | $\Delta$ | `\Delta` |  |  |
    | $\kappa$ | `\kappa` | $\tau$ | `\tau` | $\Theta$ | `\Theta` |  |  |

    Note that no \$ signs are necessary for these commands (any \$ signs will appear verbatim on the screen). If the user enters a string starting with a "`\`" that is not recognized as a valid Greek letter, it will be replaced by a question mark "?". In the current version of JaxoDraw it is not possible to do super- or subscripts, this will be implemented in some future version (see the wish list in section ).

-   **LaTeX text mode**
    When entering the LaTeX text mode, the user may enter a text string that will appear only in the LaTeX output file and any files created from it via `latex ``->`` dvips`. Like that all the commands known to LaTeX in math mode are available to the user. The position of the text will be marked on the screen by an icon that identifies it as a LaTeX text object. This icon does not appear in direct postscript or printing output. Note that the LaTeX text string will automatically be put between \$ signs, so the text will always be in LaTeX math mode. If you want a normal font in LaTeX text mode, you should use `{\rm }`. Note also that your input here is the only possible source of errors in your LaTeX source code. If you get any LaTeX compilation errors, check your LaTeX text objects first. In edit mode, the user may choose the LaTeX font size and the alignment with respect to the current position of the text object.

# Screen elements of JaxoDraw

The screen of JaxoDraw is divided into five main sections:

-   The menu bar on top

-   The tool bar just below the menu bar

-   The button panel on the left

-   The status bar on bottom

-   The drawing area (the canvas) in the center

The tool and the status bar may optionally be switched off in the preferences dialog. In the following we will describe each of the above sections in greater detail.

## The menu bar

The menu bar contains four main menu bar items: File, Edit, Options and Help.

#### File

-   **New**
    Starts a new JaxoDraw graph, abandoning the current plot.

-   **Open**
    Open an existing JaxoDraw file, abandoning the current plot. This pops up a file chooser dialog where the user may indicate an XML file that was stored in an earlier session.

-   **Save**
    Save the current plot using the last specified name. If no name is specified, a file chooser menu is popped up. The current graph is then saved in an XML format that may be opened in a later session.

-   **Save As**
    The same as Save, but always pops up a file chooser menu to save the current plot under the chosen name.

-   **Describe**
    Add a text description to a graph. This will appear as a comment in all output files.

-   **Export**
    Pops up a dialog where the user may choose among several export file formats. These ones include: LaTeX `->` EPS (to produce an encapsulated postscript (`eps`) file via `latex ``->`` dvips`), LaTeX (to produce a text file containing LaTeX source code), Postscript Portrait, Postscript Landscape and EPS (to produce direct postscript output via Java's internal postscript interface in portrait, landscape and `eps` format, respectively). Pressing the Export button will pop up a file chooser dialog to enter a file name for the chosen export format.

    In addition, there is a button that allows to preview any of the above output formats. Note that in order to preview any of the postscript exports, you will need to indicate a postscript previewer in the preferences dialog (since there is no Java internal postscript renderer). For previewing output in text format, you may still indicate a preferred text editor but if you do not do so, a Java internal text previewer is used by default.

-   **Print**
    Prints the current graph to a specified printer or postscript file. This opens the standard Java printer dialog where any installed and configured printers are detected automatically. Note that printing to a file should be equivalent to the corresponding Export - Postscript option.

-   **Quit**
    Exits JaxoDraw.

#### Edit

-   **Undo**
    Cancels the last operation. Note that multiple Undo's are not possible.

-   **Clear**
    Clears this graph. This only removes the visible objects from the screen, it does not affect any values associated with the graph.

-   **Move**
    Goes into move mode. Displays handles where the user may grab an object and move it by dragging it over the screen.

-   **Resize**
    Goes into Resize mode. Displays handles where the user may grab an object and resize it by dragging a specified point. Note that loops and arcs cannot be resized from the center point.

-   **Copy**
    Goes into Copy mode. Displays handles where the user may grab an object that will be duplicated by an exact copy that the user may drag to a different location.

-   **Color**
    Goes into Color mode. Displays handles where the user may grab an object which pops up a dialog to change the color of the object. See section  for more information on colors.

-   **Edit**
    Goes into Edit mode. Displays handles where the user may grab an object which pops up a dialog to change the parameters of the object. Which parameters may be edited depends on the object.

-   **Delete**
    Goes into Delete mode. Displays handles where the user may grab an object to delete it.

-   **Background**
    Goes into Background mode. Displays handles where the user may grab an object to put it into the background.

-   **Foreground**
    Goes into Foreground mode. Displays handles where the user may grab an object to put it into the foreground.

#### Options

-   **Look and Feel**
    Lets the user choose a Look and Feel for the current session. Note that some LAFs may not be available on your system and that there might be differences in some layouts, in particular with icons in the tool bar.

-   **Vertex types**
    Lets the user choose the type of vertex to be drawn when in Vertex mode. By default, it is a black dot, other vertices currently supported are a circle with a cross, a square and a cross. Choosing one vertex type will change the icon of the Vertex button in the button panel to the corresponding vertex.

-   **Show Toolbar**
    Lets the user choose whether the toolbar is visible or not.

-   **Show Statusbar**
    Lets the user choose whether the statusbar is visible or not.

-   **Antialias on**
    Lets the user choose whether to use antialiasing or not. The graphics quality is usually better with antialiasing turned on. This goes with the cost that graphics rendering may be slower on some machines and you may need to refresh the screen from time to time, especially after a number of editing operations.

-   **Arrow**
    Lets the user choose whether arrows should be drawn on all objects that support them.

-   **Preferences**
    Pops up a dialog where the user may choose several settings to be saved on a permanent basis. The first group of settings are the default HTML viewer (to view the JaxoDraw documentation in HTML format), a default text editor (used for previewing LaTeX text output) and a default postscript viewer (used for previewing the printer or direct postscript output). Note that you need to specify a default postscript viewer in order to view postscript files from within JaxoDraw because Java does not have an internal possibility to render postscript files. Contrary to that, if you do not specify any default HTML viewer or text editor, previews will still be possible with the Java internal HTML and text rendering mechanisms which will be used by default.

    You may then choose the default Look and Feel, the default size of the grid, the default line width, the default opening angle for arcs, as well as the initial screen size. Finally you may determine whether the tool- and the status bar are visible by default, whether antialiasing should be used by default and whether arrows should be drawn by default on all objects that support them.

    Clicking OK will apply the specified values for the current session without saving them in the system configuration file `.Jaxorc`, clicking Save will save the settings without applying them to the current session, the button Clear only clears the text fields of the default previewers, Reset restores all the values to their current default settings and Cancel closes the Preferences dialog without applying any changes.

    See section  for more information on setting resources.

#### Help

-   **About**
    Gives some information about the version of JaxoDraw you are using.

-   **User guide**
    Pops up a new window with this user guide in HTML format. If a default HTML viewer has been chosen in the Preferences dialog, it will be used, otherwise a Java internal previewer is used by default.

-   **System info**
    Gives some information about your system (current user, operating system, Java installation).

## The tool bar

The tool bar may be switched on and off in the Options menu item. If it is switched on, the tool bar contains icons whose action is identical to the corresponding menu entries: New, Open, Save, Save As, Describe, Export, Print. There is furthermore one icon that does a Latex `->` EPS preview, and on the right there is an icon to pop up the user guide.

## The button panel

The button panel on the left of the screen is divided into the following subsections:

#### Particle buttons

There is one button for each particle type: fermion (straight line), scalar (dashed line), ghost (dotted line), photon (wiggled line) and gluon (pig-tailed line); and the three object types: lines, arcs and loops. When one of these buttons is clicked the program goes into the corresponding drawing mode, i.e., no handles are shown on the screen and the user may click on the canvas to start drawing the corresponding object.

#### Miscellaneous buttons

There are buttons for drawing blobs (ellipses), boxes, vertices and zig-zag lines, as well as buttons that allow the insertion of postscript text and LaTeX text into the graph. See section  above for information on postscript- and LaTeX text mode. When one of these buttons is clicked the program goes into the corresponding drawing mode.

#### Action buttons

These are the buttons that lead to an immediate action: Undo and Clear have the same effect as the corresponding entries in the Edit menu, while the Refresh button leads to a redrawing of the screen. This is especially useful if antialising is used.

#### Edit buttons

There are a number of buttons (Move, Resize, Copy, Color, Edit, Delete, Background and Foreground) whose actions are equivalent to the ones described in the Edit menu panel section. When one of these buttons is clicked the program goes into the corresponding edit mode.

#### Grid and exit button

The grid button turns on the grid so that the user can choose only certain points for placing his objects. Note that this will not change any objects already present on the screen. The exit button quits JaxoDraw.

## The status bar

The status bar may be switched on and off in the Options menu item. If it is switched on, the status bar contains three areas: one to display the current file (if any), one to display the current drawing mode and one that displays the current coordinates of the cursor on the canvas.

## The canvas

This is the main drawing area. After choosing a drawing mode from the button panel, the user may draw the corresponding object by left-clicking and dragging on the canvas.

# Known problems and limitations

This section gives a list of bugs and limitations that were known at the time of first publication of JaxoDraw-1.0. Please check the Bugs section of our http://altair.ific.uv.es/\~JaxoDraw/bugs.html for an updated version of this document. Note that not all points are necessarily real bugs, we regard this just as a collection of features that do not work exactly the way we would like to.

## Bugs

-   If a LaTeX text file is previewed with the Java internal previewer (i.e. without having set a custom previewer in the preferences), the page displays but cannot be scrolled. When the export chooser menu is closed, it becomes scrollable (this may be used as a workaround).

-   Choosing a different Look and Feel in the Preferences dialog of the Options menu item and pressing the OK button, does not update the Look and Feel of the current session. Workaround: use the Look and Feel dialog of the Options menu instead.

-   When using IBM's Runtime Environment, the program may be executed and works fine for most parts but presents some peculiarities: the layout of pop up windows is not always the same and XML output serializes the bounding boxes of objects that are explicitly marked as transient in the source code. This has been reported to us for version number `1.4.1` of IBM's SDK. For us, this appears to be an incompatibility between SUN's and IBM's Runtime Environments. On the other hand, the program compiles fine with IBM's jikes compiler (tested with version `1.13`).

-   If your LaTeX compilations give errors complaining about unknown commands like

    , you will probably have to update your `axodraw.sty` file to a more recent version (the one included in our distribution will work).

-   There is a bug in `axodraw` concerning gluon loops. In fact there is no command for drawing gluon loops, but if you draw a gluon arc with 360, then the gluon wiggles do not close correctly. Since this is a bug in `axodraw`, there is no workaround except not to use gluon loops, or, if you need nicely closing loops, to use the direct postscript output of JaxoDraw.

-   Running an internal LaTeX compilation without `axodraw` installed (or LaTeXin the case you are a Windows user), will hang the program. Please check appendix  for information about installing `axodraw`.

## Wish list

The following are requested features that we will hopefully implement in a future version of JaxoDraw:

-   Enhance the TextParser class to allow sub- and superscripts in text objects

-   Implement a triangle vertex

-   Improve the drawing of arcs

-   Let the user include custom packages in the LaTeX output

-   Add the possibility to move/copy a group of objects

-   Allow to work with several graphs at a time

-   Show the LaTeX text in a pop-up window when rolled over

# Documentation

This section gives a list of hints and tricks as well as a list of frequently asked questions that were known at the time of first publication of JaxoDraw-1.0. Please check the Docs section of our , for an updated version of this document.

## Tips and tricks

-   Note that postscript files produced by Export - EPS are considerably larger in size than the same files generated via `latex ``->`` dvips`. This is due to the way how Java handles the postscript printing internally. Keep this in mind if you want to include a bunch of small figures in your document: it is then probably preferable to use the LaTeX output.

-   It is a good idea to use the refresh button from time to time, especially if there are a lot of objects on the screen and if you are using antialising.

-   Instead of producing EPS figures and including them into your document, you may as well cut-and-paste the LaTeX output of JaxoDraw into your own LaTeX source code. Like that you may avoid the proliferation of numerous postscript files to be distributed with your source code. Note however that you will have to include `axodraw` in the header of your LaTeX file (put

    somewhere before

    ) and you will probably have to distribute the `axodraw.sty` file along with your source code because it is not part of any standard LaTeX distribution.

-   To add multiple arrows to objects (such as loops, for example), or to draw arrows on objects that do not support them (photon and gluon objects in particular), use fermion lines with very small length (5 points should do the job). Use the edit menu, to give the arrow the inclination you need and then move it to the wanted location.

## FAQ

No questions so far ...

# History

|          |                       |
|---------:|:----------------------|
| 1.9.2003 | Released JaxoDraw-1.0 |

# Credits

We are grateful to Prof. Arcadi Santamaria for numerous helpful remarks and moral support during the development of JaxoDraw. We also acknowledge Prof. Jos Vermaseren for his kind permission to use and distribute his axodraw style file along with JaxoDraw.


abstract: Space weather and its impact on infrastructure presents a clear risk in the modern era, as evidenced by the adverse effects of geomagnetically induced currents (GICs) in power networks. To model GICs, ground-based geomagnetic field (B-field) measurements are critical and need to be available in the region of interest. A challenge globally lies in the sparse distribution of magnetometer arrays, which are seldom located near critical power network nodes. Interpolation of the geomagnetic field (B-field) is often needed, with the spherical elementary current system (SECS) approach developed for high-latitude regions favoured. We adapt this interpolation scheme to include low-cost variometers to interpolate $dB/dt$ directly and increase interpolation accuracy. A further adaptation to the scheme is to physically represent the mid-latitude context where most power networks and pipelines lie. The driving current systems in these regions differ from their high-latitude counterparts. Using a physics-consistent mid-latitude version of SECS, we show why previous implementations in Southern Africa are incorrect but still result in useful interpolation. The scope of these adaptations not only has direct application to research in general, but also to utilities, where effective low-cost instrumentation can be used to improve GIC modelling accuracy.
address: Department of Physics, Imperial College London, London, UK, SW7 2BW; Department of Electrical Engineering, University of Cape Town, Cape Town, South Africa, 7700; South African National Space Agency, Hermanus, South Africa, 7200
author: M. J. ; S. I. ; P. J. ; C. T.
title: Adaptations to a geomagnetic field interpolation method in Southern Africa

# Introduction

In the context of increasing societal dependence on technology, the need for improved space weather awareness has been recognised internationally. Loosely, space weather is the effect of solar activity on the Earth and the near-Earth environment. The technologies affected by adverse space weather are widespread, ranging from satellite operation, HF communication and GPS navigation, to grounded conducting networks such as power grids, railways and pipelines . The primary space weather related cause of damage in power grids and pipelines arises from geomagnetically induced currents (GICs). In power networks, GICs driven by extreme space weather events may result in total system collapse, similar to that which led to the 1989 Hydro-Québec blackout . A conservative estimate of the direct economic impact of this event, which caused a 12-hour long power blackout for millions of people, was on the order of \$13.2 million . The indirect and knock-on economic effects may be much larger . In response to the threat posed by GICs, the United States Federal Energy Regulatory Commission (FERC) issued a directive for all utilities in the United States to assess GIC risks and undertake data collection in support of research in the field . GIC research efforts however have been international, and include engineering aspects , geophysical modelling and economic assessments .

For most space weather ground-effects, it is the interaction of solar plasma with the near-Earth environment that acts as the driving mechanism. Short-term fluctuations of the geomagnetic field (B-field) measured on the ground are a direct result of these interactions. The Earth's roughly dipolar B-field is perturbed by near-Earth currents, created by interactions between the solar wind plasma and the magnetosphere. As such, geomagnetic activity as measured by the B-field on the surface of the Earth generally tracks space weather activity. For GICs, the B-field and its fluctuations ($dB/dt$) are more than just a proxy for space weather activity. Through Faraday's law of induction, the fluctuations of the penetrating B-field induce a geoelectric field (E-field) and telluric currents within Earth. These naturally occurring currents are often used by the geophysics community to estimate the subsurface conductivity structure through magnetotelluric (MT) modelling in the frequency domain. When a grounded conducting network is present, the induced currents may enter the network as GICs and disrupt operations. Accurate estimation of the disturbance B-field or $dB/dt$ is the first step in providing accurate modelling and forecasting of GICs.

A challenge globally, for both GIC and other geophysical research, is the sparse spatial coverage of observatory-grade magnetometers that can measure the absolute values of the geomagnetic field. A natural approach has been to make use of spatial interpolation of the B-field. Various interpolation methods have been used, ranging from simplistic nearest neighbour approaches to spherical cap harmonic analysis , Delauney triangulation and polynomial interpolation using magnetic scalar potentials . The favoured method is however the physically inspired spherical elementary current systems (SECS) interpolation scheme . The basic idea behind SECS interpolation is that an equivalent current system at a height similar to a driving near-Earth current system can be estimated using basis functions, with coefficients constrained using B-field measurements at geomagnetic observatories. At high-latitudes, where the complex auroral electrojets occur, the assumed height is around 100 km, which locates the equivalent currents in the D-region of the ionosphere. Further, it is assumed that at high-latitudes divergence-free current nodes can be used as basis functions to fully describe the ionospheric Hall currents associated with near-vertical field-aligned currents. In previous GIC modelling in Southern Africa, SECS has been used extensively to interpolate B-field estimates within the power network and improve on GIC estimates . However, for the mid-latitude Southern African context where distant magnetospheric currents are the main driver, divergence-free basis functions are not expected to be representative of the more spatially consistent B-field. Explicitly, the use of divergence-free basis functions has been identified as a cause of inadequate interpolation accuracy using SECS in other mid-latitude regions .

This paper acts as a follow-up to the original implementation of SECS in Southern Africa by and will address two important adaptions in B-field interpolation that improve interpolation accuracy and interpretability. The first is to include data from low-cost fluxgate magnetometers operated as variometers, i.e. not observatory-grade magnetometers, to improve interpolation accuracy. The second adaption is to correct the previous implementation of SECS and then identify basis functions that are more appropriate for mid-latitudes.

The next section outlines the extent of magnetometer measurements in Southern Africa, with datasets identified for validation of SECS interpolation and its adaptations. The mechanics of SECS interpolation and the proposed adaptations are then presented, followed by implementation of both in the results section. The paper concludes with a discussion of the results and the implications of adapted B-field interpolation.

# Geomagnetic Field Measurements in Southern Africa

Southern Africa has a long legacy of geomagnetic research and currently has four geomagnetic observatories (HER, HBK, KMH and TSU), operated by the South African National Space Agency as part of the international INTERMAGNET network (www.intermagnet.org). Although these geomagnetic observatories form the backbone of geomagnetic research, there is an increasing number of field assets with similar potential. Specifically, additional B-field measurements may come from lower cost magnetometers that are not observatory-grade (often not temperature controlled, which may introduce drift that affects measurements when not corrected for). Similar to variometers or induction magnetometers, these low-cost magnetometers are able to accurately measure B-field variation (per timestep). As shown in Figure , leveraging these additional measurements would create a much denser grid of B-field measurements.

Magnetometer data from the various sites in Figure and Table are used for both interpolation and validation. First, there is initial validation of the SECS interpolation scheme as applied by previous work. Validation was done using the INTERMAGNET sites to drive interpolation across Southern Africa, which is then compared to B-field measurements from sites where LEMI-417M magnetotelluric (MT) sensors are deployed. The second use of data is in the validation of adaptations of the interpolation scheme. These adaptations require concurrent data coverage across sites and, due to availability, four geomagnetic storms in 2015 are used (see Table , 22,224 data points in total). The data used include samples from all phases of the geomagnetic storm, from quiet time to the impulsive peak, rapidly varying main phase and slowly varying recovery phase. High-fidelity B-field measurements from the KMH observatory are kept as the out-of-sample dataset for validation purposes. Adaptations are driven with data from either the remaining three INTERMAGNET sites (HER, HBK, TSU), or additionally including data from magnetometers at SUT, WAT and KMS. The observatories at SUT and WAT make use of LEMI-025 3-axis fluxgate magnetometers, whereas KMS is an MT site equipped with a LEMI-417M 3-axis fluxgate magnetometers and a 2-axis E-field sensor. All fluxgate instruments are designed to measure the absolute magnetic field components along three orthogonal axes. The absolute field measurements are however subject to drift, which is corrected through manual baseline measurements (as done at INTERMAGNET sites). In this paper, for ease of reference we will refer to low-cost fluxgate magnetometers with uncorrected baselines as variometers. More accurately, a variometer is used to measure the variation of the field components about baseline values, usually through induction measurements of $dB/dt$. Induction magnetometers are typical examples of variometers. These magnetometers are based on Faraday's law of induction and use induction coils to measure the emf (voltage) induced by changes in magnetic flux through the coil, i.e. $dB/dt$ and not the absolute B-field.

|                    |         |            |      |             |      |
|:------------------:|:-------:|:----------:|:----:|:-----------:|:----:|
|      Station       | Station | Geographic |      | Geomagnetic |      |
| Type / Name |  Code   |    Lat.    | Lon. |    Lat.     | Lon. |
| INTERMAGNET |         |            |      |             |      |
|   Hartebeesthoek   |   HBK   |   -25.9    | 27.7 |    -36.3    | 97.0 |
|      Hermanus      |   HER   |   -34.4    | 19.2 |    -42.8    | 84.6 |
|    Keetmanshoop    |   KMH   |   -26.6    | 18.1 |    -37.2    | 87.0 |
|       Tsumeb       |   TSU   |   -19.2    | 17.7 |    -31.1    | 89.2 |
|  LEMI-025   |         |            |      |             |      |
|     Sutherland     |   SUT   |   -32.4    | 20.8 |    -41.5    | 87.2 |
|     Waterberg      |   WAT   |   -20.5    | 17.2 |    -32.3    | 88.3 |
|  LEMI-417M  |         |            |      |             |      |
|      Kakamas       |   KMS   |   -28.5    | 20.5 |    -38.6    | 88.7 |
|      Koeberg       |   KOE   |   -33.4    | 18.3 |    -42.3    | 84.2 |
|     Middelpos      |   MID   |   -31.5    | 20.1 |    -41.1    | 86.8 |
|        Obib        |   OBB   |   -27.5    | 16.4 |    -38.2    | 85.7 |
|     Trompsberg     |   TRM   |   -30.0    | 26.0 |    -39.7    | 94.5 |
|      Vaalputs      |   VLP   |   -30.1    | 18.3 |    -39.9    | 85.9 |

Geomagnetic measurement sites in Southern Africa (see Figure ).

|             |                      |     |
|:-----------:|:--------------------:|:---:|
| Geomagnetic |         Data         | Max |
|    Storm    |        Range         | Kp  |
|      1      | 15-16, 18 March 2015 |  6  |
|      2      |   21-23 June 2015    | 8+  |
|      3      | 09-12 September 2015 |  7  |
|      4      | 06-14 September 2015 | 7+  |
|             |                      |     |

Data availability for HER, HBK, TSU, SUT, WAT and KMS sites to validate interpolation adaptations relative to KMH. Maximum Kp (planetary K-index) during periods is included as an indication of geomagnetic activity.

# SECS Interpolation

SECS uses an equivalent current system to create a physically inspired interpolation scheme based on Maxwell's equations. As shown by , including this prior adds significant robustness when compared with other purely mathematical interpolation schemes that do not consider the physical context. From Helmholtz's theorem, any current flowing on a surface can be broken into a curl-free part (allowing current flow into and out of the surface) and a divergence-free part (allowing current flow on the surface). In terms of the real-world current systems at play, overhead ionospheric Hall currents associated with the auroral electrojet system would be linked to the divergence-free part. The curl-free part is more often associated with field-aligned and Pedersen currents. Assuming a uniform conductivity of the ionosphere and field-aligned currents that are perpendicular to the ground, ground-based measurements would predominantly measure the overhead divergence-free Hall currents at high-latitudes . SECS interpolation aims to approximate a similar real-world current system with an equivalent current system or current surface at an arbitrary height, as shown in Figure .

Of the different SECS implementations, we assume cylindrical coordinates ($r=\sqrt{x^2+y^2},\phi,z$) , with a current element of amplitude $I_0$ at height $h$, as shown in Figure . Implementation of SECS at mid-latitudes assumes that divergence-free current system representation still holds, and an equivalent current height of 100 km has been used in previous implementations in Southern Africa . It should be noted that no physical current system exists at this height for mid-latitudes. Rather the dominant current systems are the more distant magnetospheric currents . Nevertheless, for divergence-free current nodes $I_0$ within the SECS interpolation scheme, the equivalent surface current density $\vec{J_{df}}(\rho)$ as a function of radial distance $\rho$ from current node on the current surface is,

$$\begin{aligned}
\vec{J_{df}}(\rho)=\frac{I_0}{2\pi\rho}\hat{e_\phi},
\end{aligned}$$ where $\hat{e_\phi}$ is in the azimuthal direction.

Choosing a cylindrical coordinate system where $z$ is downwards, and assuming the disturbance B-field shows harmonic time dependence (i.e. $e^{i\omega t}$), a current node $I_0$ can then be related to a measured B-field on the ground for a given time instance through ,

$$\begin{aligned}
\vec{B}(r)=\frac{\mu_0I_0}{4\pi r}\left(\left(1-\frac{h}{\sqrt{r^2+h^2}}\right)\hat{e_r}+\left(\frac{r}{\sqrt{r^2+h^2}}\right)\hat{e_z}\right).\label{eq:secs}
\end{aligned}$$

Here $\mu_0$ is the permeability of free-space, $r$ is the radial distance from the current node to observer on the surface of the Earth and $h$ is the height of the equivalent current system.

For some defined spatial extent, we can then extend this Biot-Savart relation from a single current element to a grid of elementary current elements. Taking the current grid (say $n$ elements), we group all current elements into a vector $I$. To constrain the elementary currents, we require B-field measurements. Assuming there are multiple magnetometers (say $m$ stations), we can similarly group the B-field measurements into a vector $B$. To solve for $I$, a matrix equation is set up, i.e. $B=T\cdot I$, where $T$ is a transfer function matrix that relates the elementary currents to the measured B-field, encoding the geometry of the problem. Since we are only interested in the horizontal B-field, only the radial component $\hat{e_r}$ of is used. An important property of the transfer function is that it is purely a spatial relationship between the elementary current and the magnetometer station.

Diverging from the traditional SECS formalism, but following previous implementations in Southern Africa, the matrix equation calculation is performed separately for the $x$ (north-south) and $y$ (east-west) components of $I$ and $B$ respectively. More explicitly in matrix form,

$$\begin{aligned}
\begin{array} {rcl}
\left[ \begin{array}{c}
B_{x,y:1} \\
\vdots \\
B_{x,y:m}
\end{array} \right]
& = &
\left[ \begin{array}{ccc}
T_{11} & \cdots & T_{1n} \\
\vdots & \ddots & \vdots \\
T_{m1} & \cdots & T_{mn}
\end{array} \right]
\left[ \begin{array}{c}
I_{x,y:1} \\
\vdots \\
I_{x,y:n} \end{array}
\right],
\end{array}
\end{aligned}$$ where, $$\begin{aligned}
T_{ij}=\frac{\mu_0}{4 \pi r}\left(1-\frac{h}{\sqrt{r_{ij}^2+h^2}}\right).
\end{aligned}$$

In this particular formalism, the $B_{x,y}$ components are related to corresponding current nodes, i.e. $I_{x,y}$ does not refer to direction. The indices $i$ and $j$ refer to the mapping between magnetometer ($[B_1,...,B_m]$) and current element ($[I_1,...,I_n]$) respectively.

Since interpolation is usually needed for sparse magnetometer grids, $m<n$ and the problem is underdetermined. This further means that $T$ is non-square ($m\neq n$), and $I$ needs to be calculated through a quasi-inverse $T^{-1}$, i.e. $I=T^{-1}B$. Commonly, this quasi-inverse $T^{-1}$ is obtained through singular value decomposition (SVD). After successfully solving the inversion problem and estimating the vector $I$ from the measured B-field, $I$ can be used to interpolate the B-field to any other point of interest, i.e. $B'=T'\cdot I$. This procedure is then repeated for all required time instances.

| Site |      Data Range      | Comparison | *RMSE* | $\rho$ |
|:----:|:--------------------:|:----------:|:------:|:------:|
| HER  |  5/4/2012-15/8/2012  |  INTERMAG  | 16 nT  |  0.82  |
|      |  8/1/2015-27/1/2015  |            |        |        |
| HBK  |  1/11/2013-7/1/2015  |  INTERMAG  | 16 nT  |  0.68  |
| KMS  | 1/9/2013-19/10/2015  |    SECS    |  4 nT  |  0.99  |
| MID  |  6/7/2012-7/11/2012  |    SECS    |  4 nT  |  0.99  |
| OBB  | 30/8/2013-11/12/2014 |    SECS    |  8 nT  |  0.93  |
|      | 17/9/2015-11/12/2015 |            |        |        |
| VLP  | 22/5/2012-9/11/2012  |    SECS    | 17 nT  |  0.76  |
|      | 25/5/2014-14/2/2015  |            |        |        |

Comparison of MT variometer measurements (LEMI-417M magnetotelluric sensors) with geomagnetic observatories and SECS interpolation over Southern Africa as defined by RMSE and the correlation coefficient $\rho$.

## Validation of Previous SECS Implementation

To test the accuracy of the SECS interpolation scheme as implemented in Southern Africa previously, a set of data from MT magnetometers can be used to compare interpolation with measurement. Table below shows various periods of measured B-field at MT sites compared with SECS interpolation at those sites. Of the MT sites used, HER and HBK are co-located with INTERMAGNET stations and the accuracy of MT variometer measurements can be calibrated against observatory-grade magnetometer measurements in general. The interpolation in this case makes use of a current node grid spanning an area larger than the interpolation region, with distances between current nodes roughly 100 km. To mirror previous work done in Southern Africa , the height of the equivalent current system is similarly taken as 100 km and B-field data from HER, HBK, KMH and TSU INTERMAGNET sites are used to drive the interpolation. From the resulting comparisons in Table , the difference in B-field measurements at co-located INTERMAGNET observatory magnetometers and MT magnetometers is larger than the difference between SECS interpolation and similar MT magnetometers at remote sites. The comparison suggests that the previous implementation of the planar SECS interpolation scheme does just as well as having a variometer available - in effect validating previous use of the SECS method for GIC applications in Southern Africa. A question raised by this analysis is why the planar SECS interpolation scheme does so well in Southern Africa, and not at other mid-latitudes where previously implemented ? Possible answers to this question are explored in Sections and .

# dSECS: Interpolating $dB/dt$ Directly

If we shift the focus to modelling the variation of the B-field, we do not need the luxury of drift-corrected observatory-grade magnetometers. Instead, we can adapt the principle behind SECS interpolation and use low-cost fluxgate magnetometers or variometers that accurately measure the change in the B-field i.e. $dB/dt=B(t_i)-B(t_{i-1})$. Since the transfer matrix $T$ is time independent, we see that $dB/dt$ can be interpolated in much the same way as $B$. The only difference in this case is that current nodes used for interpolation become current node variations $dI/dt$, i.e.,

$$\begin{aligned}
dB/dt&=&B(t_i)-B(t_{i-1})\nonumber\\
&=&T\cdot I(t_i)-T\cdot I(t_{i-1})\nonumber\\
&=&T\cdot \left(I(t_i)-I(t_{i-1}) \right) \nonumber\\
&=&T\cdot dI/dt.
\end{aligned}$$

Observatory-grade magnetometers can of course act as variometers, with the implication that there will be more variometers available than absolute magnetometers. Given a larger number of variometer measurements, the confidence in $dB/dt$ interpolation would be higher than for the case where only measurements of $B$ are used. The rate of change $dB/dt$ is also what is typically used for geoelectric studies and can be used as an alternative to the B-field in the frequency domain. Using the greater interpolation accuracy of $dB/dt$, we can nevertheless improve the interpolation of $B$. To do this, we consider the time series of $B$ and of $dB/dt$. Let us assume the time series $B$ is of length $N+1$ and hence $dB/dt$ is of length $N$. Assuming there exists an $N+1$ set of perturbations $\epsilon$ that link the interpolated B-field estimate with the more accurate interpolated $dB/dt$ variation estimate, the two resulting time series can be equated,

$$\begin{aligned}
dB_1/dt&=&(B_2+\epsilon_2)-(B_1+\epsilon_1)\nonumber\\
&\cdots&\nonumber\\
dB_N/dt&=&(B_{N+1}+\epsilon_{N+1})-(B_N+\epsilon_N).
\end{aligned}$$

In matrix form $A\vec{x}=\vec{b}$, this would be rewritten as,

$$\begin{aligned}
\hspace*{-25pt}
\small
\textit{\tiny N}\overset{\xrightarrow[\hphantom{\hspace*{3cm}}]{\textit{N+1}}}{\left\downarrow {\footnotesize \left[
\begin{array}{ccccc}
-1 & 1 & 0 & \cdots & 0 \\
0 & -1 & 1 & \cdots & 0 \\
\vdots & \ddots & \ddots & \ddots & \vdots \\
0 & \cdots & 0 & -1 & 1
\end{array} \right]}
\right.}
\left[ \begin{array}{c}
\epsilon_1 \\
\epsilon_2 \\
\vdots \\
\epsilon_{N+1} \end{array}
\right]=\left[ \begin{array}{c}
\frac{dB_1}{dt} + B_1 - B_2 \\
\frac{dB_2}{dt} + B_2 - B_3 \\
\vdots \\
\frac{dB_N}{dt} + B_N - B_{N+1}
\end{array} \right].
\end{aligned}$$

Although the sparse matrix $A$ is non-square ($N \times N+1$), it has an analytical quasi-inverse that is well-behaved does not need to be estimated through SVD. This inverse is given by,

$$\begin{aligned}
A^{-1}=
\overset{\xrightarrow[\hphantom{\hspace*{5cm}}]{\textit{N}}}{\left.\left[ \begin{array}{ccccc}
-\frac{N}{N+1} & -\frac{N-1}{N+1} & -\frac{N-2}{N+1} & \cdots & -\frac{1}{N+1} \\
\frac{1}{N+1} & -\frac{N-1}{N+1} & -\frac{N-2}{N+1} & \cdots & -\frac{1}{N+1} \\
\frac{1}{N+1} & \frac{2}{N+1} & -\frac{N-2}{N+1} & \cdots & -\frac{1}{N+1} \\
\vspace{-0.25cm} & & & & \\
\vdots & \ddots & \ddots & \ddots & \vdots \\
\vspace{-0.25cm} & & & & \\
\frac{1}{N+1} & \cdots & \frac{N-2}{N+1} & -\frac{2}{N+1} & -\frac{1}{N+1} \\
\frac{1}{N+1} & \cdots & \frac{N-2}{N+1} & \frac{N-1}{N+1} & -\frac{1}{N+1} \\
\frac{1}{N+1} & \cdots & \frac{N-2}{N+1} & \frac{N-1}{N+1} & \frac{N}{N+1}
\end{array} \right]\right\downarrow}\textit{\tiny N+1}\hspace*{2pt}.
\end{aligned}$$

To verify the nature of the quasi-inverse, it can be shown that $AA^{-1}=\mathds{1}(N\times N)$ and $A^{-1}A\approx\mathds{1}(N+1\times N+1)$ when $N\gg1$. Since all the components in $\vec{b}$ are known, this quasi-inverse approach is used again to solve for the perturbations $\vec{x}$. After $\vec{x}$ is estimated in our particular case, each original interpolated baseline $B_i$ time instance is updated by its corresponding perturbation $\epsilon_i$, i.e. the resulting initial B-field interpolation is constrained by the more accurate interpolated $dB/dt$. This formalism of efficiently constraining a baseline estimate by a more accurate variation estimate has widespread application.

# Correction to Previous SECS Implementation

A possible reason for discrepancy regarding improved performance relative to other SECS implementations in mid-latitude regions lies in the implementation of the interpolation scheme. Specifically, the previous implementations in Southern Africa assumed that the $B_x$ and $B_y$ components can be computed independently with corresponding $I_x$ and $I_y$ current nodes. This is not a correct physical interpretation of the SECS methodology that assumes a single $I_0$ current node related to a horizontal radial B-field ($B_r$), that would need to be projected into its $B_x$ and $B_y$ components. When attempting a correct implementation of SECS using that same data as in the validation shown in Table , the interpolation performance breaks down as the divergence-free current node bases fail to link to the sparse magnetometer measurements. Furthermore, performance is exceptionally sensitive to choice of current system grid as the B-field contributions from various divergence-free current nodes need to cancel to describe a relatively spatially consistent B-field, typical of mid-latitudes.

Although the previous implementation of SECS in Southern Africa diverges from the physical basis of traditional SECS interpolation, the fact that it achieves accurate interpolation suggests a similar adaptation would be feasible. The accuracy in describing a spatially smoother field is due to artificial smoothing of the interpolation across an area much larger than the defined divergence-free equivalent current height of 100 km at mid-latitudes, where additionally no such current system would exist. This smoothing introduced by $(1-h/\sqrt{r^2+h^2})$ is compounded by allowing the two components of the B-field to be defined separately. The combination allows a smooth current system to be represented, when Hall-like ionospheric currents should be the basis. Hence, although not physically consistent, the previous implementation of SECS interpolation in Southern Africa can be seen an effective mathematical transform.

For similar representativeness of traditional SECS interpolation, an adapted version of the interpolation scheme can be developed using either short/finite line current elements or infinite line currents to form an equivalent current system (ECS). Physically, we expect a line current basis to be appropriate for the distant magnetospheric current driving seen at mid-latitudes. Using the same underlying approach of SECS, this correction takes the form of a Biot-Savart mapping from each line current element to ground B-field measurement. Assuming a right-handed coordinate system where $z$ is upwards, and making use of the set-up shown in Figure and Figure we have,

$$\begin{aligned}
B_{x,y}&=&\mp\frac{\mu_0 I_{y,x}}{4\pi h'}\cos(\theta)|\sin(\phi_1)-\sin(\phi_2)|\nonumber\\
&=&\mp\frac{\mu_0I_{y,x}}{4\pi h'}\frac{h}{h'}|\sin(\phi_1)-\sin(\phi_2)|\nonumber\\
&=&\mp\frac{\mu_0I_{y,x}}{4\pi}\frac{h}{r_{x,y}^2+h^2}|\sin(\phi_1)-\sin(\phi_2)|.\label{eq:cor}
\end{aligned}$$

The angles $\phi_1$ and $\phi_2$ are defined as the angles between ground observer and line element end points in a calculation plane ($x',y',z'$), i.e. the plane that includes both the current element and ground observer. Including the orthogonal height $h'$ in the calculation plane results in the magnetic field a distance $\xi$ away from the current element, and defined in the calculation plane reference frame. Since the calculation plane is an angle $\theta$ away from the vertical plane, an additional projection of $\cos(\theta)$ is required to get the magnetic field result back into horizontal components in a standard geographic reference frame. This projection can be simplified to use the calculation plane height $h'$ and standard height $h$. Further simplification allows the entire relation to be defined in terms of the current system height $h$ and the orthogonal projection $r_{x,y}$ (relative to the current element). The final result in equates $B_{x,y}$ to orthogonal $I_{y,x}$ current elements, using the $r_{x,y}$ projection orthogonal to the current element and the angles $\phi_1$ and $\phi_2$ which define the extent of the current element.

In the geometry of the problem, we explicitly have that the $B_{x,y}$ components are mapped to the orthogonal $I_{y,x}$ components (using the appropriate projected displacement components $r_{x,y}$). Note the change of sign for the $-I_y$ current driving $B_x$. Here it should also be stressed that the calculation for the $x$ and $y$ components are done separately, unlike traditional SECS interpolation. The derivation of the Biot-Savart equation takes into account the relation between line element and ground node in the plane formed by the line element and node, with the result then rotated to the typical frame of reference and measurement. As in previous modelling, the distances between current nodes are roughly 100 km and for this case it is assumed that current elements are connected, i.e. the current element lengths either side of each node are half the distance to the adjacent node.

Instead of assuming discrete line elements in the ECS interpolation scheme, an infinite line current approach can be used in a similar way with projection from a calculation plane. Assuming the line current is infinite in extent compared with the interpolation distances, we have the simplified Biot-Savart form,

$$\begin{aligned}
B_{x,y}=\mp\frac{\mu_0 I_{y,x}}{2 \pi}\frac{h}{r_{x,y}^2+h^2}.\label{eq:cor_inf}
\end{aligned}$$

In the previous implementation of SECS in Southern Africa, with separate calculation of components, the Biot-Savart mapping tends to approximate a $1/r$ drop-off in B-field magnitude when $r\gg h$, i.e. $B_{x,y}=\mu_0I_0/4\pi r_{x,y}$. This implementation is as such able to describe the B-field over a much larger area (1000's of km) than the scale height of the equivalent current system (100 km). When $r<h$, the divergence-free current system (which can be thought of as a current disc defined for each node) provides horizontal contributions that increasingly cancel each other out, finally cancelling out entirely at $r=0$. The B-field as such is damped by $(1-h/\sqrt{r^2+h^2})$ radially, with a minimum of zero directly under the node (associated with an incident field-aligned current). Physically, this is not expected at mid-latitudes.

In the line element ECS adaptation presented, when $r\gg h$ the B-field drops off as $1/r^2$, which requires a magnetometer grid with scale length of at most $h$ for reasonable interpolation. Fortunately for mid-latitudes, the dominant driving current systems are magnetospheric currents and $r<h$ for interpolation lengths over Southern Africa (roughly 1000 km). Using an ionospheric equivalent current system defined at a height of 100 km on the other hand results in B-field contributions that drop off significantly. Only scale lengths of roughly 100 km can be correlated, and not the 1,000 km needed over Southern Africa. However, keeping in line with the mid-latitude physical drivers being largely magnetospheric currents, setting the height of the current system at roughly 5,000 km in turn satisfies $r<h$ condition over the region and produces an accurate smooth current system along with accurate B-field interpolation. To stress, an ECS at 5,000 km does not represent a physical current system, but rather an equivalent current system at a height informed by the spacing between magnetometers that correctly captures the far-field contributions of the driving magnetospheric currents over the region of interest.

# Results

To test the different adaptations to SECS, KMH data is kept out-of-sample and used for comparison. SECS and the corrected line current element ECS interpolation scheme use HER, HBK and TSU geomagnetic data to drive interpolation. The dSECS and dECS approaches that use variometers to interpolate $dB/dt$ and update the B-field estimate make use of the SUT, WAT and KMS variometers. To aid comparison, interpolation in all cases uses an equivalent current grid spanning 34.5-18.5°S and 16.5-28.0°E in geographic coordinates. The extent spans the ground measurements and equates to roughly 1,200 km in the east-west direction and 1,700 km in the north-south direction. Using a grid with dimensions of $13\times18$ in these respective directions, a grid spacing of roughly 100 km between current nodes in both directions is obtained. For SECS and dSECS results, an equivalent current height of 100 km is used to match previous implementations in Southern Africa. The line element ECS and dECS instead uses a height of 5,000 km to satisfy the $r<h$ condition, where $r$ is the interpolation scale length.

Since both SECS and ECS aim to model equivalent external current systems, the disturbance B-field due to such current systems is what is ultimately interpolated. As such, in pre-processing the data, the background contribution of Earth's intrinsic geomagnetic field is removed. This intrinsic or main field contribution is estimated as the average B-field during preceding geomagnetically quiet time (24 hours). Geomagnetically quiet time in this case is identified by an absolute SYM-H level below 10 nT and ambient solar wind conditions. More sophisticated B-field baseline removal techniques exist, such as using average daily quiet time B-field profile over a month to remove the diurnal solar quiet (*Sq*) variation . By only removing a constant baseline in our case, the low-level (relative to a geomagnetic storm) *Sq* current system contributions are implicitly included within the disturbance field. A visualisation of the different disturbance fields over Southern Africa using the previous implementation of SECS and dSECS adaptation can be seen in Figure .

|       Model       | $B_x$ P-score | $B_y$ P-score |
|:-----------------:|:-------------:|:-------------:|
|       SECS        |     0.83      |     0.80      |
|       dSECS       |     0.91      |     0.88      |
| Line element ECS  |     0.94      |     0.84      |
| Line element dECS |     0.93      |     0.88      |

Results of adaptations to B-field interpolation as defined for the KMH validation set during four geomagnetic storms in 2015 ($n=22,224$ data points).

Table summarises the performance of the various adaptations relative to measured KMH data for the four geomagnetic storms described in Table . The performance is defined by $P=1-(\textit{RMSE}/\sigma)$ (where *RMSE* is the root mean square error and $\sigma$ is the standard deviation of the measured quantity ). A P-score of 1 reflects zero residuals and indicates perfect modelling. Both dSECS and the corrected line element equivalent current system (ECS) implementations improve on the previous implementation of SECS. $B_x$, which links to the main driver of the magnetospheric east-west currents, sees an improvement of between 10-13%. The largest improvement, in this case, links to a better representation of the magnetospheric current driving through the line element ECS implementation. Since B-field perturbations at mid-latitudes are dominated by the east-west magnetospheric currents, $B_y$ is more likely affected by induction effects within Earth and finer scale current system perturbations. As such, $B_y$ is less accurately interpolated. That said, $B_y$ shows a similar relative improvement given the use of adapted interpolation (dSECS) with a larger number of B-field measurements through the inclusion of variometers. The combination of the dSECS methodology and line element ECS basis in dECS result reflects the improvements dominated by both current system representation and more localised representation.

A further visualisation of the improvement given adaptions of the interpolation scheme can be seen through the error distributions in Figure . Using all storms for these total error distributions, it is evident that the proposed adaptations improve B-field interpolation. In both B-field components, the spread of the distribution as defined by the interquartile range is reduced for the dSECS method (44% improvement). The adaptation error distributions also tend more towards Gaussian (or sharper) error distributions in comparison with the typical SECS method. A more Gaussian profile is suggestive of less systematic error and more random or sampling error. An example of such sampling error would be a known decimal point rounding issue within the KMH dataset used. For the line element ECS implementations, either as is or incorporating the dECS methodology, there is marginal improvement in $B_y$ but large additional improvement in $B_x$. Similar to Table , $B_x$ is linked to the better choice of representative basis function describing dominant east-west magnetospheric currents. Estimation of $B_y$ on the other hand improves with the inclusion of more localized B-field measurements.

The results presented above make use of all available data points during the four geomagnetic storms. When considering the space weather effects of geomagnetic storms, then not all storms are the same. Simply put, larger geomagnetic storms create larger B-field perturbations, which drive larger ground effects. B-field interpolation that aims to estimate equivalent current systems also does better when the driving current systems are stronger. At mid-latitudes, the driving magnetospheric ring currents are directly related to geomagnetic storm magnitude. Considering the period of greatest geomagnetic driving over the available data as such may show improved interpolation accuracy relative to validation that includes quiet time. Using the June 2015 storm data alone, we find higher P-scores of 0.86 and 0.76 relative to using the entire dataset for base SECS interpolation of $B_x$ and $B_y$ respectively. Updating the interpolation to the line element ECS implementation improves the respective P-scores to 0.98 and 0.87. The improved representation of the stronger magnetospheric current driving is very clearly evident in the high P-score across both implementations. Further, using an infinite line current implementation described in results in P-scores of 0.96 and 0.87. It is worth noting that even this simple representation of magnetospheric current driving can result in accurate mid-latitude interpolation during geomagnetic storms.

# Discussion

The adaptations to previous geomagnetic field interpolation proposed in this paper do not nullify the contributions made by previous research using past implementations of SECS in Southern Africa. The validation of the previous implementation of SECS that shows the scheme to be as good as using local variometer measurements supports the technique as a mathematical transfer function. One of the greatest strengths of using a physically consistent equivalent current system for B-field interpolation however lies in its representativeness. In this sense it has not been possible to reconcile a physically relevant mid-latitude equivalent current system to the accuracy of interpolation using the implementation.

The need for representativeness has led to the development of the line current element ECS adaptation proposed. Using discrete line current elements, a physically relevant current system surface can be mapped at an appropriate height (as defined by $r<h$, where $r$ is the interpolation scale length). A representation of an equivalent current system as estimated using line current elements is shown in Figure . In the infinite line current approximation, the various estimates of infinite line currents as defined by current nodes need to be averaged to similarly represent an equivalent current system.

Extending the ECS representation of Figure , Figure shows the mean current element strength and direction, along with solar wind parameters and ground measurements. Evident is the link to the east-west direction of the magnetospheric ring current systems. In this sense we use the term magnetospheric ring current loosely and include the symmetric ring current (a global current system usually associated with the SYM-H index), partial ring current, magnetopause current and tail current. Additional current systems such as the substorm current wedge and field aligned currents add higher order effects . The equivalent current system as seen by ground measurements does not distinguish between different current systems and instead is linked to the net effective ground response. During quiet time and ahead of the coronal mass ejection (CME) plasma preceding the geomagnetic storm, the equivalent current magnitude is relatively weak and eastwards, likely related to the symmetric ring current. At onset of the geomagnetic storm, following the arrival of CME plasma and a southward (-$B_z$) interplanetary magnetic field (IMF) that initiates reconnection and particle injection, the westward magnetospheric current increases dramatically as expected. The strengthening of the net westward equivalent current corresponds to contributions first from tail current in the early main phase and then from the partial ring current, before giving rise to a strong symmetric westward ring current in the recovery phase .

Given the combination of sparse magnetometers (with a spacing of around 1,000 km in Southern Africa) and driving from distant magnetospheric currents, an equivalent current system height on the order of 5,000 km ($h$ being greater than the interpolation distances $r$) accurately interpolates the B-field over Southern Africa. As the height parameter is dependent on magnetometer spacing, for a denser magnetometer grid the current system height can be reduced. At mid-latitudes the reduced height and better resolution is unlikely to provide much benefit as the driving current systems remain dominated by magnetospheric currents that sit between 10,000 and 60,000 km . In testing the line element ECS interpolation approach, reflecting an actual magnetospheric height (i.e. $h\gg$ 5,000 km) provides only marginal improvement compared to $h=$ 5,000 km. In contrast, there were significant improvements in performance with increasing height from $h=$ 100 km, at which height there was no correlation between magnetometer sites and interpolation broke down entirely. At higher latitudes, where ionospheric auroral currents dominate, a denser magnetometer grid and lower height would be needed to maintain performance of the line elements implementation. Here the use of representative divergence-free current nodes instead of discrete line current elements greatly improves the efficiency of magnetometer measurements used and more accurately represents the current system dynamics at play. The traditional approach to SECS is as such best suited for high-latitudes, and the line element adaptation allows the equivalent current system approach of SECS interpolation to be used at mid-latitudes, such as in Southern Africa. Further work is required to validate the line element approach at high- and low-latitudes and determine where it possibly breaks down.

The proposed adaptation of including variometers in geomagnetic field interpolation has direct operational application. The dSECS methodology is independent of the basis functions used and focuses on interpolating $dB/dt$ directly, then merging the result with an initial B-field interpolation. The rate of change $dB/dt$ is extensively used in magnetotelluric (MT) studies, with $dB/dt$ related to the B-field by a factor $i\omega$ in the frequency domain. In modelling geomagnetically induced currents (GICs), frequency components need to be weighted correctly to reproduce GIC effective phenomena, like low-frequency geomagnetic pulsations . To do this, a low-pass filter related to the conductivity structure of the Earth needs to be applied to $dB/dt$ (which otherwise would be biased to the sampling rate of the underlying B-field measurements). With these aspects taken into account, $dB/dt$ interpolation can in effect be used as is. A caveat in $dB/dt$ interpolation is that when line element equivalent currents are used at an appropriate height, they are less sensitive to local variation in the B-field, i.e. contributions are dominated by magnetospheric currents which produces a smoother $dB/dt$ interpolation map but still an accurate B-field interpolation map.

With the increased need for real-time monitoring and modelling of GICs by utilities, dSECS and dECS provide an attractive approach to B-field estimation. The roll-out of low-cost instrumentation by a utility is much more feasible than installation and maintenance of observatory-grade magnetometers and additionally allows data access without the need for third party involvement. The low-cost of variometers has further application in research and citizen science . Although these instruments lack accuracy individually, leveraging a collection of them to estimate an equivalent current system can greatly improve estimation of the B-field at any single site, even at those sites where a variometer is situated (which in turn has application in validation of measurements). As more variometers are included in interpolation, the more accurate the resulting B-field estimations become. A secondary output of the dSECS methodology presented is the use an improved estimation of variation in a parameter to efficiently constrain a baseline estimate of the same parameter. Many fields face similar challenges where the variation in a parameter over time is more certain than its baseline estimation, making the approach presented more generally applicable.

# Conclusion

Due to the costs associated with maintaining observatory-grade magnetometers, it is not feasible to generate dense maps of geomagnetic field measurements. Interpolation of the geomagnetic field provides an attractive alternative that is widely used in research and operational contexts. Aside from the improved accuracy needed for operational modelling of geomagnetically induced currents, using a physically inspired interpolation scheme allows the equivalent currents to be interpreted. This paper presents two novel adaptations of previous geomagnetic field interpolation in Southern Africa. First, more widely available low-cost variometers are included to provide more accurate interpolation. A direct implication is that utilities and geomagnetic observatories can supplement their existing magnetometers for improved geomagnetic field estimation at a fraction of the cost. Secondly, an equivalent current system interpolation scheme using line current elements was developed for use at mid-latitudes. This approach is more representative of the driving current system at mid-latitudes compared with the more generally used divergence-free spherical elementary current systems (SECS). The implementation further allows simple analysis of the equivalent currents, not previously possible with an incorrect implementation of SECS in Southern Africa.

# Acknowledgments

The results presented in this paper rely on the data collected at Hermanus, Hartebeesthoek, Tsumeb and Keetmanshoop geomagnetic observatories. We thank SANSA for supporting their operation and INTERMAGNET (<https://www.intermagnet.org>) for promoting high standards of magnetic observatory practice. Further data from pulsation magnetometers and magnetotelluric sites operated by SANSA were used and are available through SANDIMS (<https://sandims.sansa.org.za/>). GFZ K-index data can be accessed through <https://doi.org/10.5880/Kp.0001>. The SYM-H index and interplanetary magnetic field measurements can be accessed through NASA/GSFC Space Physics Data Facility's OMNIWeb (or CDAWeb or ftp) service (<https://omniweb.gsfc.nasa.gov/>). This work was funded in part by a grant from the Open Philanthropy Project Fund, University of Cape Town and the South African National Space Agency.