How to understand SPIS-NUM architecture
This page allows you to reach a basic
understanding of NUM architecture. Tools to browse SPIS-NUM code are first
described (Javadoc documentation and source browsing in Eclipse). The SPIS-NUM
architecture itself is sketched below, although its precise documentation can
only be reached by through the previous tools.
As in any Java code, the main source of
documentation is the Javadoc-generated html
documentation. It can be found in the DocSpisNum/API directory. You can start
html browsing from index.html or overview-tree.html (../API/public/index.html
or ../API/public/overview-tree.html). The first pages provide a project
overview, emphasising package and heritage structure of the classes. The other
pages, one per class, describe class constructors, fields and methods (summary
first, details below). Be inquisitive, try to click on the wealth of links
either generic (use, tree,
index, frames, etc. at pages top) or specific to each class
data (to argument class description, etc.).
The generation of this Javadoc documentation
in/from the source code is documented in the “How To program in Java for
SPIS-NUM” page (Java for NUM.html).
If you are a more advanced user and are editing
SPIS-NUM sources with Eclipse, use “Java Browsing”
perspective. The sources will appear grouped per package, which somewhat
reflect the code structure (see below). You will also be able to see Javadoc
information in small pop-ups (unfortunately limited in size, hence sometimes
truncated), or of course in the sources themselves. Navigation can be performed
by selecting packages or by hyper-text navigation (press ctrl key and click on a class, method, class variable…).
The top-level architecture of SPIS-NUM is
briefly sketched here. Its representation as a UML diagram is given in next section.
The top-level classes are contained in
spis.Top.Xxx packages and are the following:
-
The top level object is a simulation (Simulation parent class and derived classes), of which
all versions are contained in spis.Top.Simulation package:
-
Constructor: it requests the
volume and surface meshes (usually provided by SPIS framework, or read from a
file when SPIS-NUM is run as a standalone code, see Java for NUM.html).
-
Major methods:
-
integrate: compute time integration
-
a few pre-determined methods
to return results (see simulation abstract class interface)
-
Major fields: it basically
contains a Spacecraft and
a Plasma object (imposed from GenericSimulation
level, the class derived from Simulation parent class)
This top-most level object is normally called
by SPIS framework. It can yet be called by the main program of SPIS-NUM when it
is executed as a standalone code for debugging (see spis.Top.Top package
below).
-
A first object of
lower-level is a spacecraft (SC parent class and derived
classes), all contained in spis.Top.SC package:
-
Major methods:
-
integrate: compute time integration of spacecraft potentials
-
computeInteraction: compute plasma-material interactions on the spacecraft (secondary
emission, photo-emission, induced conductivity…)
-
Major fields: it basically
contains spacecraft Circuit, SurfMesh and surface fields (SurfField) describing the
spacecraft state (potential, etc.).
-
A second object of
lower-level is a plasma (plasma parent class and derived
classes), all contained in spis.Top.plasma package:
-
Major methods:
-
integrate: compute plasma dynamics
-
Major fields: it basically
contains the volume mesh, electric (and magnetic) fields and particle
populations. Different ways of defining populations are offered in different
plasma types (HybridPlasma1 or FlexiblePlasma)
Other classes of lower level are grouped in
lower level packages (only the major ones are mentionned):
-
packages spis.Vol.Mesh,
spis.Vol.Field and spis.Vol.Distrib: volume meshes, fields (values on a volume
mesh) and distributions (particle population, which can be
-
packages spis.Surf.Mesh,
spis. Surf.Field and spis. Surf.Distrib: quite similar for surfaces (spacecraft
or external boundary)
-
package spis.Surf.InteractModel:
plasma-material interaction models (still to be completed)
-
packages spis.Circ.*:
spacecraft circuit data
-
packages spis.Monitor.*:
monitoring objects (for now simple data storage for post-processing)
-
package spis.Solver.Poisson:
Poisson equation solver
-
packages spis.Util.*:
utilities, with in particular particle lists in spis.Util.List
-
package spis.Top.Default:
default objects and values (particle types, materials, sampling parameters…)
some of them being indeed global control parameters (only “verbose” flags for
now)
-
package spis.Top.Top: mostly
contains the "main"
program to run SPIS-NUM as a standalone code to debug it within Eclipse (a
menu, see Java for NUM.html)
As can be seen on the previous classes, it was
generally chosen to place derived classes in the same package as the
parent-class. The packages have all the same hierarchical level (spis + 2
levels): spis.Xxx.Yyy.