Commit 64fd9d8b authored by Steven Cordwell's avatar Steven Cordwell
Browse files

redistribute the module level docstrings

parent e8854225
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""Markov Decision Process (MDP) Toolbox
=====================================
import mdp The MDP toolbox provides classes and functions for the resolution of
\ No newline at end of file descrete-time Markov Decision Processes.
Available modules
-----------------
example
Examples of transition and reward matrices that form valid MDPs
mdp
Makov decision process algorithms
utils
Functions for validating and working with an MDP
How to use the documentation
----------------------------
Documentation is available both as docstrings provided with the code and
in html or pdf format from
`The MDP toolbox homepage <http://www.somewhere.com>`_. The docstring
examples assume that the ``mdptoolbox`` package is imported like so::
>>> import mdptoolbox
To use the built-in examples, then the ``example`` module must be imported::
>>> import mdptoolbox.example
Once the ``example`` module has been imported, then it is no longer neccesary
to issue ``import mdptoolbox``.
Code snippets are indicated by three greater-than signs::
>>> x = 17
>>> x = x + 1
>>> x
18
The documentation can be displayed with
`IPython <http://ipython.scipy.org>`_. For example, to view the docstring of
the ValueIteration class use ``mdp.ValueIteration?<ENTER>``, and to view its
source code use ``mdp.ValueIteration??<ENTER>``.
Acknowledgments
---------------
This module is modified from the MDPtoolbox (c) 2009 INRA available at
http://www.inra.fr/mia/T/MDPtoolbox/.
"""
# Copyright (c) 2011-2013 Steven A. W. Cordwell
# Copyright (c) 2009 INRA
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# * Neither the name of the <ORGANIZATION> nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
import mdp
if __name__ == "__main__":
import doctest
doctest.testfile("example.py", module_relative=True)
doctest.testfile("mdp.py", module_relative=True)
doctest.testfile("utils.py", module_relative=True)
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """Markov Decision Process (MDP) Toolbox: ``example`` module
Created on Sun Aug 18 14:32:25 2013 =========================================================
The ``example`` module provides functions to generate valid MDP transition and
reward matrices that are valid.
Available functions
-------------------
forest
A simple forest management example
rand
A random example
@author: steve
""" """
# Copyright (c) 2011-2013 Steven A. W. Cordwell
# Copyright (c) 2009 INRA
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# * Neither the name of the <ORGANIZATION> nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
from numpy import diag, ones, where, zeros from numpy import diag, ones, where, zeros
from numpy.random import randint, random from numpy.random import randint, random
from scipy.sparse import coo_matrix, dok_matrix from scipy.sparse import coo_matrix, dok_matrix
...@@ -241,3 +279,7 @@ def rand(S, A, is_sparse=False, mask=None): ...@@ -241,3 +279,7 @@ def rand(S, A, is_sparse=False, mask=None):
R[a][s] = (m * (2*random(S) - ones(S, dtype=int))) R[a][s] = (m * (2*random(S) - ones(S, dtype=int)))
# we want to return the generated transition and reward matrices # we want to return the generated transition and reward matrices
return (P, R) return (P, R)
if __name__ == "__main__":
import doctest
doctest.testmod()
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""Markov Decision Process (MDP) Toolbox """Markov Decision Process (MDP) Toolbox: ``mdp`` module
===================================== =====================================================
The MDP toolbox provides classes and functions for the resolution of The ``mdp`` module provides classes for the resolution of descrete-time Markov
descrete-time Markov Decision Processes. Decision Processes.
Available classes Available classes
----------------- -----------------
...@@ -26,43 +26,6 @@ ValueIteration ...@@ -26,43 +26,6 @@ ValueIteration
ValueIterationGS ValueIterationGS
Gauss-Seidel value iteration MDP Gauss-Seidel value iteration MDP
Available functions
-------------------
check
Check that an MDP is properly defined
checkSquareStochastic
Check that a matrix is square and stochastic
exampleForest
A simple forest management example
exampleRand
A random example
How to use the documentation
----------------------------
Documentation is available both as docstrings provided with the code and
in html or pdf format from
`The MDP toolbox homepage <http://www.somewhere.com>`_. The docstring
examples assume that the `mdp` module has been imported imported like so::
>>> import mdptoolbox.mdp as mdp
Code snippets are indicated by three greater-than signs::
>>> x = 17
>>> x = x + 1
>>> x
18
The documentation can be displayed with
`IPython <http://ipython.scipy.org>`_. For example, to view the docstring of
the ValueIteration class use ``mdp.ValueIteration?<ENTER>``, and to view its
source code use ``mdp.ValueIteration??<ENTER>``.
Acknowledgments
---------------
This module is modified from the MDPtoolbox (c) 2009 INRA available at
http://www.inra.fr/mia/T/MDPtoolbox/.
""" """
# Copyright (c) 2011-2013 Steven A. W. Cordwell # Copyright (c) 2011-2013 Steven A. W. Cordwell
......
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
""" """Markov Decision Process (MDP) Toolbox: ``utils`` module
Created on Sun Aug 18 14:30:09 2013 =======================================================
The ``utils`` module provides functions to check that an MDP is validly
described. There are also functions for working with MDPs while they are being
solved.
Available functions
-------------------
check
Check that an MDP is properly defined
checkSquareStochastic
Check that a matrix is square and stochastic
getSpan
Calculate the span of an array
@author: steve
""" """
# Copyright (c) 2011-2013 Steven A. W. Cordwell
# Copyright (c) 2009 INRA
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# * Neither the name of the <ORGANIZATION> nor the names of its contributors
# may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
from numpy import absolute, ones from numpy import absolute, ones
SMALLNUM = 10e-12 SMALLNUM = 10e-12
...@@ -294,3 +335,7 @@ class InvalidMDPError(Error): ...@@ -294,3 +335,7 @@ class InvalidMDPError(Error):
Error.__init__(self) Error.__init__(self)
self.message += msg self.message += msg
self.args = tuple(msg) self.args = tuple(msg)
if __name__ == "__main__":
import doctest
doctest.testmod()
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment