User guide


Required Python libraries

strees uses some Python libraries for the numerical computations as well as its output format and plotting. You have to have them installed and accesible to run strees:

  • NumPy and SciPy. See here for installation instructions for your operating system.
  • Matplotlib
  • h5py

For Linux and Mac OS X we recommend using the package repositories of your distribution or MacPorts/Homebrew for Macs.


strees is mostly written in Python but in order to speed up the code, C is used in the calculation of electrostatic interactions. For this purpose we built the mpolar library, which implements both Fast Multipole Method (FMM) calculations and direct, \(O(N^2)\) electrostatic computations.

This means that you have to compile the C code to obtain a mpolar library. You can do this by typing:


from the /src sub-directory.

Before you run the code, make sure that the mpolar library is accessible to the dynamic linker of your operating system. In Linux you achive that with:

export LD_LIBRARY_PATH=/path/to/your/

In Mac OS X, you do the same with:

export DYLD_LIBRARY_PATH=/path/to/your/

Running a simulation

Once the code is set up, you use the script to start a simulation:

python /path/to/ simulation.ini

where the file simulation.ini contains the input parameters of the simulation. See parameters for a list of all valid parameters with a short description.

Input files

Input files for the code are .ini files with key/value pairs. Here is an example:

run_name = %(input)s
out_file = %(input_dir)s/%(run_name)s.h5
desc = A canonical simulation with the standard parameter set

external_field = -1.5e6
tip_mobility = 0.09
end_time = 3.5e-07
time_step = 2.5e-10
branching_probability = 100.0
branching_sigma = 0.0001
conductor_thickness = 0.001
conductance = 9.6e-07
maxwell_factor = 9e9
fmm_threshold = 500000
max_charges_per_box = 200
multipolar_terms = 10
random_seed = 11
electrode_geometry = planar

The input file contains two sections:

  • [global] contains the parameters run_name, out_file and desc. In this section you can use substitutions. The code provides substitutions variables

    • %(input), containing the basename of the input file (i.e. if the input file is simulation.ini %(input) is replaced by simulation.
    • %(input_dir) is replaced by the directory containing the input file.
  • [parameters] contains all other parameters. In general you can specify these parameters in any unit system. In the example above we used SI units, so we set maxwel_factor=9e9. This is \(1/4\pi \varepsilon_0\).

Output files

The code produces a single output file per simulation, specified in the parameters.out_file() parameter. The output is a HDF5 file, organized as follows:

The file contains a single group, called main. This group contains attributes containing the input parameters used in the simulation as well as information about the running environment:

The command that was used to start the simulation.
The machine time when the simulation was started.
Human-readable version of timestamp
Login name of the user that run the simulation.
The name of the computer where the simulation run,

The group main contains a sub-group per saved timestep, with names 00000, 00001 and so forth. Each of these sub-groups contains a snapshot of the tree at the given time. The attributes of the groups are:

Simulated time of the snapshot.
Machine time when the snapshot was saved

The data is contained in these fields:

An \(N \times 3\) array containing the locations of all nodes \(i, i=0, 1, \dots N-1\).
The charge of each node.
The electrostatic potential of each node.
An array containing the index of the parent node of each node. The parent node is the immediate one further up the tree.
An estimation of the numerical error in the potentials \(\phi\).
An estimation of the numerical error in \(dq_i/dt\)


The script can be used to plot the results of a simulation for a quick inspection. Use it with:

python /path/to/ outputfile.h5 [steps] [options]


  • step indicates the step that you want to plot, such as 00300. You can also specify latest to see the latest snapshot. If you do not provide a step, the program will plot all the available steps.

  • options stands for a combination of these options:

    -h, --help

    Show a help message and exit.


    The reference step


    Open the matplotlib window?


    Plot the electric field instead of the charge?


    The reference step


    Print real and simulated times for each step


    Format of the output figures


    Plot only one projection


    Background color

If you do not set the --show option, the code will produce an output file named outputfile/outputfile_XXXXX.png, where XXXXX is the step index.

Table Of Contents

Previous topic

strees: Simulation of 3d streamer trees

Next topic

Source code documentation

This Page