mdpsolver 0.10.1__tar.gz → 0.10.3__tar.gz

{mdpsolver-0.10.1 → mdpsolver-0.10.3}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Anders Reenberg Andersen and Jesper Fink Andersen
+Copyright (c) 2026 Anders Reenberg Andersen and Jesper Fink Andersen
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{mdpsolver-0.10.1 → mdpsolver-0.10.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: mdpsolver
-Version: 0.10.1
-Summary: A fast solver for Markov Decision Processes
+Version: 0.10.3
+Summary: A fast Python solver for Markov Decision Processes
 Author-Email: Anders Reenberg Andersen <andersra@live.dk>, Jesper Fink Andersen <jesperfinkandersen@gmail.com>
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
@@ -31,7 +31,7 @@ MDPSolver is a Python package for large Markov Decision Processes (MDPs) with in
 
 # Installation
 
-Prebuilt wheels are available for **Linux**, **Windows**, and **macOS (14+)** across Python 3.10–3.14. Install directly from PyPI with:
+Install directly from PyPI with:
 
 ```
 pip install mdpsolver

{mdpsolver-0.10.1 → mdpsolver-0.10.3}/README.md

@@ -13,7 +13,7 @@ MDPSolver is a Python package for large Markov Decision Processes (MDPs) with in
 
 # Installation
 
-Prebuilt wheels are available for **Linux**, **Windows**, and **macOS (14+)** across Python 3.10–3.14. Install directly from PyPI with:
+Install directly from PyPI with:
 
 ```
 pip install mdpsolver

{mdpsolver-0.10.1 → mdpsolver-0.10.3}/pyproject.toml

@@ -15,12 +15,12 @@ CMAKE_BUILD_TYPE = "Release"
 
 [project]
 name = "mdpsolver"
-version = "0.10.1"
+version = "0.10.3"
 authors = [
   { name="Anders Reenberg Andersen", email="andersra@live.dk" },
   { name="Jesper Fink Andersen", email="jesperfinkandersen@gmail.com" },
 ]
-description = "A fast solver for Markov Decision Processes"
+description = "A fast Python solver for Markov Decision Processes"
 readme = "README.md"
 requires-python = ">=3.10"
 classifiers = [

{mdpsolver-0.10.1 → mdpsolver-0.10.3}/src/mdpsolver/model.py

@@ -24,6 +24,9 @@ class model:
     def initialize(self):
         """Create and initialize the solver module object."""
         self.mdl = solvermodule.Model()
+        # A model object contains only one model
+        self._modelDefined = False
+        self._solved = False
 
     def solve(
         self,
@@ -45,35 +48,63 @@ class model:
 
         Args:
             algorithm (str): Algorithm to use.
-            tolerance (float): Convergence threshold for the algorithm.
-            update (str): The value-update method.
+            tolerance (float): Convergence threshold for the algorithm (0 < tolerance < 1).
+            update (str): The value-update method ('standard', 'gs' or 'sor'; only 'standard' with the average reward criterion).
             criterion (str): The optimality criterion.
             parIterLim (int): The partial evaluation limit employed in the modified policy iteration algorithm.
             SORrelaxation (float): Relaxation parameter for the Successive Over-Relaxation method.
-            initPolicy (list): A 1D-list defining the initial policy. This option can be used for "warm starting" the optimization procedure.
-            initValueVector (list): A 1D-list defining the initial value vector. This option can be used for "warm starting" the optimization procedure.
+            initPolicy (list): A 1D-list defining the initial policy, one valid action index per state. This option can be used for "warm starting" the optimization procedure.
+            initValueVector (list): A 1D-list defining the initial value vector, one value per state. This option can be used for "warm starting" the optimization procedure.
             verbose (bool): If True, prints solver progress to console.
             postProcessing (bool): If True, performs post-processing after solving.
             makeFinalCheck (bool): If True, makes a final check of the value vector. This process checks if the resulting values are reasonable.
             parallel (bool): If True, enables parallel computation for faster solving. This option is only available for the custom MDP model with standard updates.
 
+        Solving the same model object again starts from the policy and the
+        value vector of the previous run, unless initPolicy or initValueVector
+        replace them. Create a new model object to start over.
+
         Returns:
             None
         """
         
         if not (algorithm == "mpi" or algorithm == "pi" or algorithm == "vi"):
             sys.exit("Error: Algorithm type not recognized. Select either: 'mpi', 'pi', or 'vi'.")
-        if tolerance <= 0.0:
-            sys.exit("Error: The tolerance needs to be a positive number.")
+        if tolerance <= 0.0 or tolerance >= 1.0:
+            sys.exit("Error: The tolerance needs to be between 0.0 and 1.0 (i.e. 0 < tolerance < 1).")
         if not (update == "standard" or update == "gs" or update == "sor"):
             sys.exit("Error: Update method not recognized. Select either: 'standard', 'gs', or 'sor'.")
         if not (criterion == "discounted" or criterion == "average"):
             sys.exit("Error: Optimality criterion not recognized. Select either: 'discounted' or 'average'.")
+        if criterion == "average" and (update == "gs" or update == "sor"):
+            sys.exit("Error: Gauss-Seidel and SOR updates are not available with the average reward criterion. Select update='standard'.")
         if parIterLim <= 0 and algorithm == "mpi":
             sys.exit("Error: The partial evaluation limit needs to be a positive number.")
         if (SORrelaxation <= 0.0 or SORrelaxation >= 2.0) and update == "sor":
             sys.exit("Error: The relaxation parameter needs to be between 0.0 and 2.0 (i.e. 0 < SORrelaxation < 2).")
-        
+        if len(initPolicy) > 0 or len(initValueVector) > 0:
+            numberOfStates = self.mdl.getNumberOfStates()
+            if numberOfStates >= 0 and len(initPolicy) > 0 and len(initPolicy) != numberOfStates:
+                sys.exit("Error: The initial policy needs one action index per state (the model has %d states, initPolicy has %d elements)." % (numberOfStates, len(initPolicy)))
+            if numberOfStates >= 0 and len(initValueVector) > 0 and len(initValueVector) != numberOfStates:
+                sys.exit("Error: The initial value vector needs one value per state (the model has %d states, initValueVector has %d elements)." % (numberOfStates, len(initValueVector)))
+            if numberOfStates >= 0 and len(initPolicy) > 0:
+                for stateIndex, action in enumerate(initPolicy):
+                    numberOfActions = self.mdl.getNumberOfActions(stateIndex=stateIndex)
+                    if not 0 <= action < numberOfActions:
+                        sys.exit("Error: The initial policy assigns action %s to state %d, which has %d actions (indices 0 to %d)." % (action, stateIndex, numberOfActions, numberOfActions - 1))
+
+        # The solver keeps the policy and the value vector of the previous run,
+        # unless initPolicy or initValueVector replace them.
+
+        if self._solved:
+            # Value iteration never uses the policy it starts from
+            reusesPolicy = len(initPolicy) == 0 and algorithm != "vi"
+            reusesValueVector = len(initValueVector) == 0
+            if reusesPolicy or reusesValueVector:
+                print("Note: This model has been solved before. Create a new model object to run solver with initial values.", flush=True)
+        self._solved = True
+
         self.mdl.solve(
             algorithm=algorithm,
             tolerance=tolerance,
@@ -98,6 +129,17 @@ class model:
         """
         return self.mdl.getRuntime()
 
+    def getIterations(self) -> int:
+        """
+        Get the number of iterations of the last solver execution.
+        An iteration is one policy improvement step, i.e. one update that
+        chooses the best action in every state.
+
+        Returns:
+            int: Number of iterations.
+        """
+        return self.mdl.getIterations()
+
     def printPolicy(self) -> None:
         """Print the entire policy to the terminal."""
         self.mdl.printPolicy()
@@ -191,13 +233,21 @@ class model:
             tranMatColumns (list): Sparse transition probabilities (option 2, part 2). A 3D-list containing the columns of the non-zero transition probabilities.
             tranMatFromFile (str): Load the transition probabilities from a comma-separated (,) file.
 
+        A model object holds one model, so mdp() can be called only once per
+        model object. Create a new model object to define another model.
+
         Returns:
             None
         """
         
+        if self._modelDefined:
+            sys.exit("Error: A model has already been defined for this model object, and mdp() can only be called once per model object. Create a new model object (e.g. mdl = mdpsolver.model()) to define another model.")
         if discount <= 0.0 or discount >= 1.0:
             sys.exit("Error: The discount needs to be in the interval between 0.0 and 1.0 (i.e. 0 < discount < 1).")
         
+        # Set before loading, so that a load that fails halfway cannot be
+        # followed by another into the same object
+        self._modelDefined = True
         self.mdl.mdp(
             discount=discount,
             rewards=rewards,

mdpsolver-0.10.3/tests/knownsolutions.py

@@ -0,0 +1,300 @@
+'''
+PROBLEMS WITH KNOWN SOLUTIONS, AND EXACT SOLUTIONS, FOR THE TESTS IN THIS FOLDER.
+
+A problem is given as rewards[s][a] and transitions[s][a] = {next state:
+probability}, from which the tests build the arguments of mdp().
+
+The hub-and-spoke problem. In the hub (state 0) one either rests, for a reward
+REST per period, or starts one of three ventures, which succeeds with
+probability 1 - FAIL. Venture k (state k) pays R_k per period and ends with
+probability q_k per period, back in the hub; two of the ventures can also be
+quit, for nothing, back to the hub. All rewards are non-negative. With discount
+factor lambda, the hub is worth m/(1 - lambda), where m is the best of REST and
+lambda(1 - FAIL)R_k/(1 + lambda(q_k - FAIL)), the per-period worth of resting or
+of venture k; a venture is continued if R_k >= lambda(1 - q_k)m, and is then
+worth (R_k + lambda q_k v_hub)/(1 - lambda(1 - q_k)), and is quit otherwise,
+worth lambda v_hub. The constants are chosen so that the best choice in the hub
+moves from resting, to the short venture, to the long one as lambda grows, and
+the poor venture goes from continued to quit. Under the average-reward criterion
+the gain is the best of REST and (1 - FAIL)R_k/(1 + q_k - FAIL) (a renewal
+argument), and with the bias of the hub set to 0, a continued venture has bias
+(R_k - g)/q_k and a quit one -g.
+
+The secretary problem (Ferguson, 1989). NCANDIDATES candidates are seen one at
+a time in random order, and each can be selected, ending the search, or passed
+over for good; the aim is to select the best of all. The optimal rule passes
+over the first CUTOFF - 1 candidates and then selects the first one that is
+better than all before it, which wins with probability about 1/e (0.398690 for
+ten candidates). The states are a candidate's position i and whether it is the
+best so far, plus an absorbing state once a candidate is selected or none is
+left. The classical problem is undiscounted and MDPSolver discounts every step,
+but every candidate takes exactly one step, so a reward of (i/n)/lambda^(i - 1)
+for selecting candidate i undoes the discount exactly: the start state is worth
+the classical probability of winning at every lambda, and candidate i's states
+are worth their classical values divided by lambda^(i - 1).
+
+The exact solutions of any problem: exactdiscounted() and exactaverage() run
+policy iteration with every policy evaluated exactly, by solving its linear
+equations, so they share no arithmetic with MDPSolver's iterative evaluation.
+checkoptimality() checks a solution against the optimality equation, with a
+margin for the optimal actions, and unichainaperiodic() the condition under
+which value iteration converges under the average-reward criterion (Puterman,
+1994, Section 8.5).
+
+References:
+    Ferguson, T. S. (1989). Who solved the secretary problem? Statistical
+    Science 4(3), 282-289. https://doi.org/10.1214/ss/1177012493
+    Puterman, M. L. (1994). Markov Decision Processes: Discrete Stochastic
+    Dynamic Programming. Wiley. https://doi.org/10.1002/9780470316887
+'''
+
+import itertools
+import sys
+
+import numpy as np
+
+
+# ------------------------------------------------------------------
+# THE HUB-AND-SPOKE PROBLEM
+# ------------------------------------------------------------------
+
+# The reward for resting in the hub, the probability that starting a venture
+# fails, and the ventures as (reward per period, probability of ending per
+# period, whether it can be quit): a short one, a long one and a poor one.
+REST = 2.0
+FAIL = 0.1
+VENTURES = ((6.0, 0.6, False),
+            (4.2, 0.05, True),
+            (1.5, 0.3, True))
+
+
+def hubproblem():
+    '''The rewards and transitions of the hub-and-spoke problem.'''
+    nventures = len(VENTURES)
+    rewards = [[REST] + [0.0] * nventures]
+    transitions = [[{0: 1.0}] + [{0: FAIL, k: 1.0 - FAIL} for k in range(1, nventures + 1)]]
+    for k, (reward, end, quittable) in enumerate(VENTURES, start=1):
+        rewards.append([reward] + ([0.0] if quittable else []))
+        transitions.append([{0: end, k: 1.0 - end}] + ([{0: 1.0}] if quittable else []))
+    return rewards, transitions
+
+
+def hubdiscounted(discount):
+    '''The optimal policy and values of the hub-and-spoke problem under discounting.'''
+    worths = [REST] + [discount * (1.0 - FAIL) * reward / (1.0 + discount * (end - FAIL))
+                       for reward, end, _ in VENTURES]
+    best = max(worths)
+    hub = best / (1.0 - discount)
+    policy, values = [int(np.argmax(worths))], [hub]
+    for reward, end, quittable in VENTURES:
+        if quittable and reward < discount * (1.0 - end) * best:
+            policy.append(1)
+            values.append(discount * hub)
+        else:
+            policy.append(0)
+            values.append((reward + discount * end * hub) / (1.0 - discount * (1.0 - end)))
+    return policy, np.array(values)
+
+
+def hubaverage():
+    '''The gain-optimal policy, the gain and the bias (0 in the hub) of the hub-and-spoke problem.'''
+    gains = [REST] + [(1.0 - FAIL) * reward / (1.0 + end - FAIL) for reward, end, _ in VENTURES]
+    gain = max(gains)
+    policy, bias = [int(np.argmax(gains))], [0.0]
+    for reward, end, quittable in VENTURES:
+        if quittable and reward < gain * (1.0 - end):
+            policy.append(1)
+            bias.append(-gain)
+        else:
+            policy.append(0)
+            bias.append((reward - gain) / end)
+    return policy, gain, np.array(bias)
+
+
+# ------------------------------------------------------------------
+# THE SECRETARY PROBLEM
+# ------------------------------------------------------------------
+
+NCANDIDATES = 10
+WINPROBABILITY = 0.398690   # for ten candidates (Ferguson, 1989), to six decimals
+
+
+def secretaryproblem(discount, compensated=True):
+    '''
+    The rewards and transitions of the secretary problem. State 2(i - 1) is
+    candidate i being the best so far, state 2(i - 1) + 1 it not being so, and
+    state 2n the end. A best-so-far candidate can be passed over (action 0) or
+    selected (action 1); any other is passed over. Compensated, the reward for
+    selecting candidate i undoes the discount of the i - 1 steps to it;
+    otherwise it is i/n whatever the discount.
+    '''
+    n = NCANDIDATES
+    end = 2 * n
+    rewards, transitions = [], []
+    for i in range(1, n + 1):
+        onward = {end: 1.0} if i == n else {2 * i: 1.0 / (i + 1), 2 * i + 1: i / (i + 1)}
+        rewards.append([0.0, (i / n) / (discount ** (i - 1) if compensated else 1.0)])
+        transitions.append([onward, {end: 1.0}])
+        rewards.append([0.0])
+        transitions.append([dict(onward)])
+    rewards.append([0.0])
+    transitions.append([{end: 1.0}])
+    return rewards, transitions
+
+
+def secretarysolution(discount):
+    '''
+    The optimal policy and values of the compensated secretary problem, from
+    the classical solution: W(m) = (m/n) sum_{k=m}^{n-1} 1/k is the probability
+    of winning by selecting the next best-so-far candidate after the m-th, and
+    the cutoff is the first candidate from which selecting a best-so-far one is
+    at least as good as going on. Returns the cutoff too.
+    '''
+    n = NCANDIDATES
+
+    def W(m):
+        return (m / n) * sum(1.0 / k for k in range(m, n))
+
+    cutoff = min(r for r in range(1, n + 1) if sum(1.0 / k for k in range(r, n)) <= 1.0)
+    policy, values = [], []
+    for i in range(1, n + 1):
+        onward = W(max(i, cutoff - 1))
+        scale = discount ** (i - 1)
+        policy += [1 if i >= cutoff else 0, 0]
+        values += [max(i / n, onward) / scale, onward / scale]
+    policy.append(0)
+    values.append(0.0)
+    return cutoff, policy, np.array(values)
+
+
+# ------------------------------------------------------------------
+# ANY PROBLEM
+# ------------------------------------------------------------------
+
+def densetranmat(transitions):
+    '''The transition probabilities as a 3D list with zeros, as tranMatWithZeros.'''
+    n = len(transitions)
+    return [[[probs.get(j, 0.0) for j in range(n)] for probs in state] for state in transitions]
+
+
+def elementwisetranmat(transitions):
+    '''The non-zero transition probabilities as rows [s, a, j, probability], as tranMatElementwise.'''
+    return [[s, a, j, p] for s, state in enumerate(transitions)
+            for a, probs in enumerate(state) for j, p in probs.items()]
+
+
+def matrices(rewards, transitions):
+    '''Per state, the rewards of its actions and the rows of their transition probabilities.'''
+    n = len(rewards)
+    R = [np.array(state, dtype=float) for state in rewards]
+    P = []
+    for state in transitions:
+        rows = np.zeros((len(state), n))
+        for a, probs in enumerate(state):
+            for j, p in probs.items():
+                rows[a, j] = p
+        P.append(rows)
+    return R, P
+
+
+def improve(R, P, policy, values, discount):
+    '''The greedy policy for the values, keeping an action that ties with the best.'''
+    improved = []
+    for s in range(len(R)):
+        q = R[s] + discount * (P[s] @ values)
+        best = int(np.argmax(q))
+        tie = q[policy[s]] >= q[best] - 1e-12 * max(1.0, abs(q[best]))
+        improved.append(policy[s] if tie else best)
+    return improved
+
+
+def exactdiscounted(rewards, transitions, discount):
+    '''The optimal policy and values under discounting, by policy iteration with exact evaluation.'''
+    R, P = matrices(rewards, transitions)
+    n = len(R)
+    policy = [int(np.argmax(r)) for r in R]
+    while True:
+        Ppolicy = np.array([P[s][policy[s]] for s in range(n)])
+        rpolicy = np.array([R[s][policy[s]] for s in range(n)])
+        values = np.linalg.solve(np.eye(n) - discount * Ppolicy, rpolicy)
+        improved = improve(R, P, policy, values, discount)
+        if improved == policy:
+            return policy, values
+        policy = improved
+
+
+def exactaverage(rewards, transitions):
+    '''
+    The gain-optimal policy, the gain and the bias (0 in state 0) of a unichain
+    problem, by policy iteration with exact evaluation: h + g = r + P h, h(0) = 0.
+    '''
+    R, P = matrices(rewards, transitions)
+    n = len(R)
+    policy = [int(np.argmax(r)) for r in R]
+    while True:
+        Ppolicy = np.array([P[s][policy[s]] for s in range(n)])
+        rpolicy = np.array([R[s][policy[s]] for s in range(n)])
+        A = np.zeros((n + 1, n + 1))
+        A[:n, :n] = np.eye(n) - Ppolicy
+        A[:n, n] = 1.0
+        A[n, 0] = 1.0
+        solution = np.linalg.solve(A, np.r_[rpolicy, 0.0])
+        bias, gain = solution[:n], solution[n]
+        improved = improve(R, P, policy, bias, 1.0)
+        if improved == policy:
+            return policy, gain, bias
+        policy = improved
+
+
+def qvalues(rewards, transitions, values, discount):
+    '''r(s, a) + discount * sum_j p(j | s, a) v(j) for every state and action.'''
+    R, P = matrices(rewards, transitions)
+    return [list(R[s] + discount * (P[s] @ np.asarray(values))) for s in range(len(R))]
+
+
+def checkoptimality(name, rewards, transitions, policy, values, discount, mingap, gain=0.0):
+    '''
+    Ends the test unless the values solve the optimality equation
+    v + g = max_a (r + discount P v), with the policy as the maximizer and every
+    maximum ahead of the runner-up by mingap.
+    '''
+    q = qvalues(rewards, transitions, values, discount)
+    scale = max(1.0, float(np.max(np.abs(values))))
+    for s in range(len(rewards)):
+        if abs(values[s] + gain - max(q[s])) > 1e-11 * scale:
+            sys.exit("Validation test failed at initialization: the known solution of the %s does not solve the optimality equation in state %d." % (name, s))
+        if int(np.argmax(q[s])) != policy[s]:
+            sys.exit("Validation test failed at initialization: the known policy of the %s does not maximize in state %d." % (name, s))
+        if len(q[s]) > 1 and sorted(q[s])[-1] - sorted(q[s])[-2] < mingap:
+            sys.exit("Validation test failed at initialization: in the %s the best action of state %d wins by only %.3e, so the comparison of policies would hinge on rounding." % (name, s, sorted(q[s])[-1] - sorted(q[s])[-2]))
+
+
+def smallestgap(rewards, transitions, values, discount):
+    '''The smallest margin by which the best action of a state beats its runner-up.'''
+    q = qvalues(rewards, transitions, values, discount)
+    gaps = [sorted(qs)[-1] - sorted(qs)[-2] for qs in q if len(qs) > 1]
+    return min(gaps) if gaps else np.inf
+
+
+def unichainaperiodic(rewards, transitions):
+    '''The first policy that is not unichain and aperiodic, or None. Enumerates every policy.'''
+    n = len(rewards)
+    for policy in itertools.product(*[range(len(r)) for r in rewards]):
+        step = np.zeros((n, n), dtype=np.int64)
+        for s in range(n):
+            for j, p in transitions[s][policy[s]].items():
+                step[s, j] = p > 0.0
+        reach = np.eye(n, dtype=np.int64)
+        for _ in range(n):
+            reach = np.minimum(reach + reach @ step, 1)
+        recurrent = [s for s in range(n) if all(reach[j, s] for j in range(n) if reach[s, j])]
+        classes = {frozenset(j for j in recurrent if reach[s, j] and reach[j, s]) for s in recurrent}
+        if len(classes) != 1:
+            return policy
+        members = sorted(next(iter(classes)))
+        power = sub = step[np.ix_(members, members)]
+        for _ in range(len(members) ** 2):   # primitive: some power is positive
+            power = np.minimum(power @ sub, 1)
+        if not np.all(power > 0):
+            return policy
+    return None

mdpsolver-0.10.3/tests/loadmdpsolver.py

@@ -0,0 +1,148 @@
+'''
+LOADS MDPSOLVER FOR THE TESTS IN THIS FOLDER.
+
+Every test imports it before anything else from mdpsolver:
+
+    from loadmdpsolver import mdpsolver, finalline, quietly
+
+The tests run the Python code of mdpsolver in Python/src, so that they can be
+run from a clone without installing anything. The compiled solvermodule does
+not have to be copied there; it is loaded from the first of these places that
+has one:
+    1. Python/src/mdpsolver, if it has been copied there;
+    2. CPP_Source_Code/build, or CPP_Source_Code/build/Release on Windows,
+       where the CMake build of the wiki's Contribution guidelines puts it,
+       unless it is older than one of the C++ sources (which is when CMake
+       would rebuild it);
+    3. the installed mdpsolver package (pip install mdpsolver, or
+       pip install ./Python), whose C++ may be older than the working tree's.
+Only modules this Python can load are considered, so a build for another Python
+version or platform in a shared folder is passed over. The module must have
+every method that the Python code calls on it, or it is older than that code.
+When the module is not the one in Python/src, the final line of a test says
+where it came from. Copied away from the repository, as for a test of a built
+wheel, the tests find no Python/src and test the installed package as a whole.
+
+Also here: finalline(), the line a test prints when it has passed, and
+quietly(), which runs a function with everything the process prints captured,
+the output of the compiled module included.
+'''
+
+import ctypes
+import glob
+import importlib.machinery
+import importlib.metadata
+import importlib.util
+import os
+import re
+import sys
+import tempfile
+
+TESTDIR = os.path.dirname(os.path.abspath(__file__))
+SRCDIR = os.path.normpath(os.path.join(TESTDIR, "..", "src"))
+CPPDIR = os.path.normpath(os.path.join(TESTDIR, "..", "..", "CPP_Source_Code"))
+BUILDDIRS = (os.path.join(CPPDIR, "build"), os.path.join(CPPDIR, "build", "Release"))
+
+
+def compiledmodules(directory):
+    '''The files in a directory that this Python can load as solvermodule.'''
+    paths = [os.path.join(directory, "solvermodule" + suffix)
+             for suffix in importlib.machinery.EXTENSION_SUFFIXES]
+    return [path for path in paths if os.path.isfile(path)]
+
+
+SOLVERMODULENOTE = None   # said in the final line when the module is not in Python/src
+
+if not os.path.isdir(os.path.join(SRCDIR, "mdpsolver")):
+    SOLVERMODULENOTE = "Python/src was not found next to the test, so the installed mdpsolver was tested as a whole."
+
+elif not compiledmodules(os.path.join(SRCDIR, "mdpsolver")):
+    sources = glob.glob(os.path.join(CPPDIR, "*.cpp")) + glob.glob(os.path.join(CPPDIR, "*.h"))
+    newestsource = max(map(os.path.getmtime, sources), default=0.0)
+    builds = [path for directory in BUILDDIRS for path in compiledmodules(directory)]
+    currentbuilds = [path for path in builds if os.path.getmtime(path) >= newestsource]
+
+    if currentbuilds:
+        spec = importlib.util.spec_from_file_location("mdpsolver.solvermodule", currentbuilds[0])
+        solvermodule = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(solvermodule)
+        SOLVERMODULENOTE = "The compiled solvermodule was loaded from %s." % currentbuilds[0]
+
+    else:
+        # The installed package is imported as a whole, before Python/src is on
+        # the path, so that whatever it does to find the libraries its module
+        # links to is done. Everything but its compiled module is then forgotten.
+        try:
+            import mdpsolver
+        except ImportError:
+            sys.exit("Validation test failed at initialization: there is no compiled solvermodule for this Python in Python/src/mdpsolver or in %s%s, and mdpsolver is not installed. Build it as described in the wiki's Contribution guidelines." % (BUILDDIRS[0], " (only one older than the C++ sources)" if builds else ""))
+        solvermodule = mdpsolver.solvermodule
+        for name in [name for name in sys.modules if name.split(".")[0] == "mdpsolver"]:
+            del sys.modules[name]
+
+        try:
+            version = importlib.metadata.version("mdpsolver")
+        except importlib.metadata.PackageNotFoundError:
+            version = "(version unknown)"
+        SOLVERMODULENOTE = "The compiled solvermodule was that of the installed mdpsolver %s, %s, whose C++ may be older than that of the working tree." % (version, solvermodule.__file__)
+        if builds:
+            SOLVERMODULENOTE += " The one in %s is older than the C++ sources and was passed over." % os.path.dirname(builds[0])
+
+    # the Python code in Python/src imports the module as mdpsolver.solvermodule
+    sys.modules["mdpsolver.solvermodule"] = solvermodule
+
+sys.path.insert(0, SRCDIR)
+
+import mdpsolver
+
+if os.path.isdir(os.path.join(SRCDIR, "mdpsolver")) and not os.path.samefile(
+        os.path.dirname(os.path.abspath(mdpsolver.__file__)), os.path.join(SRCDIR, "mdpsolver")):
+    sys.exit("Validation test failed at initialization: mdpsolver was loaded from %s rather than from Python/src." % os.path.dirname(mdpsolver.__file__))
+
+# the compiled module must have every method that the Python code calls on it
+with open(sys.modules["mdpsolver.model"].__file__) as file:
+    called = sorted(set(re.findall(r"self\.mdl\.(\w+)", file.read())))
+missing = [name for name in called if not hasattr(sys.modules["mdpsolver.solvermodule"].Model, name)]
+if missing:
+    sys.exit("Validation test failed at initialization: the compiled solvermodule has no %s, which the Python code of mdpsolver calls, so it is older than that code. Rebuild it. (%s)" % (", ".join(missing), SOLVERMODULENOTE or "It was loaded from Python/src/mdpsolver."))
+
+
+def finalline(testfile):
+    '''The line a test prints when it has passed: its file name, and where the compiled module came from, if not from Python/src.'''
+    name = os.path.splitext(os.path.basename(testfile))[0]
+    if SOLVERMODULENOTE is None:
+        return "%s: All tests passed." % name
+    return "%s: All tests passed. (%s)" % (name, SOLVERMODULENOTE)
+
+
+try:
+    LIBC = ctypes.CDLL(None)   # the C library, to flush the output of the compiled module
+except (OSError, TypeError):
+    LIBC = None
+
+
+def flushall():
+    sys.stdout.flush()
+    sys.stderr.flush()
+    if LIBC is not None:
+        LIBC.fflush(None)
+
+
+def quietly(function):
+    '''Runs a function with everything the process prints captured; returns its result and the output.'''
+    flushall()
+    with tempfile.TemporaryFile() as capture:
+        saved = (os.dup(1), os.dup(2))
+        os.dup2(capture.fileno(), 1)
+        os.dup2(capture.fileno(), 2)
+        try:
+            result = function()
+        finally:
+            flushall()
+            os.dup2(saved[0], 1)
+            os.dup2(saved[1], 2)
+            os.close(saved[0])
+            os.close(saved[1])
+        capture.seek(0)
+        output = capture.read().decode(errors="replace")
+    return result, output