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.

Setting up Python and modelx

Setting up a Python environment for modelx is pretty straight-forward. Download the WinPython distribution customized for modelx from here.

This tutorial assumes you’re using the latest modelx and spyde-modelx, so if you have downloaded the distribution before, make sure you update modelx and spyder-modelx to the latest versions by following the instruction here, or download the latest distribution from the site above.

Unzip the downloaded zip file. You can unzip it from the Windows default context menu by right-clicking on the file and select Extract All…, or instead you can use your favorite third party tool for unzipping.

../_images/ExtractAllContextMenu.png

Windows context menu for extracting zip file

In this tutorial, we use Spyder as a graphical user interface to modelx. The downloaded WinPython comes with Spyder and Spyder plugin for modelx pre-installed and pre-configured, so no need to install them separately.

Within the unzipped folder, find Spyder.exe and start Spyder by double-clicking it.

../_images/StartSpyder.png

Spyder.exe in unzipped folder

The Spyder window shows up. You may have modelx widgets showing already upon startup, but if you don’t, bring them up by going to View menu in the menu bar and select Pane and then select three modelx items (MxExplorer, MxDataView, MxAnalyzer) at the bottom.

../_images/ViewMenuMxWidgets.png

modelx Widgets in View menu

Now you should be able to see the 3 widgets. You can move them around and change their locations by unlocking panes. To unlock panes, go to View menu and uncheck Lock panes and toolbars item.

../_images/ViewMenuUnlockPane.png

Lock and Unlock Panes

The last widget to prepare for modelx is MxConsole, an IPython console that communicates with the modelx widgets. modelx works fine in Spyder’s default IPython consoles, but the default consoles do not communicate with the modelx widgets, so you want to use MxConsoles instead. You should have IPython console pane and a tab named Console 1/A. Right-click on the tab, and from the context menu, select New MxConsole.

../_images/OpenNewMxConsole.png

Console Tab Context Menu

A new tab named MxConsole 2/A is created, and after a few seconds, an IPython session starts in the MxConsole and waits for your input.

../_images/BlankMxConsole.png

MxConsole

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 Model1 Space1 Space2 Ref1 Cells1 Space3 Ref2

Model, Space and Cells

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.