Commit b299f774 authored by Janne Solanpää's avatar Janne Solanpää
Browse files

Starting to improve documentation.

parent 7fc24067
......@@ -166,7 +166,7 @@ SET(ENABLE_TESTING ON CACHE BOOL "Enable_testing Option")
# TODO: This does not allow for cross-compilation. We should change this.
SET(ENABLE_VECTORIZATION ON CACHE BOOL "Enable_vectorization Option")
option(ENABLE_VECTORIZATION "Enables vectorization" [ON])
option(CROSSCOMPILING "Disables runtime checks" [OFF])
option(CROSSCOMPILING "Disables build-time checks" [OFF])
SET(SIMD_INSTRUCTIONS "SSE2 AVX" CACHE STRING "A space separated list of instructions supported by the target processor (used only when crosscompiling)")
string(TOUPPER "${SIMD_INSTRUCTIONS}" SIMD_INSTRUCTIONS)
separate_arguments(SIMD_INSTRUCTIONS)
......
29.1.2015
Reworked structure. User interface the same, things under the hood much more cleaner. Using c++14 features now.
28.05.2014
Parser options changed:
-simulations -> ensemble-size
New options:
- save-individual-dist-sqr: Calculation of diffusion coefficients:
Saves distance squared of each trajectory to 'savepath' as txt file.
29.01.2015 Version 1.0 ready.
28.05.2014 Preliminary release under GPLv3
......@@ -17,15 +17,7 @@ If your use of this software leads to a publication, please cite our paper [Comp
## Program
The Bill2d package consists (currently) of three binaries,
* bill2d for simulation of a single initial condition
* bill2d\_diffusion\_coefficient for calculating diffusion coefficients in peridic systems, and
* bill2d\_escape for calculating escape rates and survival probabilities of open billiard.
**bill2d** is the main binary, whereas the other two are here for your convenience,
we have already used them on research that led to publications. The installation
will also install **libbill2d** library and headers for you to write your own binaries.
The Bill2d package consists several binaries for specialized purposes. See USERGUIDE for more details and a tutorial.
In addition, the package contains several Python scripts for visualization and analysis of
the simulated data, e.g., trajectories, Poincaré sections, and energies, just to name
......@@ -50,8 +42,8 @@ Next, install the dependencies:
* Doxygen (optional, for building API docs)
* Pdflatex (optional, for building developer manual)
For scripts, you should install Python 2.7 or later of the version 2 branch,
and its packages:
For scripts, you should install Python 3,
and the following packages:
* Numpy (numpy.org)
* Matplotlib (matplotlib.org)
......@@ -59,10 +51,10 @@ and its packages:
If wish to run the unit tests, please make sure you have a working internet
connection before installing as we download Google Test and Google Mock
during compilation of the unit tests.
during installation.
### LINUX/UNIX/OS X:
### LINUX/UNIX/OS X
After installing the dependencies and making sure that they can be found
in the search paths of the compiler, you can run
......@@ -74,14 +66,11 @@ $ make install
to compile and install the Bill2d software package.
Note #1: If command 'make' fails,
run it again, we seem to have a small bug in the deployment scripts.
Note #1: If you get 'Illegal Instruction' when running the code, we've failed to correctly autodetect vectorization instructions supported by your processor. Use the CMake flag '-D SIMD_INSTRUCTIONS="SSE2 AVX"' to enable both SSE2 and AVX, and just drop one or both of them to disable those instructions. Use '-D CROSSCOMPILING=ON' to disable build time checks.
Note #2: If you get 'Illegal Instruction' when running the binaries, try using the option '-DENABLE_VECTORIZATION=OFF' for cmake (remember to clean up after first round of running cmake).
Note #3: If you have headers, libraries, and programs installed in non-standard paths, please tell them to CMake using the options CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, and CMAKE_PREFIX_PATH. For Boost, you also have BOOST_ROOT, BOOST_INCLUDEDIR, and BOOST_LIBRARYDIR. For HDF5, HDF5_ROOT. For GSL, GSL_ROOT_DIR. Example:
Note #2: If you have headers, libraries, and programs installed in non-standard paths, please tell them to CMake using the options CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, and CMAKE_PREFIX_PATH. For Boost, you also have BOOST_ROOT, BOOST_INCLUDEDIR, and BOOST_LIBRARYDIR. For HDF5, HDF5_ROOT. For GSL, GSL_ROOT_DIR. Example:
```
$ cmake -DBOOST_ROOT=/path/to/my/boost/directory
$ cmake -D BOOST_ROOT=/path/to/my/boost/prefix
```
### OTHER OPERATING SYSTEMS:
......@@ -111,16 +100,15 @@ $ make test
For examples and a short user guide, see the file USERGUIDE.
The API documentation is in the file docs/bill2d_api.pdf.
The API documentation is at docs/bill2d_api.pdf.
The developer manual is in the file docs/developer_manual.pdf.
The developer manual is at docs/developer_manual.pdf.
## Obtaining the latest release
The source code for bill2d is hosted at https://bitbucket.org/solanpaa/bill2d.
The latest source code for bill2d is hosted at https://gitlab.com/qcad.fi/bill2d.
## Copying / license
......
User guide
==========
The installation produces three binaries,
The installation produces several binaries:
bill2d,
bill2d_diffusion_coefficient,
bill2d_escape,
bill2d_phase_space_regularity, and
bill2d_phase_space_regularity_checker.
Some of these may not be built depending on the installation configuration and available libraries.
'bill2d' is used for simulation of a single initial condition
'bill2d' is used for time propagation of a single initial condition
'bill2d_diffusion_coefficient' is a binary with less functionality than
'bill2d'. It is used solely for the calculation of diffusion
'bill2d_diffusion_coefficient' is used solely for the calculation of diffusion
coefficients in periodic systems.
'bill2d_escape' is a binary used to calculate escape rates/survival
......@@ -20,71 +20,72 @@ probabilities of open billiards.
'bill2d_phase_space_regularity(_checker)' is a binary used for analyzing
the phase space.
All binaries obey the same options.
All binaries obey the same arguments.
Passing arguments
=================
In this section we explain how to use the 'bill2d'-binary. Most options
also work with 'bill2d_diffusion_coefficient' and 'bill2d_escape'.
also work with the other binaries.
Arguments can be passed via command line interface, e.g.
$ bill2d --table 1
```
bill2d --table 1
```
where argument '1' tells the binary to use a rectangular table with
default parameters.
Arguments can also be passed via configuration file, e.g.
```
input.txt
----------
table = 1
```
The configuration file must be passed via the 'config' command line flag
to the binary, i.e.
```
$ bill2d --config input.txt
```
List of arguments with explanations can be obtained with the flag
'--help'. The names in parenthesis, e.g. [ --num-particles ],
is to be used when writing input files.
'--help'.
Examples of input files can be found in the directory 'examples/'.
Arguments can be passed also as a combination of input file
and command line arguments, e.g.
```
$ bill2d --config <path_to_file> --delta-t 1e-6
```
If a given argument, e.g. 'delta-t' in the above example, exists also in
the configuration file, the value of the command-line argument is used.
Interrupting the simulation
===========================
A simple SIGINT (Ctrl+C) will tell the program to finish up as soon as possible.
This works for all three binaries. The data gathered so far is still saved.
This works for all binaries. The data gathered so far is still saved.
Billiard simulation
===================
To run a simple billiard simulation, try e.g.
$ bill2d --table 1 --billtype 2 --energy 0.5 --magnetic-field 1.43 --bounce-map --savepath data.h5
To run a simple billiard simulation for a single (random) initial condition, try e.g.
```
$ bill2d --table 1 --billtype 2 --energy 0.5 --magnetic-field 1.43 --poincare-section --savepath data.h5
$ draw_trajectories -f data.h5 &
$ draw_bounce_map -f data.h5
```
'draw_trajectories' plots the particle trajectories.
'draw_bounce_map' plots the bounce map / collision map / Poincare section
which was saved with '--bounce-map'.
'draw_poincare_section' plots the bounce map / collision map / Poincare surface of section
which was saved with '--poincare-section'.
See also the example input files:
examples/magnetic_square_billiards.config
......@@ -102,29 +103,42 @@ Python or Matlab.
Python
------
In python (examples for python 2), you need to use the h5py-package:
```
>> import h5py
>> file = h5py.File('data/bill2d.h5', 'r') #IMPORTANT TO USE 'r' to not to overwrite
```
All elements of the root level can be seen with command
>> file.keys()
```
>> list(file.keys())
```
Possible output: [u'kinetic_energy', u'parameters', u'potential_energy', u'trajectories']
If we wish list the datasets in the "trajectories"-group:
>> file["trajectories"].keys()
```
>> list(file["trajectories"].keys())
```
E.g., trajectory of particle nbr 1 can be obtained with:
```
>> trajectory = file["trajectories/particle1"][:]
```
The parameters are saved to the group "parameters" as attributes. You can
obtain the list of parameters with
```
>> file["parameters"].attrs.keys()
```
And to check the value of, say, attribute 'delta_t',
```
>> file["parameters"].attrs["delta_t"]
```
Finally, let's close the file:
```
>> file.close()
```
For more details on Python+HDF5, check h5py documentation.
......@@ -132,19 +146,29 @@ For more details on Python+HDF5, check h5py documentation.
Matlab
------
Load root group info:
```
>> info = h5info('data/bill2d.h5')
```
Check groups of root level:
```
>> info.Groups.Name
```
Check the parameters:
```
>> h5disp('data/bill2d.h5','/parameters')
```
List the datasets in the "trajectories"-group (here "trajectories was the second element from 'info')
``
>> info.Groups(2).Datasets
```
Load, e.g., the trajectory of particle nbr 1:
```
>> trajectory = h5read('data/bill2d.h5', '/trajectories/particle1');
```
For more details on Matlab+HDF5, check Matlab documentation.
......
......@@ -31,14 +31,14 @@ namespace bill2d {
// Start adding options
// generic=new po::options_description("Generic options");
generic_options.add_options()("help", "Show the help message")(
"config", po::value<std::string>(&d_plist.config_path), "Config file path");
"config", po::value<std::string>(&d_plist.config_path), "Path to the input file");
// simulation options
simulation_options.add_options()
("propagator", po::value<std::string>(&d_plist.propagator_string),
"For available propagators, see the USERGUIDE")
"For available propagators, see USERGUIDE")
("max-t", po::value<double>(&d_plist.max_t),
"Maximum simulation time")
......@@ -88,8 +88,8 @@ namespace bill2d {
("save-particlenum", po::value<bool>(&d_plist.save_particlenum)->default_value(false)->implicit_value(true),
"Save the number of particles as a function of time to file")
("bounce-map", po::value<bool>(&d_plist.save_bouncemap)->default_value(false)->implicit_value(true),
"Save bounce map / collision map")
("poincare-map", po::value<bool>(&d_plist.save_bouncemap)->default_value(false)->implicit_value(true),
"Save Poincare map / bouncing map / collision map")
("custom-psos", po::value<bool>(&d_plist.calculate_custom_psos)->default_value(false)->implicit_value(true),
"Calculate crossings with the custom Poincare section a*x+b*y+c = 0")
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment