Merge branch 'update_tutorial'

doc/source/conf.py

@@ -75,7 +75,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

doc/source/tutorial/basic_operations.rst

@@ -1,23 +1,21 @@
-Basic Operations
-===================
+Basic usage in Python
+=======================
 
-Up to the previous section, we've learned how to build and run models
+So far, we've learned how to build and run models
 using Spyder IDE, by going through some basic examples.
-In this section, you will learn
-how to perform modelx's basic operations from the Python interpreter,
-such as creating Models, Spaces, Cells and References
-and evaluating Formulas.
+This section covers the basic usage of modelx.
+Unlike the prior examples, here in this section
+we will mainly use IPython consoles to interface with modelx interactively,
+instead of Spyder with the modelx plugin.
+You can keep using Spyder that you've been using from the prior examples.
+Create a new MxConsole for the exercise in this section.
+Alternatively, you can use IPython that comes with any other Python tools,
+such as Jupyter notebook, JupyterLab, PyCharm, Visual Studio Code etc.
 
 Code snippets in this section are assumed to be executed interactively
-from IPython console,
-but the snippets can also be written in Python scripts and
+from IPython console, but the snippets can also be written in Python scripts and
 can be run as Python programs.
 
-This tutorial supplements modelx reference,
-which is build from docstrings of the API functions and classes.
-The reference should cover the details of each API element,
-which may not be fully explained in this tutorial.
-
 
 Importing modelx
 ----------------
@@ -44,7 +42,7 @@ is imported as ``mx``:
     ``from modelx import defcells``
 
 
-Basic Model operations
+Working with Models
 -----------------------
 
 As introduced :ref:`previously <overview-of-core-modelx-objects>`,
@@ -200,7 +198,7 @@ Python environments other than the one that the Model is backed up on,
 so it is advisable to back up Models only for saving them temporarily.
 
 
-Basic Space operations
+Working with Spaces
 -----------------------
 
 *Spaces* are modelx objects that serve as containers, separating
@@ -296,7 +294,7 @@ or this way::
 
 Either statement works the same.
 
-Basic Cells operations
+Working with Cells
 -----------------------
 
 Cells objects are for defining calculations and storing values.
@@ -516,3 +514,126 @@ specified value is assigned::
   5    0
   Name: fibo, dtype: int64
 
+
+Namespace and References
+------------------------
+
+Defining formulas
+-----------------
+
+Most Formulas need to reference values of other Cells
+and References to calculte their own values.
+Unlike Python functions,
+the name binding for modelx Formulas is independent from
+Python modules.
+Each Space has its own namespace associated with itself,
+and the names in the Formulas of child Cells in the Space
+are bound in the namespace associated with the Space.
+The names defined in the associated namespace are
+the names of the child objects of the Space, such as
+child Cells, Spaces and References. In addition to
+the child objects' names, global References,
+special names and built-in names are defined in the associated
+namespace.
+The global References are the References defined at the containing Model level,
+as attributes of the Model.
+The special names are defiend by modelx,
+and the names start with "_".
+Currently there is only one special name, ``_space``,
+which refers to the Space itself.
+The list below summarizes
+the kind of names defined in the namespace associated with a UserSpace.
+
+    * The child Cells, Spaces and References
+    * The global References defined in the Model
+    * The special names (``_space``)
+    * The Python built-in names
+
+The sample code below is taken from
+the mortgage loan example we have seen earlier.
+The ``Balance`` global variable
+refers to a Cells object ``Balance``, but the name of the variable
+does not need to be the same as the Cells' name::
+
+    >>> Balance.formula
+    def Balance(t):
+
+        if t > 0:
+            return Balance(t-1) * (1+Rate) - Payment()
+        else:
+            return Principal
+
+    >>> Balance(30)
+    1.2096279533579946e-10
+
+
+If ``Balance`` was a Python function, then the names in
+the ``Balance`` definition, such as ``Balance``, ``Rate``,
+``Payment``, ``Principal`` would refer to global variables
+defined in the module that the function was defined in.
+However, as explained above, the Formula of ``Balance`` is evaluated
+in the namespace associated with its parent Space ``Fixed``.
+The ``Fixed`` Space has child Cells, such as ``Payment`` and
+``Balance``. It also has child References, such as
+``Principal`` and ``Rate``. So, the names in the ``Balance`` definition
+refer to those child Cells and Referneces of the ``Fixed`` Space.
+To get all the names defined in the ``Fixed`` name space,
+use the Python built-in function :obj:`dict`.
+The code below assumes that the ``Fixed`` variable refers to the ``Fixed`` Space::
+
+    >>> dir(Fixed)
+    ['Balance',
+     'Payment',
+     'Principal',
+     'Rate',
+     'Term',
+     '__builtins__',
+     '_self',
+     '_space']
+
+(Note: ``_self`` in the list above is deprecated and should not be used.)
+
+
+Running a model
+----------------
+
+Unlike a program written in a programming language,
+a *modelx* Model does not have a single entry point, such as the *main* function
+in *C*. And modelx also differs from Excel, in a sence that
+modelx does not populate its Model with calculated values upon
+opening the Model. modelx evaluates a Formula when its value
+is requested by the user directly or indirectly through Formulas
+depending on the Fromula's value.
+
+The ``Fibo`` Cells in the sample below is taken from the earlier section::
+
+    >>> Fibo.formula
+    def Fibo(n):
+        if n > 1:
+            return Fibo(n-1) + Fibo(n-2)
+        else:
+            return n
+
+Initially, ``Fibo`` does not have any values. You can check
+``Fibo``'s values by converting it to :obj:`dict`::
+
+    >>> dict(Fibo)
+    {}
+
+When you request the value of ``Fibo`` for ``n=5``,
+the values of ``Fibo`` for ``n=0`` through ``n=4`` are also calculated::
+
+    >>> Fibo(5)
+    5
+
+    >>> dict(Fibo)
+    {1: 1, 0: 0, 2: 1, 3: 2, 4: 3, 5: 5}
+
+
+
+
+
+
+
+
+

doc/source/tutorial/fibonacci.rst

@@ -1,8 +1,10 @@
 
 
 
-Example 1: Fibonacci Sequence
-------------------------------
+The simplest example
+======================
+
+
 
 Now that we have modelx ready for our exercise and we
 understand the basics of modelx objects, we are going to model
@@ -38,7 +40,7 @@ basic operations in modelx.
 
 
 Creating a Cells and defining its Formula
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------------
 
 Find MxExplorer widget in your Spyder IDE.
 
@@ -151,7 +153,7 @@ then you will see the formula in the bottom right pane.
 
 
 Getting calculated results
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
 
 The Cells ``Fibo`` does not have values yet right after it is created.
 
@@ -222,7 +224,7 @@ or as a Pandas Series or DataFrame object::
 
 
 Tracing calculation
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 Tracing calculation is for inspecting calculation dependency.
 It is useful, for example, when you want to debug a calculation,
@@ -256,7 +258,7 @@ of ``Fibo[5]`` directly or indirectly.
 
 
 Overriding calculation by input
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------
 
 Cells values can be assigned by the user. When the user
 assigns values for certain arguments, then the assigned values
@@ -291,7 +293,7 @@ for ``n=11`` before changing ``Fibo[0]``.
 
 
 Saving the work
-^^^^^^^^^^^^^^^
+---------------
 
 The last step is to save the Model we created. Bring up the context menu
 in *MxExplorer* by right-clicking in the widget, and select *Write Model* item.

doc/source/tutorial/gettingstarted.rst

@@ -1,31 +1,13 @@
 Getting Started
 ---------------
 
-Before diving into sample exercises,
-first we learn how to interface with modelx, then
-set up a Python environment for modelx, and
-learn about core modelx objects.
-
-
-How to interface with modelx
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-modelx is a Python package, so to use modelx you can simply
-write Python scripts and import it, as you would normally do with
-any other Python package.
-Likewise, you can also use it interactively from an IPython consoles,
-or in Jupyter notebooks.
-By convention, It is recommended to import the module as ``mx``::
-
-    >>> import modelx as mx
-
-Another way to interface with modelx is through Spyder plugin for modelx
-on Spyder IDE. The plugin installs custom widgets and custom IPython consoles
-that allow you to interface with modelx graphically.
-Using the GUI greatly helps you to understand and interact with modelx models more
-intuitively.
-The sample exercises in this tutorial assumes you use Spyder with the plugin.
-
+This section explains how to prepare a Python environment
+for modelx to use it for sample exercises in this tutorial.
+We prepare a stand-alone Python environment from
+a Python distribution prepared for modelx.
+If you prefer to use your own Python environment,
+See :doc:`/installation` page for how to install
+modelx and its relevant packages into your Python environment.
 
 Setting up Python and modelx
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -105,63 +87,3 @@ and waits for your input.
 
    MxConsole
 
-.. _overview-of-core-modelx-objects:
-
-Overview of core modelx objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-modelx is designed to let the users build models consisting
-of a few types of objects.
-*Model*, *Space*, *Cells* and *References*
-are the most important types of objects.
-Before getting started with the first example,
-you want to have an idea on what these types of objects are.
-
-Model, Space and Cells are to modelx
-what workbook, worksheet and cells are to a spreadsheet program respectively,
-although there are differences.
-The diagram below illustrates containment
-relationships between those objects.
-
-.. blockdiag::
-   :caption: Model, Space and Cells
-   :align: center
-
-   blockdiag {
-     orientation = portrait
-     default_node_color="#D5E8D4";
-     default_linecolor="#628E47";
-     node_width=70;
-     Model1<- Space1[hstyle=composition];
-     Model1<- Space2[hstyle=composition];
-     Model1<- Ref1[hstyle=composition];
-     Space1<- Cells1[hstyle=composition];
-     Space1<- Space3[hstyle=composition];
-     Space1<- Ref2[hstyle=composition];
-   }
-
-
-Models are the top level objects that contain all the other types
-of modelx objects. Models can be saved to files and loaded back again.
-
-Directly under Models, there are Spaces. Spaces serve as containers,
-separating contents in Models into components.
-Spaces contain Cells objects and other Spaces, allowing tree
-structures of objects to form within Models.
-
-Spaces also serve as the namespaces for the formulas associated to
-the Spaces themselves or to the Cells contained in them.
-References are names bound to arbitrary objects.
-References defined in a Model (for example *Ref1* in the
-diagram above) can be referenced from any Formulas
-in the Model. References defined in a Space can be referenced from
-the Formulas in the Space.
-For example, ``Cells1.formula`` (and ``Space1.formula`` if any) can
-refer to ``Ref2``.
-
-
-Cells are objects that can have formulas and hold values, just like
-spreadsheet cells can have formulas and values.
-Cells values are either calculated
-by their formulas or assigned as input by the user.
-We will learn how to define Cells formulas through the examples soon.

doc/source/tutorial/index.rst

@@ -5,8 +5,8 @@ This tutorial helps you learn how to use modelx for the first time
 by walking you through some hands-on examples.
 
 To fully understand what's written in this tutorial,
-it's better to have basic understanding of Python
-itself, but advanced knowledge of Python is not required.
+having a basic understanding of Python
+itself is preferable, but advanced knowledge of Python is not required.
 Even if you have never used Python before, you can still go
 through this tutorial by following instructions step-by-step.
 To learn Python itself, there are plenty of quality resources
@@ -24,8 +24,14 @@ except for Windows specific parts.
    :caption: Contents
 
    gettingstarted
+   introduction
    fibonacci
    mortgage
    basic_operations
-   eval_formulas
-   api_tutorial
+   api_tutorial
+
+..
+   debugging
+   save_and_restore
+   interface_with_python
+   object_oriented

doc/source/tutorial/mortgage.rst

@@ -1,4 +1,4 @@
-Example 2: Mortgage Loan
+Basic modeling example
 ========================
 
 For the second example, we are going to model a fixed-rate mortgage loan,