mdpsolver 0.12.0__tar.gz → 0.12.1__tar.gz

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/CPP_Source_Code/ModifiedPolicyIteration.cpp

@@ -73,6 +73,8 @@ ModifiedPolicyIteration::ModifiedPolicyIteration(double epsilon, string algorith
 	diverged(false),
 	outOfRangeState(-1),
 	outOfRangeValue(0.0),
+	gainLower(numeric_limits<double>::quiet_NaN()),
+	gainUpper(numeric_limits<double>::quiet_NaN()),
 	parIter(0)
 {
 	//check valid string input
@@ -194,6 +196,19 @@ void ModifiedPolicyIteration::solve(ModelType * mdl, Policy * ply, ValueVector *
     auto t2 = chrono::high_resolution_clock::now(); //stop time
 	duration = (double) chrono::duration_cast<chrono::nanoseconds>( t2 - t1 ).count() / 1e6;
 
+	//BOUNDS ON THE GAIN
+
+	//every loop ends with an improvement step, v' = Lv, whose smallest and largest change
+	//(diffMin and diffMax) bound the gain under the average reward criterion. The policy
+	//found chose its actions in that step, so its gain is an average of v'-v, weighted by
+	//its limiting distribution, and lies between them; the optimal gain is at least the
+	//policy's, and at most the same average for an optimal policy, which is at most diffMax.
+	//They hold for any v, so also when a limit stopped the loops.
+	if (useAvg) {
+		gainLower = diffMin;
+		gainUpper = diffMax;
+	}
+
 	//POST PROCESSING
 
 	//make sure v is the last updated vector if we use standard updates

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/CPP_Source_Code/ModifiedPolicyIteration.h

@@ -57,6 +57,8 @@ public:
     bool diverged; //the values became infinite or NaN, which ends the loops (a NaN norm passes their test)
     int outOfRangeState; //the first state with such a value (-1 if none)
     double outOfRangeValue; //and its value
+    double gainLower; //under the average reward criterion, a lower bound on the gain (NaN otherwise)
+    double gainUpper; //and an upper bound
     int getIterationLimit() { return iterLim; }
 
     //methods

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/CPP_Source_Code/ModuleInterface.cpp

@@ -342,7 +342,10 @@ void ModuleInterface::solve(string algorithm,
     results.outOfRangeState=solver.outOfRangeState;
     results.outOfRangeValue=solver.outOfRangeValue;
     results.iterationLimit=solver.getIterationLimit();
-        
+    //save the bounds on the gain (NaN under the discounted criterion)
+    results.gainLower=solver.gainLower;
+    results.gainUpper=solver.gainUpper;
+
 }
 
 void ModuleInterface::setInitPolicy(py::list initPolicy){
@@ -418,14 +421,114 @@ void ModuleInterface::printValueVector(){
     }
 }
 
-void ModuleInterface::saveToFile(string fileName, string type){
+//---------------------------------------
+//  SAVING: the policy or the value vector
+//---------------------------------------
+//saveToFile() writes the policy or the value vector to a NumPy .npy file (filetype "npy", the
+//default) or to a comma-separated file (filetype "csv"). The .npy file holds a 1D array with an
+//entry per state, as np.save writes it, so that np.load gives what getPolicy() (int64) and
+//getValueVector() (float64) return. The comma-separated file has a header line and a row per
+//state: the state index, then the action index or the value.
+
+namespace {
+
+//the start of an .npy file (version 1.0) of a 1D array of n numbers of the NumPy type (e.g.
+//"i8"), in the computer's byte order: the magic string, the version, the length of the
+//header, and the header, padded with spaces so that the numbers start at a multiple of 64
+//bytes, as np.save aligns them (see "LOADING: NumPy .npy files" for the format)
+string npyStart(const string& type, size_t n){
+    const uint16_t one = 1;
+    const char order = (*(const unsigned char*)&one == 1) ? '<' : '>';
+    string header = "{'descr': '" + string(1, order) + type + "', 'fortran_order': False, 'shape': (" + to_string(n) + ",), }";
+    header.append((64 - (10 + header.size() + 1) % 64) % 64, ' ');
+    header += '\n';
+    string start = "\x93NUMPY";
+    start += (char)1;
+    start += (char)0;
+    start += (char)(header.size() & 0xff);
+    start += (char)(header.size() >> 8);
+    return start + header;
+}
+
+//closes a file that has been written, and throws if any of it could not be written (e.g. on a
+//full disk)
+void closeWritten(ofstream& outFile, const string& fileName){
+    outFile.close();
+    if (outFile.fail()){
+        throw runtime_error("saveToFile(): failed to write the file " + fileName + ".");
+    }
+}
+
+}
+
+void ModuleInterface::saveToFile(string fileName, string type, string filetype){
+    bool policy;
     if (type.compare("policy")==0 || type.compare("p")==0){
-        savePolicyToFile(fileName,',');    
+        policy = true;
     }else if(type.compare("value")==0 || type.compare("values")==0 || type.compare("v")==0){
-        saveValueVectorToFile(fileName,',');
+        policy = false;
     }else{
         throw invalid_argument("saveToFile(): the type '" + type + "' is not recognized. Select either 'policy' or 'value'.");
     }
+    //the filetype in any case, e.g. "NPY"
+    const string given = filetype;
+    transform(filetype.begin(), filetype.end(), filetype.begin(), [](unsigned char c){ return (char)tolower(c); });
+    if (filetype.compare("npy")!=0 && filetype.compare("csv")!=0){
+        throw invalid_argument("saveToFile(): the filetype '" + given + "' is not recognized. Select either 'npy' or 'csv'.");
+    }
+    const bool npy = (filetype.compare("npy")==0);
+
+    //the file name, by default result.npy or result.csv. A name ending in .csv or .npy must
+    //agree with the filetype, as mdp() reads a file by its extension.
+    if (fileName.empty()){
+        fileName = "result." + filetype;
+    }
+    const string other = npy ? ".csv" : ".npy";
+    if (hasExtension(fileName, other)){
+        throw invalid_argument("saveToFile(): the file name " + fileName + " ends in " + other + ", but the filetype is '" + filetype + "'. Use filetype='" + other.substr(1) + "' to save a " + (npy ? "comma-separated" : "NumPy .npy") + " file.");
+    }
+
+    if (npy && policy){
+        savePolicyToNpy(fileName);
+    }else if (npy){
+        saveValueVectorToNpy(fileName);
+    }else if (policy){
+        savePolicyToFile(fileName,',');
+    }else{
+        saveValueVectorToFile(fileName,',');
+    }
+}
+
+void ModuleInterface::savePolicyToNpy(string fileName){
+    ofstream outFile(fileName, ios::binary);
+    if (!outFile.is_open()) {
+        throw runtime_error("saveToFile(): failed to open the file " + fileName + " for writing.");
+    }
+    //as int64, as getPolicy() returns it, converted a block of states at a time
+    const vector<int>& policy = problem.policy.policy;
+    const string start = npyStart("i8", policy.size());
+    outFile.write(start.data(), (streamsize)start.size());
+    vector<int64_t> block(min(policy.size(), (size_t)65536));
+    for (size_t first = 0; first < policy.size(); first += block.size()) {
+        size_t n = min(block.size(), policy.size() - first);
+        for (size_t k = 0; k < n; k++) {
+            block[k] = policy[first + k];
+        }
+        outFile.write((const char*)block.data(), (streamsize)(n * sizeof(int64_t)));
+    }
+    closeWritten(outFile, fileName);
+}
+
+void ModuleInterface::saveValueVectorToNpy(string fileName){
+    ofstream outFile(fileName, ios::binary);
+    if (!outFile.is_open()) {
+        throw runtime_error("saveToFile(): failed to open the file " + fileName + " for writing.");
+    }
+    const vector<double>& values = problem.valueVector.valueVector;
+    const string start = npyStart("f8", values.size());
+    outFile.write(start.data(), (streamsize)start.size());
+    outFile.write((const char*)values.data(), (streamsize)(values.size() * sizeof(double)));
+    closeWritten(outFile, fileName);
 }
 
 void ModuleInterface::savePolicyToFile(string fileName, char sep){
@@ -437,7 +540,7 @@ void ModuleInterface::savePolicyToFile(string fileName, char sep){
     for (int sidx = 0; sidx < problem.policy.policy.size(); sidx++) {
         outFile << sidx << sep << problem.policy.policy[sidx] << endl;
     }
-    outFile.close();
+    closeWritten(outFile, fileName);
 }
 
 void ModuleInterface::saveValueVectorToFile(string fileName, char sep){
@@ -449,7 +552,7 @@ void ModuleInterface::saveValueVectorToFile(string fileName, char sep){
     for (int sidx = 0; sidx < problem.valueVector.valueVector.size(); sidx++) {
         outFile << sidx << sep << problem.valueVector.valueVector[sidx] << endl;
     }
-    outFile.close();
+    closeWritten(outFile, fileName);
 }
 
 double ModuleInterface::getRuntime(){
@@ -473,6 +576,10 @@ py::dict ModuleInterface::getConvergence(){
     return(convergence);
 }
 
+py::tuple ModuleInterface::getGainBounds(){
+    return(py::make_tuple(results.gainLower, results.gainUpper));
+}
+
 int ModuleInterface::getNumberOfStates(){
     //the number of states of the general MDP model
     if (problem.problemType.compare("mdp")==0){

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/CPP_Source_Code/ModuleInterface.h

@@ -29,6 +29,7 @@
 #include <cstdint>
 #include <string>
 #include <iostream>
+#include <limits>
 
 #include "ModelType.h" //Generic model class
 #include "ModifiedPolicyIteration.h" //The solver
@@ -121,6 +122,9 @@ public:
         int outOfRangeState=-1;
         double outOfRangeValue=0.0;
         int iterationLimit=0;
+        //bounds on the gain under the average reward criterion (NaN after a solve under the discounted criterion)
+        double gainLower=numeric_limits<double>::quiet_NaN();
+        double gainUpper=numeric_limits<double>::quiet_NaN();
     } results;
 
     
@@ -192,8 +196,9 @@ public:
     int getNumberOfActions(int sidx); //returns the number of actions of a state of the general MDP model (-1 for the built-in models or a state outside the model)
     py::array_t<int64_t> getPolicy(); //returns the entire policy, as a NumPy array (a copy)
     py::array_t<double> getValueVector(); //returns the entire value vector, as a NumPy array (a copy)
-    void saveToFile(string fileName, string type); //save the policy or value vector to a file 
+    void saveToFile(string fileName, string type, string filetype); //save the policy or value vector to a NumPy .npy file or a comma-separated file (by default result.npy or result.csv when fileName is empty)
     py::dict getConvergence(); //whether the last solve converged, and if not, why
+    py::tuple getGainBounds(); //the lower and upper bound on the gain from the last solve under the average reward criterion
 
     //------ model check ------
 
@@ -224,6 +229,9 @@ private:
     //the elementwise formats from NumPy .npy files, read in blocks straight into the tables
     void loadRewardsFromNpy(string rewardsFromFile);
     void loadTranMatFromNpy(string tranMatFromFile);
+    //the policy or the value vector to a NumPy .npy file (a 1D array) or a comma-separated file
+    void savePolicyToNpy(string fileName);
+    void saveValueVectorToNpy(string fileName);
     void savePolicyToFile(string fileName, char sep);
     void saveValueVectorToFile(string fileName, char sep);
 

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/CPP_Source_Code/PythonModule.cpp

@@ -68,8 +68,9 @@ PYBIND11_MODULE(solvermodule, m) {
         .def("getValue", &ModuleInterface::getValue,"Returns a value from the optimized policy.",py::arg("stateIndex")=0)
         .def("getPolicy", &ModuleInterface::getPolicy,"Returns the optimized policy as a NumPy array.")
         .def("getValueVector", &ModuleInterface::getValueVector,"Returns the optimized value vector as a NumPy array.")
-        .def("saveToFile", &ModuleInterface::saveToFile,"Saves the optimized policy or value vector to a file.",py::arg("fileName")="result.csv",py::arg("type")="policy")
+        .def("saveToFile", &ModuleInterface::saveToFile,"Saves the optimized policy or value vector to a NumPy .npy file (filetype='npy') or a comma-separated file (filetype='csv'), in any case; an empty fileName saves to result.npy or result.csv.",py::arg("fileName")="",py::arg("type")="policy",py::arg("filetype")="npy")
         .def("getConvergence", &ModuleInterface::getConvergence,"Returns whether the last solve converged, and if not, why.")
+        .def("getGainBounds", &ModuleInterface::getGainBounds,"Returns the lower and upper bound on the gain from the last solve under the average reward criterion (NaN after a solve under the discounted criterion).")
         .def("checkModel", &ModuleInterface::checkModel,"Checks the general MDP model for malformed input; returns a description of each kind of problem found. Never called by mdp() or solve().",py::arg("tolerance")=1e-9);
 
 }

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mdpsolver
-Version: 0.12.0
+Version: 0.12.1
 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
@@ -49,7 +49,7 @@ MDPSolver is a Python package for large Markov Decision Processes (MDPs) with in
 | 5,000,000 | 500,000,000 | 6.3 GB | 5.03 s |
 | 10,000,000 | 1,000,000,000 | 12.7 GB | 13.0 s |
 
-Mean of 10 random models with 5 actions per state and 20 possible next states per state and action, loaded from NPY-files and solved by modified policy iteration under the discounted reward criterion with discount 0.9. Measured on an Apple M5 with 10 cores.
+Mean of 10 random models with 5 actions per state and 20 possible next states per state and action, loaded from NPY-files and solved by modified policy iteration under the discounted reward criterion with discount $\lambda=0.9$ and tolerance $\epsilon = 0.001$. Measured on an Apple M5 with 10 cores.
 
 # Installation
 

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/Python/src/mdpsolver/model.py

@@ -121,6 +121,8 @@ class model:
         # A model object contains only one model
         self._modelDefined = False
         self._solved = False
+        # The optimality criterion of the last run of solve()
+        self._criterion = None
 
     def _requireSolution(self, method):
         """
@@ -235,6 +237,7 @@ class model:
         # Set after the run, so that a run that did not finish leaves the
         # object without a solution
         self._solved = True
+        self._criterion = criterion
 
         convergence = self.mdl.getConvergence()
         hint = " Under the average reward criterion, this happens with periodic models." if criterion == "average" else ""
@@ -373,27 +376,106 @@ class model:
         return self.mdl.getValueVector()
 
     @_oneAtATime
-    def saveToFile(self, fileName: str = "result.csv", type: str = "policy") -> None:
+    def getGain(self, bound: str | None = None) -> float:
+        """
+        Get the gain, the long-run average reward per period, from the last
+        run of solve() under the average reward criterion.
+
+        The smallest and largest change of the values in the last iteration
+        of solve() are a lower and an upper bound on the gain: the gain of the
+        optimized policy and the optimal gain both lie between them. When
+        solve() has converged, the bounds are less than the tolerance apart,
+        so their midpoint is within half the tolerance of the gain.
+
+        Args:
+            bound (str): None for the midpoint of the bounds, 'lower' for the lower bound, or 'upper' for the upper bound (in any case).
+
+        Returns:
+            float: The gain, or the bound selected.
+
+        Raises RuntimeError if the last run of solve() used the discounted
+        reward criterion.
+        """
+        self._requireAverage("getGain", "gain")
+        if not (bound is None or (isinstance(bound, str) and bound.lower() in ("lower", "upper"))):
+            raise ValueError("Bound not recognized. Select either: None, 'lower', or 'upper'.")
+        lower, upper = self.mdl.getGainBounds()
+        if bound is None:
+            return (lower + upper) / 2.0
+        return lower if bound.lower() == "lower" else upper
+
+    @_oneAtATime
+    def getBias(self, stateIndex: int, referenceIndex: int = 0) -> float:
+        """
+        Get the bias (the relative value) of a state from the last run of
+        solve() under the average reward criterion, with the bias of a
+        reference state set to 0. Thus, the bias of a state is its value
+        minus the value of the reference state.
+
+        Args:
+            stateIndex (int): Index of the state.
+            referenceIndex (int): Index of the reference state, whose bias is 0.
+
+        Returns:
+            float: Bias of the given state.
+
+        Raises RuntimeError if the last run of solve() used the discounted
+        reward criterion, and IndexError for a state outside the model.
+        """
+        self._requireAverage("getBias", "bias")
+        numberOfStates = self.mdl.getNumberOfStates()
+        for name, index in (("state", stateIndex), ("reference state", referenceIndex)):
+            if not isinstance(index, numbers.Integral) or isinstance(index, bool):
+                raise TypeError("The %s needs to be an integer state index (got %r)." % (name, index))
+            if not 0 <= index < numberOfStates:
+                raise IndexError("The %s %d is outside the model, which has %d states (indices 0 to %d)." % (name, index, numberOfStates, numberOfStates - 1))
+        return self.mdl.getValue(stateIndex=int(stateIndex)) - self.mdl.getValue(stateIndex=int(referenceIndex))
+
+    def _requireAverage(self, method, quantity):
+        """
+        Raise RuntimeError unless the last run of solve() used the average
+        reward criterion.
+        """
+        self._requireSolution(method)
+        if self._criterion != "average":
+            raise RuntimeError("The %s is defined under the average reward criterion, but the last run of solve() used criterion='%s'. Call solve(criterion='average') first." % (quantity, self._criterion))
+
+    @_oneAtATime
+    def saveToFile(self, fileName: str | None = None, type: str = "policy", filetype: str = "npy") -> None:
         """
         Save the optimized policy or value vector to a file.
 
         Args:
-            fileName (str): Name of the output file.
+            fileName (str): Name of the output file. By default result.npy, or result.csv when filetype is 'csv'.
             type (str): Type of result to save ('policy' or 'value').
+            filetype (str): Type of file to save ('npy' or 'csv', in any case). 'npy' saves a NumPy .npy file of a 1D array with an entry per state, which np.load reads as the array getPolicy() (int64) or getValueVector() (float64) returns. 'csv' saves a comma-separated file with a header line and a row per state: the state index, then the action index or the value.
+
+        A file name ending in .csv with filetype 'npy', or in .npy with
+        filetype 'csv', raises a ValueError.
 
         Returns:
             None
         """
-        
+
         self._requireSolution("saveToFile")
         if not (type == "policy" or type == "value"):
             raise ValueError("Type not recognized. Select either: 'policy' or 'value'.")
+        # (in any case, e.g. "NPY")
+        if not (isinstance(filetype, str) and filetype.lower() in ("npy", "csv")):
+            raise ValueError("Filetype not recognized. Select either: 'npy' or 'csv'.")
+        filetype = filetype.lower()
+        if fileName is None:
+            fileName = "result." + filetype
+        # (mdp() reads a file by its extension)
+        other = ".csv" if filetype == "npy" else ".npy"
+        if str(fileName).lower().endswith(other):
+            raise ValueError("The file name %s ends in %s, but filetype is '%s'. Use filetype='%s' to save a %s file." % (fileName, other, filetype, other[1:], "comma-separated" if filetype == "npy" else "NumPy .npy"))
         error = _openError(fileName, "w")
         if error is not None:
             # (the argument type hides the built-in type())
             raise error.__class__("The file %s could not be opened for writing (%s)." % (fileName, error.strerror or error))
 
-        return self.mdl.saveToFile(fileName=fileName, type=type)
+        return self.mdl.saveToFile(fileName=fileName, type=type, filetype=filetype)
 
     @_oneAtATime
     def mdp(

mdpsolver-0.12.1/Python/tests/test_average.py

@@ -0,0 +1,313 @@
+'''
+UNIT TEST FOR THE GAIN AND THE BIAS UNDER THE AVERAGE REWARD CRITERION
+(model.getGain() and model.getBias()).
+
+Under the average reward criterion, solve() ends every algorithm with an
+improvement step v' = Lv. The smallest and largest change in that step, the
+smallest and largest entry of v' - v, bound the gain: the policy found chose
+its actions in that step, so its gain is an average of v' - v (weighted by its
+limiting distribution), and the optimal gain is at least the policy's and at
+most the largest entry (Puterman, 1994, Section 8.5). The bounds hold for any
+v, so also when solve() stops at a limit. getGain() returns their midpoint, and
+getGain(bound="lower") and getGain(bound="upper") the bounds themselves.
+
+The values grow by about the gain in every iteration, so only their
+differences are meaningful: they approach the differences between the biases
+of the states. getBias(s, referenceIndex=k) returns the value of state s
+minus the value of state k, the bias of state s with the bias of state k set
+to 0.
+
+Sub-tests:
+    Case 1: The hub-and-spoke problem of knownsolutions.py, whose gain is known
+            in closed form, under value iteration, policy iteration and
+            modified policy iteration, with serial and parallel computation, and
+            at a loose and a tight tolerance: the bounds contain the gain and
+            are less than the tolerance apart, getGain() is their midpoint and
+            lies within half the tolerance of the gain, and the run converged.
+    Case 2: Random unichain models, at a loose tolerance: the bounds contain
+            both the gain of the policy found and the optimal gain, each
+            computed exactly by solving linear equations.
+    Case 3: A periodic model, a cycle of three states with one action each,
+            where value iteration and the evaluation of policy iteration never
+            converge: solve() stops at its limit with a ConvergenceWarning, and
+            the bounds still contain the gain, while their midpoint does not
+            equal it.
+    Case 4: The hub-and-spoke problem and the random models of case 2, whose
+            biases are known (in closed form, and by solving linear
+            equations), at a tight tolerance, under every algorithm: for
+            every state and every reference state, the bias is a float, the
+            value of the state minus that of the reference state (so exactly
+            0 for the reference state itself), and lies within BIASTOL of the
+            known bias with that of the reference state subtracted. The
+            default reference state is state 0, and NumPy integers work as
+            well.
+    Case 5: getGain() and getBias() before solve() raise a RuntimeError, and
+            so do they after a run under the discounted criterion, also when
+            an earlier run on the same object was under the average criterion.
+            A run under the average criterion after a discounted one gives the
+            gain and the bias. The bound is selected in any case ("Lower",
+            "UPPER"), and any other bound raises a ValueError. A state or a
+            reference state outside the model raises an IndexError, and one
+            that is not an integer a TypeError.
+
+References:
+    Puterman, M. L. (1994). Markov Decision Processes: Discrete Stochastic
+    Dynamic Programming. Wiley. https://doi.org/10.1002/9780470316887
+
+mdpsolver is loaded by loadmdpsolver.py, which explains where the compiled
+solvermodule is taken from.
+'''
+
+import sys
+import warnings
+
+import numpy as np
+
+from loadmdpsolver import mdpsolver, finalline, quietly
+from knownsolutions import arrayinput, exactaverage, hubaverage, hubproblem, matrices
+
+
+# ------------------------------------------------------------------
+# INITIALIZATION
+# ------------------------------------------------------------------
+
+DISCOUNT = 0.9             # mdp() needs one; the average reward criterion ignores it
+TOLERANCES = (1e-3, 1e-9)  # a loose and a tight epsilon handed to solve()
+LOOSE = TOLERANCES[0]
+TIGHT = TOLERANCES[1]
+ROUNDING = 1e-12           # the margin for rounding when the bounds are compared with an exact gain
+BIASTOL = 1e-8             # how far a bias may lie from the known one at the tight tolerance (the errors are about 1e-10)
+
+ALGORITHMS = (("value iteration", "vi"), ("policy iteration", "pi"), ("modified policy iteration", "mpi"))
+
+HUBREWARDS, HUBTRANSITIONS = hubproblem()
+HUBGAIN, HUBBIAS = hubaverage()[1:]
+
+# Case 2: random models in which every action leads to state 0 with a
+# probability of at least MINPROB, so every policy is unichain (state 0 is in
+# its only recurrent class) and aperiodic (state 0 can stay in state 0)
+NSTATES, NACTIONS, NNEXT = 40, 3, 4
+MINPROB = 0.05
+SEEDS = range(5)
+
+# Case 3: a cycle 0 -> 1 -> 2 -> 0 with the reward CYCLEREWARD in state 2 only,
+# whose gain is CYCLEREWARD / 3, while the changes of a step are 0 and CYCLEREWARD
+CYCLEREWARD = 3.0
+CYCLEREWARDS = [[0.0], [0.0], [CYCLEREWARD]]
+CYCLETRANSITIONS = [[{1: 1.0}], [{2: 1.0}], [{0: 1.0}]]
+CYCLEGAIN = CYCLEREWARD / 3.0
+
+if not HUBGAIN > 0.0:
+    sys.exit("Validation test failed at initialization: the gain of the hub-and-spoke problem is %r, where it should be positive." % HUBGAIN)
+# the biases of the hub-and-spoke problem differ between the states by far
+# more than BIASTOL, so a wrong reference state cannot pass case 4
+if HUBBIAS[0] != 0.0 or np.min(np.abs(np.subtract.outer(HUBBIAS, HUBBIAS))[~np.eye(len(HUBBIAS), dtype=bool)]) < 100 * BIASTOL:
+    sys.exit("Validation test failed at initialization: the biases of the hub-and-spoke problem, %s, are not 0 in the hub and far apart." % HUBBIAS)
+if np.isclose(CYCLEGAIN, CYCLEREWARD / 2.0):
+    sys.exit("Validation test failed at initialization: the gain of the cycle equals the midpoint of its bounds, so case 3 could not tell them apart.")
+
+
+# ------------------------------------------------------------------
+# HELPER FUNCTIONS
+# ------------------------------------------------------------------
+
+def solve(rewards, transitions, **settings):
+    '''A new model object, solved under the average reward criterion; anything solve() prints ends the test.'''
+    def run():
+        mdl = mdpsolver.model()
+        mdl.mdp(discount=DISCOUNT, **arrayinput(rewards, transitions, bycolumn=True))
+        mdl.solve(criterion="average", **settings)
+        return mdl
+
+    mdl, output = quietly(run)
+    if output:
+        sys.exit("Validation test failed: solve() with %s printed %r." % (settings, output.strip()))
+    return mdl
+
+
+def bounds(mdl):
+    '''The lower bound, the midpoint and the upper bound that getGain() returns.'''
+    return mdl.getGain(bound="lower"), mdl.getGain(), mdl.getGain(bound="upper")
+
+
+def checkbounds(case, label, lower, upper, gain, what="the gain"):
+    '''Ends the test unless the bounds contain the gain.'''
+    if not (np.isfinite(lower) and np.isfinite(upper)):
+        sys.exit("Validation test failed at case %d: %s gives the bounds [%r, %r] on the gain." % (case, label, lower, upper))
+    if not (lower - ROUNDING <= gain <= upper + ROUNDING):
+        sys.exit("Validation test failed at case %d: %s gives the bounds [%.15g, %.15g], which do not contain %s, %.15g." % (case, label, lower, upper, what, gain))
+
+
+def randommodel(seed):
+    '''A random unichain and aperiodic model, as rewards[s][a] and transitions[s][a] = {next state: probability}.'''
+    rng = np.random.default_rng(seed)
+    rewards, transitions = [], []
+    for s in range(NSTATES):
+        rewards.append(list(rng.uniform(0.0, 10.0, NACTIONS)))
+        state = []
+        for a in range(NACTIONS):
+            others = rng.choice(np.arange(1, NSTATES), size=NNEXT - 1, replace=False)
+            probs = MINPROB + (1.0 - NNEXT * MINPROB) * rng.dirichlet(np.ones(NNEXT))
+            state.append({0: float(probs[0]), **{int(j): float(p) for j, p in zip(others, probs[1:])}})
+        transitions.append(state)
+    return rewards, transitions
+
+
+def policygain(rewards, transitions, policy):
+    '''The gain of a unichain policy, from h + g = r + P h with h(0) = 0.'''
+    R, P = matrices(rewards, transitions)
+    n = len(R)
+    A = np.zeros((n + 1, n + 1))
+    A[:n, :n] = np.eye(n) - np.array([P[s][policy[s]] for s in range(n)])
+    A[:n, n] = 1.0
+    A[n, 0] = 1.0
+    return np.linalg.solve(A, np.r_[[R[s][policy[s]] for s in range(n)], 0.0])[n]
+
+
+def raises(error, function):
+    '''Whether the function raises the error; returns the message, or None.'''
+    try:
+        function()
+    except error as raised:
+        return str(raised)
+    return None
+
+
+# ------------------------------------------------------------------
+# CASE 1: The hub-and-spoke problem, whose gain is known
+# ------------------------------------------------------------------
+
+for algorithmlabel, algorithm in ALGORITHMS:
+    for parallel in (False, True):
+        for tolerance in TOLERANCES:
+            label = "%s (parallel=%s, tolerance %g) on the hub-and-spoke problem" % (algorithmlabel, parallel, tolerance)
+            mdl = solve(HUBREWARDS, HUBTRANSITIONS, algorithm=algorithm, tolerance=tolerance, parallel=parallel)
+            if not mdl.hasConverged():
+                sys.exit("Validation test failed at case 1: %s did not converge." % label)
+            lower, middle, upper = bounds(mdl)
+            checkbounds(1, label, lower, upper, HUBGAIN)
+            if not upper - lower < tolerance:
+                sys.exit("Validation test failed at case 1: %s gives bounds %.3e apart, which is not less than the tolerance." % (label, upper - lower))
+            if middle != (lower + upper) / 2.0:
+                sys.exit("Validation test failed at case 1: %s gives getGain() = %.15g, where the midpoint of the bounds is %.15g." % (label, middle, (lower + upper) / 2.0))
+            if abs(middle - HUBGAIN) > tolerance / 2.0:
+                sys.exit("Validation test failed at case 1: %s gives getGain() = %.15g, which is %.3e from the gain %.15g, more than half the tolerance." % (label, middle, abs(middle - HUBGAIN), HUBGAIN))
+
+
+# ------------------------------------------------------------------
+# CASE 2: Random unichain models, against exact gains
+# ------------------------------------------------------------------
+
+for seed in SEEDS:
+    rewards, transitions = randommodel(seed)
+    optimalgain = exactaverage(rewards, transitions)[1]
+    for algorithmlabel, algorithm in ALGORITHMS:
+        label = "%s (tolerance %g) on random model %d" % (algorithmlabel, LOOSE, seed)
+        mdl = solve(rewards, transitions, algorithm=algorithm, tolerance=LOOSE, parallel=False)
+        if not mdl.hasConverged():
+            sys.exit("Validation test failed at case 2: %s did not converge." % label)
+        lower, middle, upper = bounds(mdl)
+        checkbounds(2, label, lower, upper, policygain(rewards, transitions, [int(a) for a in mdl.getPolicy()]), "the gain of the policy found")
+        checkbounds(2, label, lower, upper, optimalgain, "the optimal gain")
+        if not upper - lower < LOOSE:
+            sys.exit("Validation test failed at case 2: %s gives bounds %.3e apart, which is not less than the tolerance." % (label, upper - lower))
+
+
+# ------------------------------------------------------------------
+# CASE 3: A periodic model, where solve() stops at a limit
+# ------------------------------------------------------------------
+
+for algorithmlabel, algorithm in ALGORITHMS[:2]:   # (modified policy iteration would take 100 sweeps per iteration to its limit)
+    label = "%s on the three-state cycle" % algorithmlabel
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        mdl = solve(CYCLEREWARDS, CYCLETRANSITIONS, algorithm=algorithm, tolerance=LOOSE, parallel=False)
+    if mdl.hasConverged() or not any(issubclass(w.category, mdpsolver.ConvergenceWarning) for w in caught):
+        sys.exit("Validation test failed at case 3: %s converged or gave no ConvergenceWarning, where the cycle should stop it at its limit." % label)
+    lower, middle, upper = bounds(mdl)
+    checkbounds(3, label, lower, upper, CYCLEGAIN)
+    if abs(middle - CYCLEGAIN) < LOOSE:
+        sys.exit("Validation test failed at case 3: %s gives the midpoint %.15g, which equals the gain, where the bounds [%.15g, %.15g] should be too far apart for that." % (label, middle, lower, upper))
+
+
+# ------------------------------------------------------------------
+# CASE 4: The bias, against known biases
+# ------------------------------------------------------------------
+
+problems = [("the hub-and-spoke problem", HUBREWARDS, HUBTRANSITIONS, HUBBIAS)]
+for seed in SEEDS:
+    rewards, transitions = randommodel(seed)
+    problems.append(("random model %d" % seed, rewards, transitions, exactaverage(rewards, transitions)[2]))
+
+for problemlabel, rewards, transitions, knownbias in problems:
+    for algorithmlabel, algorithm in ALGORITHMS:
+        label = "%s (tolerance %g) on %s" % (algorithmlabel, TIGHT, problemlabel)
+        mdl = solve(rewards, transitions, algorithm=algorithm, tolerance=TIGHT, parallel=False)
+        if not mdl.hasConverged():
+            sys.exit("Validation test failed at case 4: %s did not converge." % label)
+        values = mdl.getValueVector()
+        for reference in range(len(rewards)):
+            for state in range(len(rewards)):
+                bias = mdl.getBias(state, referenceIndex=reference)
+                if not isinstance(bias, float) or bias != values[state] - values[reference]:
+                    sys.exit("Validation test failed at case 4: getBias(%d, referenceIndex=%d) after %s gives %r, where it should be the float value of state %d minus that of state %d, %r." % (state, reference, label, bias, state, reference, values[state] - values[reference]))
+                difference = abs(bias - (knownbias[state] - knownbias[reference]))
+                if difference > BIASTOL:
+                    sys.exit("Validation test failed at case 4: getBias(%d, referenceIndex=%d) after %s differs by %.3e from the known bias, which is more than %.1e." % (state, reference, label, difference, BIASTOL))
+        for state in range(len(rewards)):
+            if mdl.getBias(state) != mdl.getBias(state, referenceIndex=0):
+                sys.exit("Validation test failed at case 4: getBias(%d) after %s differs from getBias(%d, referenceIndex=0)." % (state, label, state))
+        if mdl.getBias(np.int64(2), referenceIndex=np.int64(1)) != mdl.getBias(2, referenceIndex=1):
+            sys.exit("Validation test failed at case 4: getBias() after %s gives another result with the NumPy integers 2 and 1 than with the integers." % label)
+
+
+# ------------------------------------------------------------------
+# CASE 5: Errors, the bound and the reference state
+# ------------------------------------------------------------------
+
+mdl = mdpsolver.model()
+mdl.mdp(discount=DISCOUNT, **arrayinput(HUBREWARDS, HUBTRANSITIONS, bycolumn=True))
+CALLS = (("getGain()", lambda: mdl.getGain()), ("getBias(1)", lambda: mdl.getBias(1)))
+for call, function in CALLS:
+    message = raises(RuntimeError, function)
+    if message is None or "solve()" not in message:
+        sys.exit("Validation test failed at case 5: %s before solve() gives %r, where it should raise a RuntimeError naming solve()." % (call, message))
+
+quietly(lambda: mdl.solve(tolerance=LOOSE))
+for call, function in CALLS:
+    message = raises(RuntimeError, function)
+    if message is None or "discounted" not in message:
+        sys.exit("Validation test failed at case 5: %s after a run under the discounted criterion gives %r, where it should raise a RuntimeError naming the criterion." % (call, message))
+
+# a run under the average criterion after the discounted one (the note that
+# the model has been solved before is printed)
+quietly(lambda: mdl.solve(tolerance=TIGHT, criterion="average"))
+lower, middle, upper = bounds(mdl)
+checkbounds(5, "a run under the average criterion after a discounted one", lower, upper, HUBGAIN)
+biases = np.array([mdl.getBias(s) for s in range(len(HUBREWARDS))])
+if float(np.max(np.abs(biases - HUBBIAS))) > BIASTOL:
+    sys.exit("Validation test failed at case 5: getBias() after a run under the average criterion that followed a discounted one gives %s, where the known bias is %s." % (biases, HUBBIAS))
+for name, expected in (("Lower", lower), ("LOWER", lower), ("upper", upper), ("Upper", upper), ("UPPER", upper), (None, middle)):
+    if mdl.getGain(bound=name) != expected:
+        sys.exit("Validation test failed at case 5: getGain(bound=%r) gives %r, where it should give %r." % (name, mdl.getGain(bound=name), expected))
+for name in ("middle", "", "low", 1, True):
+    if raises(ValueError, lambda: mdl.getGain(bound=name)) is None:
+        sys.exit("Validation test failed at case 5: getGain(bound=%r) does not raise a ValueError." % (name,))
+for index, error in ((-1, IndexError), (len(HUBREWARDS), IndexError), (1.0, TypeError), ("0", TypeError), (True, TypeError), (None, TypeError)):
+    for call, function in (("getBias(%r)" % (index,), lambda: mdl.getBias(index)),
+                           ("getBias(0, referenceIndex=%r)" % (index,), lambda: mdl.getBias(0, referenceIndex=index))):
+        if raises(error, function) is None:
+            sys.exit("Validation test failed at case 5: %s does not raise %s." % (call, error.__name__))
+
+# and a run under the discounted criterion again
+quietly(lambda: mdl.solve(tolerance=LOOSE))
+for call, function in CALLS:
+    if raises(RuntimeError, function) is None:
+        sys.exit("Validation test failed at case 5: %s after a discounted run that followed an average one does not raise a RuntimeError." % call)
+
+
+# ------------------------------------------------------------------
+# FINAL VALIDATION
+# ------------------------------------------------------------------
+
+print(finalline(__file__))

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/Python/tests/test_order.py

@@ -3,8 +3,9 @@ UNIT TEST FOR CALLING THE METHODS OF A MODEL OBJECT IN THE WRONG ORDER.
 
 A model object is used in three steps: mdp() defines the model, solve() solves
 it, and the output methods (getPolicy(), getValueVector(), getAction(),
-getValue(), getRuntime(), getIterations(), hasConverged(), printPolicy(),
-printValueVector() and saveToFile()) report the solution. checkModel() needs
+getValue(), getGain(), getBias(), getRuntime(), getIterations(),
+hasConverged(), printPolicy(), printValueVector() and saveToFile()) report
+the solution. checkModel() needs
 only mdp(). Before a solution exists, the solver
 holds a placeholder policy and value vector, a single -1 each, which the output
 methods used to return as if it were a solution: getPolicy() gave [-1] and
@@ -42,7 +43,10 @@ Sub-tests:
             getValueVector(), which are the known solution; printPolicy(),
             printValueVector() and the file of saveToFile() with them; and
             getIterations() and getRuntime() are a positive count and a time,
-            and hasConverged() is True.
+            and hasConverged() is True. The run is under the discounted
+            criterion, where getGain() and getBias() raise a RuntimeError
+            naming the average reward criterion (test_average.py tests them
+            under that criterion).
             A later run of solve() rejected by its own checks leaves the
             solution in place.
 
@@ -81,7 +85,7 @@ if NSTATES < 2 or -1 in HUBPOLICY or np.any(HUBVALUES == -1.0):
 tmpdir = tempfile.TemporaryDirectory()
 
 # The output methods, each with the arguments of a call
-OUTPUTFILE = os.path.join(tmpdir.name, "policy.csv")
+OUTPUTFILE = os.path.join(tmpdir.name, "policy.npy")
 OUTPUTMETHODS = {
     "getRuntime": dict(),
     "getIterations": dict(),
@@ -90,6 +94,8 @@ OUTPUTMETHODS = {
     "printValueVector": dict(),
     "getAction": dict(stateIndex=1),
     "getValue": dict(stateIndex=1),
+    "getGain": dict(),
+    "getBias": dict(stateIndex=1),
     "getPolicy": dict(),
     "getValueVector": dict(),
     "saveToFile": dict(fileName=OUTPUTFILE, type="policy"),
@@ -231,6 +237,12 @@ for rejected in (False, True):
     results, printed = {}, {}
     for method in OUTPUTMETHODS:
         removeoutputfile()
+        if method in ("getGain", "getBias"):
+            # (the gain and the bias exist under the average reward criterion only)
+            error, output = attempt(lambda: call(mdl, method))
+            if type(error) is not RuntimeError or "average" not in str(error) or output:
+                sys.exit("Validation test failed at case 3: %s() %s under the discounted criterion gave %r and printed %r, where it should raise a RuntimeError naming the average reward criterion and print nothing else." % (method, after, error, output.strip()))
+            continue
         try:
             results[method], printed[method] = quietly(lambda: call(mdl, method))
         except Exception as error:
@@ -254,11 +266,9 @@ for rejected in (False, True):
             or not np.allclose([float(line.split(": ")[1]) for line in lines], values, rtol=1e-5):
         sys.exit("Validation test failed at case 3: printValueVector() %s printed %r, where it should print the %d values of getValueVector()." % (after, printed["printValueVector"].strip(), NSTATES))
 
-    with open(OUTPUTFILE) as file:
-        rows = file.read().strip().splitlines()
-    expected = ["State_Index,Action_Index"] + ["%d,%d" % (s, a) for s, a in enumerate(policy)]
-    if rows != expected:
-        sys.exit("Validation test failed at case 3: saveToFile() %s wrote %r, where it should write %r." % (after, rows, expected))
+    saved = np.load(OUTPUTFILE, allow_pickle=False)
+    if list(saved) != policy:
+        sys.exit("Validation test failed at case 3: saveToFile() %s wrote %r, where it should write %r." % (after, list(saved), policy))
 
     iterations, runtime = results["getIterations"], results["getRuntime"]
     if not isinstance(iterations, int) or iterations < 1:

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/Python/tests/test_output.py

@@ -2,8 +2,9 @@
 UNIT TEST FOR THE OUTPUT OF A SOLVED MODEL: saveToFile(), getAction(),
 getValue() AND THE REPORT ON CONVERGENCE.
 
-saveToFile() writes the policy or the value vector to a comma-separated file.
-type="value" used to write nothing, since the compiled module knew only
+saveToFile() writes the policy or the value vector to a NumPy .npy file
+(filetype="npy", the default) or to a comma-separated file (filetype="csv");
+until 0.12.0 it wrote only comma-separated files. type="value" used to write nothing, since the compiled module knew only
 "values", and a file that could not be opened was reported on stderr only.
 getAction() and getValue() used to return -1 and 0.0 for a state outside the
 model, and 0.0 cannot be told from a real value; they now raise IndexError.
@@ -18,12 +19,20 @@ limit, when the values become infinite or NaN, or when the final check
 discount allow.
 
 Sub-tests:
-    Case 1: saveToFile() with type="policy" and type="value" writes a header
-            and one row per state, equal to getPolicy() and getValueVector()
-            (to the six significant digits written), replacing a file that is
-            there. An unknown type raises a ValueError, and a file in a folder
-            that does not exist raises a FileNotFoundError; neither writes a
-            file.
+    Case 1: saveToFile() with type="policy" and type="value" writes by
+            default an .npy file that np.load reads as the array of
+            getPolicy() (int64) or getValueVector() (float64), and with
+            filetype="csv" a header and one row per state, equal to them (to
+            the six significant digits written); both replace a file that is
+            there. Without a file name, it writes result.npy, or result.csv
+            with filetype="csv", in the working directory. The filetype may be
+            in any case, e.g. "NPY" or "Csv", also in the compiled module,
+            and a default name is then in lower case. An unknown type or
+            filetype, and a name ending in .csv with filetype="npy" or in .npy
+            with filetype="csv" (in any case), raise a ValueError, also in the
+            compiled module, whose message for a name names the filetype to
+            use; a file in a folder that does not exist raises a
+            FileNotFoundError. None of them writes a file.
     Case 2: getAction() and getValue() agree with getPolicy() and
             getValueVector() in every state, and raise an IndexError naming the
             index for a state outside the model.
@@ -137,6 +146,14 @@ def readrows(path):
         return file.read().strip().splitlines()
 
 
+def loadednpy(path):
+    '''The array np.load reads from an .npy file, or the exception it raises.'''
+    try:
+        return np.load(path, allow_pickle=False)
+    except Exception as error:
+        return error
+
+
 mdl, caught, output = solved(HUBMODEL)
 if output or caught:
     sys.exit("Validation test failed at initialization: solving the hub-and-spoke problem printed %r and warned %r." % (output.strip(), [str(w.message) for w in caught]))
@@ -149,29 +166,84 @@ if POLICY != HUBPOLICY or float(np.max(np.abs(np.array(VALUES) - HUBVALUES))) >
 # CASE 1: saveToFile()
 # ------------------------------------------------------------------
 
-for kind, header, column in (("policy", "State_Index,Action_Index", POLICY), ("value", "State_Index,Value", VALUES)):
-    path = os.path.join(tmpdir.name, "%s.csv" % kind)
+for kind, header, column, dtype in (("policy", "State_Index,Action_Index", POLICY, np.int64), ("value", "State_Index,Value", VALUES, np.float64)):
+    # The default filetype: the array of getPolicy() or getValueVector()
+    path = os.path.join(tmpdir.name, "%s.npy" % kind)
     with open(path, "w") as file:
         file.write("this file is replaced\n")
     error, output = raises(lambda: mdl.saveToFile(fileName=path, type=kind))
     if error is not None or output:
         sys.exit("Validation test failed at case 1: saveToFile(type=%r) raised %r and printed %r." % (kind, error, output.strip()))
+    array = loadednpy(path)
+    if not isinstance(array, np.ndarray) or array.dtype != dtype or array.shape != (NSTATES,) or not np.array_equal(array, column):
+        sys.exit("Validation test failed at case 1: saveToFile(type=%r) wrote a file that np.load reads as %r, where it should be the %s array %r." % (kind, array, np.dtype(dtype).name, column))
+
+    # filetype="csv": a header and a row per state
+    path = os.path.join(tmpdir.name, "%s.csv" % kind)
+    with open(path, "w") as file:
+        file.write("this file is replaced\n")
+    error, output = raises(lambda: mdl.saveToFile(fileName=path, type=kind, filetype="csv"))
+    if error is not None or output:
+        sys.exit("Validation test failed at case 1: saveToFile(type=%r, filetype='csv') raised %r and printed %r." % (kind, error, output.strip()))
     rows = readrows(path)
     if not rows or rows[0] != header or len(rows) != NSTATES + 1:
-        sys.exit("Validation test failed at case 1: saveToFile(type=%r) wrote %r, where it should write the header %r and %d rows." % (kind, rows, header, NSTATES))
+        sys.exit("Validation test failed at case 1: saveToFile(type=%r, filetype='csv') wrote %r, where it should write the header %r and %d rows." % (kind, rows, header, NSTATES))
     for s, row in enumerate(rows[1:]):
         index, entry = row.split(",")
         if int(index) != s or not np.isclose(float(entry), column[s], rtol=1e-5, atol=0.0):
-            sys.exit("Validation test failed at case 1: saveToFile(type=%r) wrote the row %r for state %d, where its %s is %r." % (kind, row, s, kind, column[s]))
-
-for label, given, expected in (("an unknown type", dict(type="values2"), ValueError),
-                               ("a file in a folder that does not exist", dict(type="policy"), FileNotFoundError)):
-    path = os.path.join(tmpdir.name, "missing" if expected is FileNotFoundError else "", "result.csv")
-    error, output = raises(lambda: mdl.saveToFile(fileName=path, **given))
-    if not isinstance(error, expected):
-        sys.exit("Validation test failed at case 1: saveToFile() with %s raised %r, where it should raise a %s." % (label, error, expected.__name__))
-    if output or os.path.exists(path):
-        sys.exit("Validation test failed at case 1: saveToFile() with %s printed %r or wrote a file." % (label, output.strip()))
+            sys.exit("Validation test failed at case 1: saveToFile(type=%r, filetype='csv') wrote the row %r for state %d, where its %s is %r." % (kind, row, s, kind, column[s]))
+
+# Without a file name: result.npy or result.csv in the working directory (in
+# lower case also for a filetype in upper case)
+folder = os.path.join(tmpdir.name, "defaults")
+os.mkdir(folder)
+here = os.getcwd()
+os.chdir(folder)
+try:
+    results = [raises(lambda: mdl.saveToFile(type="value")), raises(lambda: mdl.saveToFile(type="value", filetype="CSV"))]
+finally:
+    os.chdir(here)
+for (error, output), given in zip(results, ("", ", filetype='CSV'")):
+    if error is not None or output:
+        sys.exit("Validation test failed at case 1: saveToFile(type='value'%s) without a file name raised %r and printed %r." % (given, error, output.strip()))
+if sorted(os.listdir(folder)) != ["result.csv", "result.npy"]:
+    sys.exit("Validation test failed at case 1: saveToFile() without a file name wrote %s, where it should write result.npy, and result.csv with filetype='csv'." % sorted(os.listdir(folder)))
+array, rows = loadednpy(os.path.join(folder, "result.npy")), readrows(os.path.join(folder, "result.csv"))
+if not isinstance(array, np.ndarray) or not np.array_equal(array, VALUES) or rows[0] != "State_Index,Value" or len(rows) != NSTATES + 1:
+    sys.exit("Validation test failed at case 1: saveToFile(type='value') without a file name wrote %r to result.npy and %r to result.csv, where they should hold the value vector." % (array, rows))
+
+# The filetype in any case, also in the compiled module
+for filetype in ("NPY", "Csv"):
+    for name, method in (("saveToFile()", mdl.saveToFile), ("The compiled module's saveToFile()", mdl.mdl.saveToFile)):
+        path = os.path.join(tmpdir.name, "anycase.%s" % filetype.lower())
+        if os.path.exists(path):
+            os.remove(path)
+        error, output = raises(lambda: method(fileName=path, type="value", filetype=filetype))
+        if error is not None or output:
+            sys.exit("Validation test failed at case 1: %s with filetype=%r raised %r and printed %r." % (name, filetype, error, output.strip()))
+        saved = loadednpy(path) if filetype.lower() == "npy" else readrows(path)
+        if (filetype.lower() == "npy" and not (isinstance(saved, np.ndarray) and np.array_equal(saved, VALUES))) \
+                or (filetype.lower() == "csv" and (saved[0] != "State_Index,Value" or len(saved) != NSTATES + 1)):
+            sys.exit("Validation test failed at case 1: %s with filetype=%r wrote %r, where it should write the value vector as a %s file." % (name, filetype, saved, filetype.lower()))
+
+# Arguments that are not used, and a file that cannot be opened (the compiled
+# module makes the same checks of the arguments)
+for label, given, expected, words in (
+        ("an unknown type", dict(fileName="result.npy", type="values2"), ValueError, "'policy' or 'value'"),
+        ("an unknown filetype", dict(fileName="result.npy", filetype="npz"), ValueError, "'npy' or 'csv'"),
+        ("a name ending in .csv and the default filetype", dict(fileName="result.csv"), ValueError, "filetype='csv'"),
+        ("a name ending in .CSV and filetype='npy'", dict(fileName="result.CSV", filetype="npy"), ValueError, "filetype='csv'"),
+        ("a name ending in .npy and filetype='csv'", dict(fileName="result.npy", filetype="csv"), ValueError, "filetype='npy'"),
+        ("a name ending in .npy and filetype='CSV'", dict(fileName="result.npy", filetype="CSV"), ValueError, "filetype='npy'"),
+        ("a file in a folder that does not exist", dict(fileName=os.path.join("missing", "result.npy")), FileNotFoundError, "missing")):
+    path = os.path.join(tmpdir.name, given["fileName"])
+    methods = [("saveToFile()", mdl.saveToFile)] + ([("The compiled module's saveToFile()", mdl.mdl.saveToFile)] if expected is ValueError else [])
+    for name, method in methods:
+        error, output = raises(lambda: method(**{**given, "fileName": path}))
+        if not isinstance(error, expected) or words not in str(error):
+            sys.exit("Validation test failed at case 1: %s with %s raised %r, where it should raise a %s that says %r." % (name, label, error, expected.__name__, words))
+        if output or os.path.exists(path):
+            sys.exit("Validation test failed at case 1: %s with %s printed %r or wrote a file." % (name, label, output.strip()))
 
 
 # ------------------------------------------------------------------

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/README.md

@@ -30,7 +30,7 @@ MDPSolver is a Python package for large Markov Decision Processes (MDPs) with in
 | 5,000,000 | 500,000,000 | 6.3 GB | 5.03 s |
 | 10,000,000 | 1,000,000,000 | 12.7 GB | 13.0 s |
 
-Mean of 10 random models with 5 actions per state and 20 possible next states per state and action, loaded from NPY-files and solved by modified policy iteration under the discounted reward criterion with discount 0.9. Measured on an Apple M5 with 10 cores.
+Mean of 10 random models with 5 actions per state and 20 possible next states per state and action, loaded from NPY-files and solved by modified policy iteration under the discounted reward criterion with discount $\lambda=0.9$ and tolerance $\epsilon = 0.001$. Measured on an Apple M5 with 10 cores.
 
 # Installation
 

{mdpsolver-0.12.0 → mdpsolver-0.12.1}/pyproject.toml

@@ -30,7 +30,7 @@ CMAKE_BUILD_TYPE = "Release"
 
 [project]
 name = "mdpsolver"
-version = "0.12.0"
+version = "0.12.1"
 authors = [
   { name="Anders Reenberg Andersen", email="andersra@live.dk" },
   { name="Jesper Fink Andersen", email="jesperfinkandersen@gmail.com" },