Menu
▾
▴
Tree [7d070d] default tip / History
Read Me
Posgen
======
Posgen is a command-line tool for the manipulation and creation of
“POS” (position) files from Atom Probe Tomography (APT).
These POS files contain a list of x,y,z and mass-to-charge data,
which are in the form of a 3D point cloud (a series of points
in space). Using posgen a wide variety of “operations” can be
performed, where an operation is a small subroutine that works on this
point cloud. Operations in posgen include geometric operations (cutting,
scaling, rotating), compositional (obtain compositions or profiles, drop
unranged data), file format conversions (pos↔tapsim, pos↔text), data
synthesis (crystal generation), statistical analyses (clustering), etc.
The program is primarily aimed at users who undertake data analysis of
atom probe datasets, who would like to minimise the amount of computer
programming they need to undertake, whilst still being able to manipulate
datasets quickly.
Contributing
============
We are really intrested to hear what you have done with this program,
and any feedback or additions that you may have made. Please contact
us on our forums to tell us what neat things you have done:
http://sourceforge.net/p/apttools/discussion/
You can also email us at:
tehuser at users.sourceforge.net
Licence
=======
This program is distributed under the terms of the GNU General Public
Licence, version 3.0 or greater.
You may use this in your application, provided that if you distribute
your program, you make your program available under the same terms. These
terms are fully detailed in the COPYING file in this folder.
In summary, two important points are that you need to make the source code
for your program, and this library available to end users. End users must
also be free to similarly distribute the program You may not use technical
measures to prevent users from modifying or compiling the program.
Wikipedia Page:
https://en.wikipedia.org/wiki/GNU_General_Public_License
Dependencies:
============
For versions > 0.0.4, posgen now uses the shared library "libatomprobe"
* libatomprobe - https://hg.sr.ht/~mycae/libatomprobe
You may need to compile and install this library before you can compile posgen.
Further, posgen also requires the following development libraries,
at minimum. These are usually called *-dev or *-devel (e.g. libxml2-dev) when installing:
* libxml2
* qhull
* gsl
* muparser (optional)
* libatomprobe
To compile you will need:
* a C++ compiler (e.g. g++)
* make
Compiling Under Linux
=====================
In the following the intial "#" and "$" is not part of the command. Do not type it in, or cut and paste it.
it simply shows which lines are commands.
Debian/Ubuntu/Mint:
-install the dependencies using this command as administrator (root):
(if libatomprobe available from your installer, otherwise compile/install separately)
# apt install libatomprobe-dev
then:
# apt install libgsl-dev libqhull-dev libxml2-dev libiconv-dev g++ libmuparser-dev
Fedora/redhat/centos
(First compile & install libatomprobe)
# dnf install gsl-devel qhull-devel libxml2-devel libiconv-devel
Compiling Under OSX
===================
First compile libatomprobe using the instructions therein, the follow the below instructions.
We recommend using "MacPorts" to obtain the dependencies. First install
MacPorts, then install the dependencies like so:
$ sudo port install gsl qhull cmake gcc libxml2
$ make
Compiling Under Cygwin (For windows)
=====================
A windows version of the program can be compiled, to enable running
the program under windows.
Use cygwin (cygwin.com) to install the following libraries
libxml2
gsl
qhull
You will also need these programs to compile the program
g++
make
To compile, run :
make
This generates a .dll. You *must* either
install the library, or
have this in the library path (eg same folder) as the program you are trying to run
If you do not do this, the program will fail to load, due to a missing
dll.
== After installing overall dependencies ==
After installing dependencies:
Some dependencies may not be available or sufficiently up-to-date
to work. Specifically, posgen requires libatomprobe after Nov. 2021 to function.
Please manually install libatomprobe as needed from
https://hg.sr.ht/~mycae/libatomprobe
You will pobably need to install mercurial (hg) to retrieve the code
$ hg clone https://hg.sr.ht/~mycae/libatomprobe
Then follow the instructions there to build the dependency
- Compile the program
$ make
Changing options
=========
The build system used (CMake) is configured to produce a shared library
(.so or .dll file, depending on your system). However, there are several
options that can be changed:
If you wish to disable/enable any optional items such as:
- Parallelism
- Debugging
- Coverage
- Other language bindings
Supported targets for the make command are:
* debug - enable all debug checks
* quickdebug - enable some debug checks
* parallel - enable parallel algorithms
* optimal - compile with optimisations
* clean - remove compiled files
Testing the built program
===========
To compile under a unix environment, first install the requirements
(per above). Then, go to the top directory and run (ignore the $, this
just means a terminal):
$ make
Once this completes, you can run the unit tests with:
$ ./test.sh
This should not flag any errors. If you do see an error, contact us so we can debug it.
Building the documentation
=======================
The documentation for the program is available online (PDF) and in the repository (latex):
Online : http://apttools.sourceforge.net/manuals/posgen.pdf
The documentation can be also be generated using Latex. Install latex and run :
$ cd docs
$ pdflatex userguide.tex && bibtex userguide && pdflatex userguide.tex
from the top level of the project to generate the PDF.
========================
