Getting Started

Getting Started#

Installation#

Unit tests in polaris-studio are currently run in Python 3.11 (Ubuntu Linux) and Python 3.10 (Windows). As of October/24, Python 3.12 is also supported, although not consistently tested. We recommended using Python 3.11.

Python installations from the Windows store are NOT SUPPORTED

The Windows app store ships a version of Python that contains an sqlite dll that does not support the loading of extensions. This means that Spatialite will not be loaded, and therefore Polaris-Studio will not work properly.

For errors during installation and use, please refer to the Frequently Asked Questions

Using a virtual environment#

However you install polaris-studio we recommend first setting up a clean virtual environment to keep dependencies separated from your system python. The following batch code will make sure your pip is upto date, create a new virtualenv and activate it.

Linux

python -m pip install --upgrade pip
python -m virtualenv ~/virtualenvs/polarislib
source ~/virtualenvs/polarislib/bin/activate

Windows (PowerShell)

python -m pip install --upgrade pip
python -m virtualenv c:/python/virtualenvs/polarislib
c:\python\virtualenvs\polarislib\Scripts\activate.ps1

Windows (cmd.exe)

python -m pip install --upgrade pip
python -m virtualenv c:/python/virtualenvs/polarislib
c:\python\virtualenvs\polarislib\Scripts\activate.bat

Install the package#

After activating your virtual environment, you need to install the polaris-studio package into that environment.

From PyPI

Installing the package from the PyPI registry is as easy as:

python -m pip install uv
python -m uv pip install polaris-studio

From a wheel file

If you’ve been provided with a wheel file you can install that using pip:

python -m pip install uv
python -m uv pip install polaris-studio-py3-none-any.whl

From GitLab

If you have access to the ANL GitLab server you may want to clone a copy of the source directly. This has the benefit of being easier to update when new features are released or bugs squashed. The following clones the repo and installs it into in editable (-e) mode.

Note that this option doesn’t provide compiled POLARIS executables and you will need to provide your own when running models.

git clone https://git-out.gss.anl.gov/polaris/code/polarislib.git ~/git/polaris-studio
python -m pip install uv
python -m uv pip install -e ~/git/polaris-studio

Installation options#

In order to reduce the number of installed dependencies required for common workflows, polaris-studio utilizes a partitioned dependency set. This means that if you want to run a model, you don’t need to install dependencies that are only used when building the network or analyzing results through a GUI. While basic dependencies will ALWAYS be installed, additional sets are unlocked by adding the appropriate option(s) to the installation command, which install the required dependencies. These options also apply when installing in editable model (-e) from a cloned repository.

hpc: This option includes the dependencies required to run the model on a HPC environment, such as the PG database connectivity required to coordinate runs and the globus data transfer tooling.

python -m uv pip install polaris-studio[hpc]

builder: This option includes all the dependencies required to run the model on a regular workstation, as well as access model-building tools, result analysis and GUI resources. This is the preferred option for those working with polaris-studio but not developing it

python -m uv pip install polaris-studio[builder]

dev: This option includes all the dependencies required by any resource in polaris-studio, as well as those needed for testing, document building and debugging. This is the option recommended for those developing polaris-studio,
which only makes sense when installing from a cloned repository.

python -m uv pip install polaris-studio[dev]

Other options, such as installation of only linting requirements and documentation dependencies also exist, but their use is intended on Continuous Integration (CI) and Continuous Deployment (CD) pipelines only.

Command Line Interface#

polaris-studio provides a convenient CLI (command line interface) for a few key Polaris tasks, including running and upgrading models and building them from git.

The main thing to know here is that this interface is available only from within an active Python virtual environment and, once such environment is active, the interface is available from any folder/directory.

The polaris commands available are:

polaris run
polaris upgrade
polaris build-from-git
polaris gui

A simple example for this would be:

polaris build-from-git --data_dir d:/mymodel --city=grid --upgrade true
polaris run --data_dir d:/mymodel/grid/built --num_threads 18

The up-to-date configuration for which one of these commands is available by adding the parameter –help after the command you are interested in using, but the available parameters are listed below.

Polaris run#

polaris run --help

>>> Options:
>>>   --data_dir TEXT                  Model directory  **[required]**
>>>   --config_file TEXT               Convergence control file override. Defaults to convergence_control.yaml
>>>   --num_threads INTEGER            Number of threads to use for model run
>>>   --population_scale_factor FLOAT RANGE
>>>                                    Population sampling factor [0.0001<=x<=1.0]
>>>   --upgrade TEXT                   Whether we want to upgrade the model to the latest structure before running it
>>>   --do_pop_synth / --no_pop_synth  Override the "should run population sythesizer" flag from convergence_control.yaml
>>>   --do_skim / --no_skim            Override the "should run skimming" flag from convergence_control.yaml
>>>   --do_abm_init / --no_abm_init    Override the "should run abm_init iteration" flag from convergence_control.yaml
>>>   --polaris_exe TEXT               Path to the polaris executable to be used. Defaults to the executable shipped with polaris-studio
>>>   --num_abm_runs INTEGER           Number of ABM runs to be run. Defaults to the value on convergence_control.yaml
>>>   --start_iteration_from TEXT      Start running from this iteration. Useful if restarting a previously failed run.
>>>   --help                           Show this message and exit.

Polaris upgrade#

polaris upgrade --help

>>> Options:
>>>   --data_dir TEXT      Model directory  **[required]**
>>>   --help               Show this message and exit.

Polaris build-from-git#

polaris build-from-git --help

>>> Options:
>>>   --data_dir  TEXT      Target model directory  **[required]**
>>>   --city      TEXT      City model to build - corresponds to the git repository **[required]**
>>>   --db_name   TEXT      DB name. Defaults to the value in abm_scenario.json
>>>   --overwrite BOOLEAN   Overwrite any model in the target directory. Defaults to False
>>>   --inplace   BOOLEAN   Build in place or a sub-directory. Defaults to subdirectory
>>>   --upgrade   TEXT      Whether we should upgrade the model after building it
>>>   --help                Show this message and exit.

Polaris GUI#

It is also possible to access the Polaris GUI from the terminal

polaris gui --help

>>> Options:
>>>   --data_dir TEXT      Model directory  **[required]**
>>>   --help               Show this message and exit.

An example of this command would be

polaris gui --data_dir c:/models/chicago/run062