Adding API usage guide.

doc/conf.py

@@ -16,13 +16,13 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['ipython_console_highlighting']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']

doc/install.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 Installation
 ------------
 

doc/intro.rst

@@ -1,10 +1,13 @@
 Introduction
 ============
 
-PYPOWER is a power flow and Optimal Power Flow (OPF) solver. It is a port of
-MATPOWER_  to the Python_ programming language. Current features include:
+PYPOWER is a power flow and Optimal Power Flow (OPF) solver. Current features
+include:
 
 * DC and AC (Newton's method & Fast Decoupled) power flow and
 * DC and AC optimal power flow (OPF)
 
+PYPOWER is a translation of MATPOWER_  to the Python_ programming language
+using SciPy_.
+
 .. include:: ./link_names.txt

doc/ipython_console_highlighting.py

@@ -0,0 +1,98 @@
+"""reST directive for syntax-highlighting ipython interactive sessions.
+"""
+
+#-----------------------------------------------------------------------------
+# Needed modules
+
+# Standard library
+import re
+
+# Third party
+from pygments.lexer import Lexer, do_insertions
+from pygments.lexers.agile import (PythonConsoleLexer, PythonLexer, 
+                                   PythonTracebackLexer)
+from pygments.token import Comment, Generic
+
+from sphinx import highlighting
+
+
+#-----------------------------------------------------------------------------
+# Global constants
+line_re = re.compile('.*?\n')
+
+#-----------------------------------------------------------------------------
+# Code begins - classes and functions
+
+class IPythonConsoleLexer(Lexer):
+    """
+    For IPython console output or doctests, such as:
+
+    .. sourcecode:: ipython
+
+      In [1]: a = 'foo'
+
+      In [2]: a
+      Out[2]: 'foo'
+
+      In [3]: print a
+      foo
+
+      In [4]: 1 / 0
+
+    Notes:
+
+      - Tracebacks are not currently supported.
+
+      - It assumes the default IPython prompts, not customized ones.
+    """
+
+    name = 'IPython console session'
+    aliases = ['ipython']
+    mimetypes = ['text/x-ipython-console']
+    input_prompt = re.compile("(In \[[0-9]+\]: )|(   \.\.\.+:)")
+    output_prompt = re.compile("(Out\[[0-9]+\]: )|(   \.\.\.+:)")
+    continue_prompt = re.compile("   \.\.\.+:")
+    tb_start = re.compile("\-+")
+
+    def get_tokens_unprocessed(self, text):
+        pylexer = PythonLexer(**self.options)
+        tblexer = PythonTracebackLexer(**self.options)
+
+        curcode = ''
+        insertions = []
+        for match in line_re.finditer(text):
+            line = match.group()
+            input_prompt = self.input_prompt.match(line)
+            continue_prompt = self.continue_prompt.match(line.rstrip())
+            output_prompt = self.output_prompt.match(line)
+            if line.startswith("#"):
+                insertions.append((len(curcode),
+                                   [(0, Comment, line)]))
+            elif input_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, input_prompt.group())]))
+                curcode += line[input_prompt.end():]
+            elif continue_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Prompt, continue_prompt.group())]))
+                curcode += line[continue_prompt.end():]
+            elif output_prompt is not None:
+                insertions.append((len(curcode),
+                                   [(0, Generic.Output, output_prompt.group())]))
+                curcode += line[output_prompt.end():]
+            else:
+                if curcode:
+                    for item in do_insertions(insertions,
+                                              pylexer.get_tokens_unprocessed(curcode)):
+                        yield item
+                        curcode = ''
+                        insertions = []
+                yield match.start(), Generic.Output, line
+        if curcode:
+            for item in do_insertions(insertions,
+                                      pylexer.get_tokens_unprocessed(curcode)):
+                yield item
+
+#-----------------------------------------------------------------------------
+# Register the extension as a valid pygments lexer
+highlighting.lexers['ipython'] = IPythonConsoleLexer()

doc/usage.rst

@@ -1,25 +1,161 @@
 Usage
 -----
 
-Installing PYPOWER creates ``pf`` and ``opf`` commands. To list the command
-options::
+PYPOWER provides a Command Line Interface (CLI) and a Python Application
+Programming Interface (API).
+
+
+Command Line Interface
+++++++++++++++++++++++
+
+Following the :ref:`installation` instructions adds ``pf`` and ``opf``
+to the command path. To print usage info type::
 
   $ pf -h
 
-PYPOWER includes a selection of test cases. For example, to run a power flow
-on the IEEE 14 bus test case::
+All available options will be printed::
+
+	Usage: pf [options] [casedata]
+
+	Runs a power flow.
+
+	If 'casedata' is provided it specifies the name of the input data file
+	containing the case data.
+
+	Options:
+	  --version             show program's version number and exit
+	  -h, --help            show this help message and exit
+	  -t, --test            run tests
+	  -c TESTCASE, --testcase=TESTCASE
+	                        built-in test case (choose from: 'case30_userfcns',
+	                        'case118', 'case9', 'case30Q', 'case30pwl', 'case6ww',
+	                        'case57', 'case39', 'case14', 'case9Q', 'case30',
+	                        'case300', 'case4gs', 'case24_ieee_rts')
+	  -o FNAME, --outfile=FNAME
+	                        pretty printed output will be appended to a file with
+	                        the name specified. Defaults to stdout.
+	  -s SOLVEDCASE, --solvedcase=SOLVEDCASE
+	                        the solved case will be written to a case file with
+	                        the specified name in PYPOWER format. If solvedcase
+	                        ends with '.mat' the case is saves  as a MAT-file
+	                        otherwise it saves it as a Python file.
+
+	  Power Flow Options:
+	    --pf_alg=PF_ALG     power flow algorithm: 1 - Newton's method, 2 - Fast-
+	                        Decoupled (XB version), 3 - Fast-Decoupled (BX
+	                        version), 4 - Gauss Seidel [default: 1]
+	    --pf_tol=PF_TOL     termination tolerance on per unit P & Q mismatch
+	                        [default: 1e-08]
+	    --pf_max_it=PF_MAX_IT
+	                        maximum number of iterations for Newton's method
+	                        [default: 10]
+	    --pf_max_it_fd=PF_MAX_IT_FD
+	                        maximum number of iterations for fast decoupled method
+	                        [default: 30]
+	    --pf_max_it_gs=PF_MAX_IT_GS
+	                        maximum number of iterations for Gauss-Seidel method
+	                        [default: 1000]
+	    --enforce_q_lims=ENFORCE_Q_LIMS
+	                        enforce gen reactive power limits, at expense of |V|
+	                        [default: False]
+	    --pf_dc=PF_DC       use DC power flow formulation, for power flow and OPF:
+	                        False - use AC formulation & corresponding algorithm
+	                        opts, True  - use DC formulation, ignore AC algorithm
+	                        options [default: False]
+
+	  Output Options:
+	    --verbose=VERBOSE   amount of progress info printed: 0 - print no progress
+	                        info, 1 - print a little progress info, 2 - print a
+	                        lot of progress info, 3 - print all progress info
+	                        [default: 1]
+	    --out_all=OUT_ALL   controls printing of results: -1 - individual flags
+	                        control what prints, 0 - don't print anything
+	                        (overrides individual flags, except OUT_RAW), 1 -
+	                        print everything     (overrides individual flags,
+	                        except OUT_RAW) [default: -1]
+	    --out_sys_sum=OUT_SYS_SUM
+	                        print system summary [default: True]
+	    --out_area_sum=OUT_AREA_SUM
+	                        print area summaries [default: False]
+	    --out_bus=OUT_BUS   print bus detail [default: True]
+	    --out_branch=OUT_BRANCH
+	                        print branch detail [default: True]
+	    --out_gen=OUT_GEN   print generator detail (OUT_BUS also includes gen
+	                        info) [default: False]
+	    --out_all_lim=OUT_ALL_LIM
+	                        control constraint info output: -1 - individual flags
+	                        control what constraint info prints, 0 - no constraint
+	                        info (overrides individual flags), 1 - binding
+	                        constraint info (overrides individual flags), 2 - all
+	                        constraint info (overrides individual flags) [default:
+	                        -1]
+	    --out_v_lim=OUT_V_LIM
+	                        control output of voltage limit info: 0 - don't print,
+	                        1 - print binding constraints only, 2 - print all
+	                        constraints (same options for OUT_LINE_LIM,
+	                        OUT_PG_LIM, OUT_QG_LIM) [default: 1]
+	    --out_line_lim=OUT_LINE_LIM
+	                        control output of line limit info [default: 1]
+	    --out_pg_lim=OUT_PG_LIM
+	                        control output of gen P limit info [default: 1]
+	    --out_qg_lim=OUT_QG_LIM
+	                        control output of gen Q limit info [default: 1]
+	    --out_raw=OUT_RAW   print raw data [default: False]
+	    --return_raw_der=RETURN_RAW_DER
+	                        return constraint and derivative info in
+	                        results['raw'] (in keys g, dg, df, d2f)) [default: 0]
+
+
+PYPOWER includes a selection of test cases. For example, to run a power flow on
+the `IEEE 14 bus <http://pypower.org/api/pypower.case14-module.html>`_ test
+case::
 
   $ pf -c case14
 
-Alternatively, the path to a PYPOWER case data file can be specified.::
+Alternatively, the path to a `PYPOWER case data
+<http://pypower.org/api/pypower.caseformat-module.html>`_ file can be
+specified::
 
   $ pf /path/to/case14.py
 
 The ``opf`` command has the same calling syntax. For example, to solve an OPF
-for the IEEE Reliability Test System and write the solved case to file::
+for the `IEEE Reliability Test System
+<http://pypower.org/api/pypower.case24_ieee_rts-module.html>`_ and write the
+solved case to file::
 
   $ opf -c case24_ieee_rts --solvedcase=rtsout.py
 
-For further information please refer to the `API documentation`_.
+
+Application Programming Interface
++++++++++++++++++++++++++++++++++
+
+The Python API for PYPOWER can be accessed using the ``pypower.api``
+package:
+
+.. sourcecode:: ipython
+
+  In [1]: from pypower.api import case9, ppoption, runpf, printpf
+
+To load the 9 bus test case, solve an AC power flow using the fast-decoupled
+method and print the results:
+
+.. sourcecode:: ipython
+
+  In [2]: ppc = case9()
+
+  In [3]: ppopt = ppoption(PF_ALG=2)
+
+  In [4]: r = runpf(ppc, ppopt)
+
+  In [5]: printpf(r)
+
+For additional information refer to the Python documentation for each of the
+functions. E.g:
+
+.. sourcecode:: ipython
+
+  In [6]: help runpf
+
+Alternatively, refer to the on-line `API documentation`_.
 
 .. include:: ./link_names.txt

pypower/main.py

@@ -204,4 +204,5 @@ def opf(args=sys.argv[1:]):
 
 
 if __name__ == '__main__':
-    pf(['-c', 'case9', '--out_all=-1', '-s', '/tmp/out.py'])
+    pf(['-h'])
+#    pf(['-c', 'case9', '--out_all=-1', '-s', '/tmp/out.py'])