hopsy is a versatile open-source domain-agnostic platform for (MCMC)-sampling convex polytopes
P = {x : Ax ≤ b},
which appear in many domains:
hopsy is a Python3 package powered by the C++ library HOPS.
Using pybind11 hopsy calls and extends HOPS with a range of useful features, bringing the performance of C++
and simplicity of Python together in one package.
Details and more use-cases are described here.
hopsy can be easily installed from the Python Package Index using pip install hopsy.
It is also possible to install the source dist on pypi in case there is no wheel for your particular OS yet.
Alternatively, you can download the source code from our GitHub repository with
git clone https://github.com/modsim/hopsy --recursive
Note the --recursive option which is
needed for hops, eigen and pybind11 submodules.
Next, compile either a binary wheel using pip
pip wheel --no-deps hopsy/
or use the standard CMake routine
mkdir hopsy/cmake-build-release && cd hopsy/cmake-build-release
cmake ..
make
Note however that the binary wheel produced from pip can be actually installed using pip, using
pip install hopsy-x.y.z-tag.whl
where the version x.y.z and tag tag will depend on the verison you downloaded and your build environment.
If you use the CMake routine, the compiled shared library will be located in build/ and can
be used within the directory.
To compile binary wheels for distribution (e.g. via the Python Package Index pypi.org), use the makewheels.sh script.
On Unix (Linux, OS X)
If you want to use the parallel tempering implemented in hops, you need a working MPI installation, because threads would not work due to the python GIL. The next step is to compile hopsy by source and to check that the script examples/parallel_tempering.py works. Both modes of the distribution should be found, otherwise there is some issue. In this case, please contact us.
In order to use parallel tempering, python interpreter must be called with MPI:
mpirun -np 10 parallel_tempering_application.py
In this case, 10 parallel chains would be constructed.
A basic usage example is presented below. More examples can be found in tests/ directory or in the docs.
import hopsy
import matplotlib.pyplot as plt
# the polytope is defined as
# P := {x : Ax <= b}
# thus we need to define A and b. these constraints form the simple box [0,5]^2.
A = [[1, 0], [0, 1], [-1, 0], [0, -1]]
b = [5, 5, 0, 0]
# next we construct a 2-dim standard Gaussian
model = hopsy.Gaussian(dim=2)
# the complete problem is defined by the target distribution and the constrained domain,
# defined by the above mentioned inequality
problem = hopsy.Problem(A, b, model)
# the run object contains and constructs the markov chains. in the default case, the
# Run object will have a single chain using the Hit-and-Run proposal algorithm and is
# set to produce 10,000 samples.
mc = hopsy.MarkovChain(problem, proposal=hopsy.GaussianHitAndRunProposal, starting_point=[.5, .5])
rng = hopsy.RandomNumberGenerator(seed=42)
# call sample on the mc and rng objects
acceptance_rate, states = hopsy.sample(mc, rng, n_samples=10_000, thinning=2)
# the states have 3 dimensions: number of chains, number of samples, number of dimensions.
plt.scatter(states[:, :, 0].flatten(), states[:, :, 1].flatten())
plt.show()
The development of hopsy primarily takes place on (JuGit)[https://jugit.fz-juelich.de/IBG-1/ModSim/hopsy], where we have access to powerful continuous integration and a Docker registry. The GitHub repository is only a mirror, so please report issues and make pull requests on JuGit. Please install pre-commit before commiting to our repository, see pre-commit step in .gitlab-ci.yml.
docs-sources$ make html # make will tell you which python packages you might be missing
docs-sources$ rm ../docs/* -r
docs-sources$ cp _build/html/* ../docs/ -r
docs-sources$ git add ../ docs && git commit -m "updated docs" && git push # and so on...
If you like hopsy and used it in your scientific work, please cite our paper
@article{10.1093/bioinformatics/btae430,
author = {Paul, Richard D and Jadebeck, Johann F and Stratmann, Anton and Wiechert, Wolfgang and Nöh, Katharina},
title = "{hopsy — a methods marketplace for convex polytope sampling in Python}",
journal = {Bioinformatics},
volume = {40},
number = {7},
pages = {btae430},
year = {2024},
month = {07},
issn = {1367-4811},
doi = {10.1093/bioinformatics/btae430},
url = {https://doi.org/10.1093/bioinformatics/btae430},
}
hopsy is licensed under the MIT license.
FAQs
A python interface for hops, the highly optimized polytope sampling toolbox.
We found that hopsy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.