Installation#

Note

This page explains how to install and configure modelx and related packages manually, and is intended for advanced Python users or Linux/Mac users.

For Windows users, it is recommended to use the latest custom WinPython with modelx, which is available here. You can start using modelx just by unzipping the downloaded file, and no need to follow the steps on this page.

Python version#

modelx requires Python 3.7 or newer. However, Python 3.7 reached its end of life so if you’re still using Python 3.7, you should upgrade it. The newer the version of Python is, the faster it performs.

Package dependency#

The packages listed below are either required by modelx, or can be used with modelx to develop models more efficiently.

  • NetworkX (>=2.0) (required)

  • asttokens (required)

  • LibCST (required)

  • pandas (nearly required, not installed from modelx dependency)

  • OpenPyXL (nearly required, not intalled from modelx dependency)

  • Spyder (>=4.0.0) (optional)

You can install and use modelx without pandas or OpenPyXL, but modelx would raise errors when features requiring those packages are requested. pandas and OpenPyXL are not automatically installed from modelx’s dependency, so you should install them separately if they are missing.

networkx#

NetworkX is a required package that modelx depends on. Version 2.0 or newer is required.

asttokens#

asttokens is a required package that modelx depends on.

LibCST#

LibCST is a required package that modelx depends on.

Pandas#

Although pandas is not strictly required for modelx, you should have pandas installed, as some methods in modelx require pandas and errors will be raised if such methods are called without pandas installed.

In most Python distributions, pandas is pre-installed, but if it’s not installed, install it by typing pip install pandas in the console, or if you’re using Anaconda, by conda install pandas.

Openpyxl#

OpenPyXL is a package that supports reading from and writing to Excel files. OpenPyXL is also not strictly required, but some methods, such as new_pandas() depend on it to interface with Excel files. So to have modelx fully function, you should have OpenPyXL installed.

To install OpenPyXL from pip, type pip install openpyxl in the console, or if you’re using Anaconda, type conda install openpyxl.

Spyder#

To use modelx with Spyder, a popular open-source Python IDE, A plugin for modelx is available. spyder-modelx is a separate package to add custom IPython consoles and Modelx explorer, a widget that shows the current model in a tree view. The supported Spyder version is 4.0.0 or newer. For how to install the plugin, see here.

Installing modelx#

Note

For lifelib users, when installing lifelib using pip or conda, modelx is automatically installed due to its dependency, so no need to install modelx separately.

Just like other Python packages, you can install modelx by running pip command from a terminal on Linux, or from a command prompt on Windows. If your Python environment is Anaconda, use the conda command in stead of pip, as explained below.

To install the current version of modelx with pip:

> pip install modelx

To upgrade to a newer version using the --upgrade flag:

> pip install --upgrade modelx

To make modelx available only to you but others, install it into your user directory using the --user flag:

> pip install --user modelx

To uninstall modelx:

> pip uninstall modelx

If you prefer to install modelx from files placed locally on your machine instead of directly fetching from the Web, you can manually download modelx files from GitHub or PyPI. Unpack the downloaded files and run the following command at the top of the source directory:

> pip install .

To install the latest development version instead of the released version, clone the modelx repository from github, and install them from the cloned repos in editable mode.

Anaconda environment#

Anaconda is a Python distribution for scientific computing that has its own package management command named conda. If your Python environment is based on the Anaconda distribution, do not use pip to install and update modelx. In stead, use the conda command.

To install the current version of modelx:

> conda install -c conda-forge modelx

To upgrade modelx:

> conda update modelx

To uninstall modelx:

> conda remove modelx

Spyder integration#

Spyder is a popular open-source Python IDE, and a Spyder plugin for modelx is available. For more about the Spyder plugin for modelx, see the Spyder plugin page

Configuring Spyder#

Disable User Module Reloader

When you use modelx with Spyder, sometimes you may want to re-run the same file in the editor window multiple times in the same IPython session. You don’t want to reload modelx because reloading modelx module creates multiple instances of modelx systems within the same Python process, causing models created before and after a reload to reside in different modelx systems. To avoid that, you need to change User Module Rloader (UMR) setting.

From the Spyder menu, select Tools->Preferences to bring up Preferences window. Choose Python interpreter in the left pane, and you’ll find an area titled User Module Reloader (UMR) on the bottom right side of the Preferences window. Leave Enable UMR option checked, click Set UMR excluded(not reloaded) modules and then UMR dialog box pops up as the figure blow. Enter “modelx” in the dialog box. This prevents Spyder from reloading the modelx module every time you re-run the same script from Run menu, while allowing other modules to be reloaded.

Note that you need to restart Spyder to bring the change into effect.

_images/PreferencesUMR.png

User Module Reloader setting#

Import modelx at IPython startup

When you use modelx in IPython, you need to import modelx first. Doing so every time you open a new IPython session is tedious, so there’s a way to import modelx at each IPython session’s startup. From the Spyder menu, select Tools->Preferences to bring up Preferences window. Choose IPython console in the left pane, and select Startup tab from the tabs on the right. Enter import modelx as mx in the box titled Lines: in the Run code area, and click Okay. Next time you open a new IPython session, modelx is imported as mx in the IPython’s global namespace.

_images/PreferencesStartup.png

IPython startup setting#

Installing Spyder plugin for modelx#

The plugin is available as separate Python packages named spyder-modelx and spymx-kernels.

The supported version of Spyder is 4.0.0 or newer. The plugin does not work with Spyder 3.x.

spyder-modelx package is available on PyPI, and can be installed using pip command. If you’re using Anaconda distribution, do not use pip but use conda instead:

> pip install spyder-modelx

With Anaconda:

> conda install -c conda-forge spyder-modelx

spymx-kernels is installed automatically because spyder-modelx depends on spymx-kernels.

If Spyder is running while the plugin gets installed, close Spyder once and restart it to bring the plugin into effect.

Updating packages#

To update modelx to the latest version, use -U option with pip install, or conda update with Anaconda:

> pip install -U modelx

On Anaconda:

> conda update modelx