# User guide¶

## Installation¶

### 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.

### Compilation¶

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:

make


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/mpolar.so

In Mac OS X, you do the same with:

export DYLD_LIBRARY_PATH=/path/to/your/mpolar.so

## Running a simulation¶

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

python /path/to/grow_tree.py 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:

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

[parameters]
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:

command
The command that was used to start the simulation.
timestamp
The machine time when the simulation was started.
ctime
Human-readable version of timestamp
user
Login name of the user that run the simulation.
hostname
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:

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

The data is contained in these fields:

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

## Plotting¶

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

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

Where

• 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.

--ref=REF

The reference step

--show

Open the matplotlib window?

--field

Plot the electric field instead of the charge?

--print-parameters

The reference step

--print-times

Print real and simulated times for each step

--format=FORMAT

Format of the output figures

--single

Plot only one projection

--axisbg=AXISBG

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.