kep-solver 4.0.0

A Python package for reading and solving single instances of kidney exchange problems.

kep_solver

This Python package is devoted to various algorithms, procedures and mechanisms that are useful when studying kidney exchange programmes in general. It is written and maintained by William Pettersson.

• Full documentation
• Pypi link

Requirements

kep_solver runs on Python 3.10 or higher. As long as you install via pip, all other requirements will be handled by pip

Quick start with notebooks

This package provides two sample notebooks in the notebooks folder. You can access either of these using MyBinder.

Please note that MyBinder, as a free service, does have limits on its use. For more intensive use, or where the privacy of the data you use is important, you can self-install using the following instructions.

Quick start self-install

Create a virtual environment for kep_solver

mkvirtualenv kep_solver

Install kep_solver

pip install kep_solver

Download a sample JSON file from https://kep-web.optimalmatching.com/static/jsons/sample-1.json

Run the following Python commands

# Import the required functions
from kep_solver.fileio import read_json
from kep_solver.programme import Programme
from kep_solver.model import TransplantCount

# Read some input
instance = read_json("sample-1.json")

# Create a transplant pool with one objective.
# We will allow cycles to have at most 3 donor/recipient pairs and allow chains
# to have have at most 2 donors (i.e., one non-directed donor and one
# donor/recipient pair).
programme = Programme([TransplantCount()],
                       description="My first KEP",
                       maxCycleLength=3,
                       maxChainLength=2)

# Solve our instance
solution, model = programme.solve_single(instance)

# Print the solution
for selected in solution.selected:
    print(f"Selected {selected}")

Current features

• Reading instance files (json and XML formats)

• Creation of compatibility graphs

• Solving for the following objectives (single, or hierarchical)

  • Maximise the number of transplants
  • Maximise the number of backarcs
  • Maximise the number of effective 2-way exchanges
  • Minimise the number of three-cycles
  • Maximise the score using the UK scoring mechanisms

While the above objectives are exactly those in use by NHSBT when running the UKLKSS (the UK national KEP), I do intend to add further objectives

Expected users

I expect this software to be useful to researchers. Depending on what questions you want answered, you can either test policy changes to determine how they affect the running of a KEP, or you can implement new models or objectives to see how they perform

Documentation

Full documentation for kep_solver can be found at https://kep-solver.readthedocs.io/en/latest/.

Interface

This is just a Python module for now, a web-interface that demonstrates a basic use case is viewable at https://kep-web.optimalmatching.com, and the source code for said website is online at https://gitlab.com/wpettersson/kep_web

Future plans

• More objective functions
• Supporting transnational pools
• Implementation of faster models and modelling techniques

Contributing

I welcome input from others, whether you have ideas for improvements or want to submit code. Details on contributing can be found in CONTRIBUTING.md. You can also get in touch directly, or raise an issue

Licensing

This software is licensed under the Affero GPL v3 License, as described in LICENSE.

TO THE EXTENT PERMITTED BY LAW, THIS SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

This software has been supported by the Engineering and Physical Sciences Research Council (EPSRC) grants EP/T004878/1 (Multilayer Algorithmics to Leverage Graph Structure) and EP/X013618/1 (KidneyAlgo: New Algorithms for UK and International Kidney Exchange).