For full docs please visit our readthedocs pages (note, still under development).
This package requires the following:
- Python 3
- HDF5 and h5py
- C++11 compatible compilers
- a POSIX operating system (no Windows, sorry)
The following may optionally be provided by your system, but if they aren't then this package will use internal versions of them
- yaml-cpp
- pybind11
In order to make sure everything will build properly when the installing the package via PyPI repositories, it is best to do local test installations as follows:
python setup.py sdist
pip install dist/pyscannerbit-0.0.1.tar.gz
This creates the source distribution tarball that is uploaded to PyPI, and
performs the installation directly from that. Following this procedure means
that nothing will accidentally get left out of the distribution tarball. If
you need to add new files to it, add them to the MANIFEST.in file.
If you have downloaded the source from github then feel free to use the developer installation instructions above. But you can also install this package via PyPI:
pip install pyscannerbit
This information is mainly for developers, but it might be helpful to know this
if you are having installation trouble (though if this is the case please file
or check the bug reports at https://github.com/bjfar/pyscannerbit/issues)
This package is primarily a Python interface to a C API that is built by the GAMBIT build system. This system in turn automatically downloads and build various scanning algorithm libraries and turns them into plugins for ScannerBit.
The tricky thing that needs to occur, which does not occur in a 'vanilla'
GAMBIT installation, is that various shared libraries need to be moved into
the final Python package installation path, whilst still being able to
find each other when Python loads them. This involves some careful handling
of their installation and rpath settings. If you are getting errors about
missing symbols when trying to import pyscannerbit, the reasons is probably
that something has gone wrong with this process. It is still a bit experimental,
so please file a bug report if you see such errors.
If you modify anything on the GAMBIT side, those changes will need to be manually imported into this package. This is done via the ScannerBit standalone tarball. So in the GAMBIT source do
cmake ..
make standalone_tarballs
then from this package run the script grab_ScannerBit.sh as follows
./grab_ScannerBit.sh <GAMBIT_SOURCE_ROOT>
and it will strip out contrib packages that we don't need, and then copy the stripped tarball into pyscannerbit/scannerbit.
NOTE! The GAMBIT version number is not automatically detected, so if
this changes it will need to be updated in the grab_ScannerBit.sh script.
Mostly for my own sake because I keep forgetting how to do this:
twine upload dist/pyscannerbit-x.x.x.tar.gz
Sometimes differences between the hdf5 version h5py comes with and the hdf5 version ScannerBit uses may cause ScannerBit to not load files or segfault. If this happens, try recompiling h5py using the system's hdf5 headers:
pip install --no-binary=h5py h5py --no-cache-dir --ignore-installed --user
You may need to specify a version with:
HDF5_VERSION=X.Y.Z pip install --no-binary=h5py h5py --no-cache-dir --ignore-installed --user
with X, Y, Z replaced by the version needed. To find the version ScannerBit uses, run (while NOT in the pyscannerbit directory):
python -c "from pyscannerbit import ext_module as ext; print(\"hdf5 version:\", ext.sb.get_hdf5_version())"
Also, on macs, especially if you're on a shared network drive, you may need to set:
export HDF5_USE_FILE_LOCKING=FALSE
Copyright (c) 2018, The GAMBIT Collaboration All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.