Mapof

This open-source, MIT-licensed package is a core part of the Mapof ecosystem. This framework allow for representing various features of (computational) problem instances in the context of the instance structure in a visually appealing way. Mapof is a direct successor of mapel, which will be deprecated in the (unforeseen) future.

Mapel is abandoned, long live Mapof!!!

We've successively substituted mapel packages present when we decided to start Mapof and have abandoned active development of mapel. Here is a map of the old and new projects:

1. mapel-core ==> Mapof
2. mapel-elections ==> Mapof-elections
3. mapel-roommates ==> Mapof-roommates
4. mapel-marriagess ==> Mapof-marriages

Hence, this package, Mapof, is a direct successor of mapel-core.

Installation of Mapof

There are in principle three (standard to python packages) ways to install Mapof. We strongly recommend installing the package from PyPi but you can also: use the code as a local package or install the package from the local code using some package manager.

Installation from PyPi

We recommend installing Mapof in a separate virtual environment (we use venv but any reasonable environment manager should do). Installation from Pypi with one of Python's package managers allows a seamless usage of Mapof with its remaining modules, that are to come soon, which all declare Mapof as dependency. A drawback is here that one cannot edit the Mapof code easily. If you use pip type pip install mapof to get the newest version and your are ready to go. If you use other package managers, do whatever it usually takes to install packages from PyPi. If pip drops executables into a user-local directory (for example ~/Library/Python/3.13/bin on macOS), add it to your shell PATH so commands like tqdm are available:

export PATH="$HOME/Library/Python/3.13/bin:$PATH"

Patching installation from PyPi

To patch function mapof.bar.foo you can define your own function my_foo and then assign it using mapof.bar.foo = mapof.bar.my_foo. If you do this before calling mapof.bar.foo, then each call to mapof.bar.foo will actually run your my_foo function.

Using code locally without package managers

Using the code as a local package is another option. Doing so, by downloading the package and importing different modules directly, comes with an easy way to edit Mapof files. However, it enforces usage of all other Mapof packages in the very same way. Trying installing other packages via some package manger will most likely result in that you will be using the manager-downloaded PyPi version of the Mapof module instead of your handcrafted one (there are workarounds, but you probably know these tricks very well if you ever want to take this path).

Using code locally with package manager

A somewhat compromise solution is to fork the repo and install the package into the package management system using your locally stored (perhaps edited) code. This might have a drawback that you need to update your installation after every change you make in the Mapof code.

However pip offers a handy solution here, the editable mode. Overall, using pip you can pass to pip install the path to the project (where pyproject.toml resides) and the -e switch. By this you get the best of two worlds Mapof is managed by pip and your modifications of the package are reflected immediately in the code that uses Mapof. This approach also have its limitations but in most cases it should just work well. In case you experience troubles, you should see what the pip documentation has to say about the editable mode.

Documentation

The complete documentation is available here.

Contribution

Feel free to contribute to Mapof using pull requests. We use black to enforce a coherent code style.

Acknowledgments

This project is part of the PRAGMA project which has received funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 101002854).