kep_solver.pool module

Handling of KEP pools, which are just the rules, procedures and algorithms for a particular KEP.

class ModelledExchange(exchange, values)

Bases: object

An exchange as modelled, including its value for various objectives and any other relevant information.

__init__(exchange, values)

Constructor for ModelledExchange. Contains the Exchange object, and also the value of this exchange for the various objectives in this model.

Parameters:

  • exchange (Exchange) – The exchange

  • values (list[float]) – The value of this exchange for each objective

property exchange: Exchange

The underlying exchange.

property values: list[float]

The values of this exchange.

class Solution(exchanges, scores, possible, times, numSolutions)

Bases: object

A solution to one instance of a KEP. Contains the exchanges, and the set of objective values attained.

__init__(exchanges, scores, possible, times, numSolutions)

Constructor for Solution. This class essentially just stores any information that may be useful.

Parameters:

  • exchanges (list[ModelledExchange]) – the list of selected exchanges

  • scores (list[float]) – the list of scores achieved for each objective

  • possible (list[ModelledExchange]) – the set of possible exchanges, and their values for each objective

  • times (list[tuple[str, float]]) – The time taken for various operations. Each is a tuple with a string description of the action, and the time (in seconds)

  • numSolutions (list[int]) – Either an empty list (if solutions weren’t counted) or a list such that the i’th entry in the list is the number of distinct solutions found for the i’th objective

property times: list[tuple[str, float]]

Get the time taken for various operations. Each element of the returned list is a tuple where the first item is a string description of some operation, and the second item is the time taken in seconds.

Returns:

the list of times (and their descriptions)

property selected: list[ModelledExchange]

Get the selected solution.

Returns:

the list of exchanges selected.

property values: list[float]

Get the Objective values of the selected solution.

Returns:

the list of objective values

property possible: list[ModelledExchange]

Return a list of all the possible chains and cycles that may be selected as ModelledExchange objects that contain the value of said exchange for each objective.

Returns:

a list of cycles/chains as ModelledExchange objects

property numSolutions: list[int]

Return the number of optimal solutions found for each objective.

Returns:

a list of cycles/chains as ModelledExchange objects

class Pool(objectives, maxCycleLength, maxChainLength, description, build_alt_embed=0)

Bases: object

A KEP pool.

__init__(objectives, maxCycleLength, maxChainLength, description, build_alt_embed=0)

Constructor for Pool. This represents a set of objectives, and parameters for running matchings (such as maximum cycle and chain lengths).

Parameters:

  • objectives (list[Objective]) – the list of objectives

  • maxCycleLength (int) – The longest cycle length allowed.

  • maxChainLength (int) – The longest chain length allowed. Note that the length of a chain includes the non-directed donor.

  • description (str) – A description of this pool.

  • build_alt_embed (int) –

    Whether to build alternate and embedded exchanges. build_alt_embed can be set to any of the following:

    0: Don’t build alternate and embedded cycles. Faster, if you don’t need alternate and embedded cycles 1: Build all alternate and embedded cycles. 2: Build only those alternate and embedded cycles that NHSBT expects

property description: str

A description of this pool.

property objectives: list[Objective]

The list of objectives for this Pool.

property maxCycleLength: int

The maximum length of cycles in this pool.

property maxChainLength: int

The maximum length of chains in this pool. Note that this includes the non-directed donor, so a chain of length 1 only has a non-directed donor and no recipients.

solve_single(instance, *, maxCycleLength=None, maxChainLength=None, countSolutions=False, maxCount=None, solver=None)

Run a single instance through this pool, returning the solution, or None if no solution is found (e.g., if the solver crashes).

Parameters:

  • instance (Instance) – The instance to solve

  • maxCycleLength (Optional[int]) – The longest cycle allowed. If not specified, we use the default from the Pool

  • maxChainLength (Optional[int]) – The longest chain allowed. If not specified, we use the default from the Pool

  • solver – An instantiated PuLP solver. If empty, a CBC solver is created and used

Return type:

tuple[Optional[Solution], Model]

Returns:

A tuple containing a Solution object, or None if an error occured, as well as the model that was solved.