API Usage¶
This tools can be used as an API, from a python prompt or from a command line.
Steps:
Complete the configuration of the experiment
All the settings of the experimets are parsed from the configuration files using configparser.
run an experiment
process the experiment
show results
Configuration files¶
All parameters for the simulation are stored in a .ini file, for example:
[experiment]
# experiment ID
exp_ID = PHLX_02
[simu]
# internal GHZ radius, lyr
GHZ_inner = 20000.
# external GHZ radius, lyr
GHZ_outer = 60000.
# time span to simulate
t_max = 2.e6
#tau_awakeningS
tau_a_min = 2000
tau_a_max = 80000
tau_a_nbins = 10
# tau_surviveS
tau_s_min = 2000
tau_s_max = 80000
tau_s_nbins = 10
# Separate data in directories according to D_max
D_max_min = 20000
D_max_max = 20000
D_max_nbins = 1
# Number of realizations for each simulation
Nran = 10
# Parallel run
run_parallel = Y
Njobs = 10
[output]
dir_output = ../out/
dir_plots = ../plt/
pars_root = params
progress_root = progress
plot_fname = plot
plot_ftype = PNG
clobber = N
[UX]
show_progress = Y
verbose = Y
It is not possible to add, remove or change fields from this file, if so it will trigger failures in the testing process. The fields are organized in four categories:
- experiment
for the experiment ID. Each time a new ID is used, it will generate a new directory in the
dir_output
directory.- simu
for simulation parameters
- output
for the names of directories and files that store simulation results.
- UX
parameters related to the user experience
An example file is provided in the set
directory.
The details about the configuration parameters are given in Configuration.
Loading configuration¶
There are two approaches to loading the configuration parameters, that depend on how the code is run:
1. Command line call
The configiration file can be given throught the command line:
python run_experiment.py config_file.ini
In order for this to work, the script run_experiment.py must contain:
from hearsay import hearsay
from sys import argv
conf = hearsay.parser(argv)
2. Call from a python environment
When used from a python environment, it is possible to pass a filename as a string.
from hearsay import hearsay
config_file = 'config_file.ini'
conf = hearsay.parser(config_file)
If the parser
method is called without arguments, it will try to load
the file ../set/experiment.ini
which is distributed with the package.
Command line usage¶
For a simple test, go to src
and run:
$ python run_experiment.py ../set/experiment.ini
$ python process_experiment.py ../set/experiment.ini
$ python plot_experiment.py ../set/experiment.ini
It is important to use the same configuration file on these three steps, since parameters are used to build filenames.
If no name is given for a configuration file, it will use a dafault file
in ../set/experiment.ini
.
API usage¶
To use functionalities, import the hearsay
module:
from hearsay import hearsay
First, we must parse the configuration parameters from the .ini file.
All parameters with an assigned value must be read with the
configparser
module. The ConfigParser class is inherited in hearsay.parser
.
Variables can be accessed using the names of the sections and the names of the fields. For example, conf[‘simu’][‘t_max’].
There are several posibilities for loading the configuration parameters.
From the command line it is possible to give the name of the file containing the parameter settings:
python run_experiment.py < ../set/experiment.ini
In this case, the file must contain the following:
from sys import argv
conf = hearsay.parser(argv)
From the python interface, it is possible to give the filename as a string:
from hearsay import hearsay
conf = hearsay.parser('../set/experiment.ini')
Also, in the default case, the function hearsay.parser
can be
called without arguments, and the default configuration file will be
loaded:
from hearsay import hearsay
conf = hearsay.parser()
After the instantiation of a parser object without arguments, the default parameters can be overwritten with the specific methods:
from hearsay import hearsay
conf = hearsay.parser()
conf.check_file('../set/experiment.ini')
conf.read_config_file()
conf.load_filenames()
conf.load_parameters()
Finally, the simulation is made with the
hearsay.GalacticNetwork
class, where the function hearsay.GalacticNetwork.run_experiment()
makes
the computations.
G = hearsay.GalacticNetwork(conf)
G.run_experiment()
This function accepts the parallel
flag which indicates
a parallel version of the code will run:
G.run_experiment(parallel=True)
The analysis and visualization of the results can be done as follows:
R = hearsay.results(conf)
R.load()
res = R.redux_2d()
The method hearsay.results.redux_2d
computes the matrices.
A complete example of visualization is provided in the src
directory.