High-Performance GISAXS (Grazing Incidence Small Angle X-ray Scattering)
Bug (what bug…?) reporting: Email: abhinav.sarje@gmail.com
The HipGISAXS software is only available to be downloaded and used by employees
of academic research institutions, not-for-profit research laboratories, or
governmental research facilities. Please read the accompanying LICENSE file
before downloading the software. By downloading the software, you are agreeing
to be bound by the terms of this Non-Commercial End User License Agreement.
This licensing information is also provided as a PDF file along with the documentation.
HipGISAXS has been successfully tested on the following platforms.
This software uses several third-party libraries, and they need to be installed and available in order to compile and run HipGISAXS.
For ease, if possible use the installations already available on your system, if any. Alternatively, download and install them yourself.
The following are the dependencies of this software:
libtiff should be built with C++ support enabled. Also, disable jpeg support unless you have JPEG libraries installed. Brief instructions on building libtiff are given in the appendix.
HipGISAXS|- README.md : Duh!|- LICENSE : This contains all the licensing information for HipGISAXS.|- SConstruct : Scons file for installation.|- SConscript : Scons file for installation.|- bin : This contains HipGISAXS binaries generated by compilation.|- build : A few Makefiles for various systems are provided in this.|- data : This provides some sample input shape definition files.|- doc : This will contain detailed documentation of HipGISAXS.|- examples : This contains some example input files in HiG format.|- extras : This contains some extra stuff such as syntax highlighting config for Vim.|- include : All the source headers are within this directory. It contains subdirectories.|- lib : The HipGISAXS library, libhipgisaxs.a, is generated here.|- man : This has the man pages.|- obj : All the object files generated during build are stored here.|- samples : This contains some samples on how to use the HipGISAXS library.|- src : This is the main source code directory. It contains many subdirectories.
To build the HipGISAXS application binary and static library, use scons. Make sure you are passing paths to all the dependencies through --extrapath= option of scons:
$ scons --extrapath=<path1>,<path2>,<etc>
To enable GPU support, use --with-cuda option:
$ scons --extrapath=<path1>,<path2>,<etc> --with-gpu
To enable MPI support, use --with-mpi option:
$ scons --extrapath=<path1>,<path2>,<etc> --with-gpu --with-mpi
or,
$ scons --extrapath=<path1>,<path2>,<etc> --with-mpi
The generated binary, hipgisaxs, will be located in the bin directory.
The generated static library, libhipgisaxs.a, will be located in the lib directory.
… and you are done. Go enjoy HipGISAXS!
NOTE: See Appendix at the end of this file for more detailed and customized building information.
Execute the binary with the input file as an argument. For example,
$ ./bin/hipgisaxs examples/01-pyramid.hig
The HipGISAXS binary takes as input a file in HiG format.
Please refer to detailed HipGISAXS documentation for details of the HiG format. Detailed information on the inputs is available at https://webhipgisaxs.lbl.gov
A few sample input files are located in the directory examples, with extensions .hig.
Update the input files as needed.
The main components in the input file to update are the following:
Shape name defines the input filename containing triangulated shape data.
It should point to the correct location of the file (relative path):
...shape = {...name = "data/flexrod.obj"} ...
This file needs to be either in HDF5 format or the OBJ format.
Some sample shape files are provided in the directory “data”, with extensions “.hd5”.
Output locatation needs to be defined as pathprefix and runname in the computation object:
...computation = {...pathprefix = ".",runname = "myflexrod",...} ...
The pathprefix is a relative path to a directory.
The runname is appended with a timestamp, and a directory by this resulting name is created in the directory specified by pathprefix.
All output files are stored in this generated directory.
Resolution alters the final image resolution, and also affects the run time:
...computation = {...resolution = [ 1000 500 ],...} ...
Obviously, simulations with lower resolutions finish faster.
Modify the provided input file templates as needed.
Please refer to the examples provided in the samples directory.
It contains simple code which uses the HipGISAXS library.
The corresponsing Makefile is also provided as a reference.
Once all the required software are available, use the scons command to build the binary. Example:
$ scons --extrapath=$PATHS_TO_SOFTWARE --with-mpi --with-cuda
On successful build, the binary will be generated in the bin directory, called hipgisaxs.
All required software, except libtiff are available as modules on Edison. An example set of modules you can load are given in the build/modules.edison file. You could just source this file:
$ source build/modules.edison
You will need to install libtiff. Please refer to the required software section above.
build/build-edison.sh. If needed, make sure the paths are correctly set, including your installation of libtiff. Since Edison requires cross compilation for its compute nodes, make sure the CC and CXX environment variables are also set. Example:
$ CC=cc CXX=CC scons --with-mpi --extrapath=$BOOST_ROOT,$TIFFDIR
NOTE: For those users who are member of the ‘als’ group at NERSC, an installation of libtiff is available under /project/projectdirs/als/local/tiff-4.0.6.
bin directory, called hipgisaxs.All required software, except libtiff are available as modules on Cori. An example set of modules you can load are given in the build/modules.cori file. You could just source this file:
$ source build/modules.cori
You will need to install libtiff. Please refer to the required software section above.
Build command is same as for the Edison system (see above), given in the build/build-edison.sh. If needed, make sure the paths are correctly set, including your installation of libtiff. Since Cori requires cross compilation for its compute nodes, make sure the CC and CXX environment variables are also set. Example:
$ CC=cc CXX=CC scons --with-mpi --extrapath=$BOOST_ROOT,$TIFFDIR
NOTE: For those users who are member of the als group at NERSC, an installation of libtiff is available under /project/projectdirs/als/local/tiff-4.0.6.
bin directory, called hipgisaxs.All required software as modules on Titan, except libtiff which is already installed systemwide. An example set of modules you can load are given in the build/modules.titan file. You could just source this file:
$ source build/modules.titan
An example build command is given in the build/build-titan.sh. If needed, make sure the paths are correctly set. Since Titan requires cross compilation for its compute nodes, make sure the CC and CXX environment variables are also set. Example:
$ CUDA_TOOLKIT_PATH=$CRAY_CUDATOOLKIT_DIR CXX=CC CC=cc scons --with-mpi --with-cuda --extrapath=$BOOST_DIR
On successful build, the binary will be generated in the bin directory, called hipgisaxs.
build/build-bragg.sh or build/build-andromeda.sh. If needed, make sure the paths are correctly set.Once all the required software are available, use the scons command to build the binary. Example:
$ scons --extrapath=/usr/local/cuda --with-mpi --with-cuda
On successful build, the binary will be generated in the bin directory, called hipgisaxs.
configure script to generate the required build files. C++ support should be enabled. Additionally, disable JPEG support unless you are willing to install JPEG libraries as well. Example:
$ ./configure --prefix=<my_install_path> --disable-zlib --disable-jpeg --enable-cxx
make:
$ make
<my_install_path>:
$ make install