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.
python -m pip install --upgrade pip
python -m virtualenv ~/virtualenvs/polarislib
source ~/virtualenvs/polarislib/bin/activate
python -m pip install --upgrade pip
python -m virtualenv c:/python/virtualenvs/polarislib
c:\python\virtualenvs\polarislib\Scripts\activate.ps1
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.
Installing the package from the PyPI registry is as easy as:
python -m pip install uv
python -m uv pip install polaris-studio
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
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.
Installing the license#
If you have received a license file from Argonne, you can install it in three different manners.
The first installation option is to use the GUI to point to the license file in the pace where it is will be stored long term. The GUI will become available once you first try to run Polaris, and it looks like the following:
# Activate your virtual environment
.\python_venv\Scripts\activate
# And add the license
polaris add-license --lincense_path "D:\Argonne\License 1.Lic"
On a Jupyer notebook or Python script you can add the license by calling the add_license
method from
the Polaris
class.
from polaris import Polaris
Polaris.add_license("D:\Argonne\License 1.Lic"
In case you fail to install the license or the license is not correct, you will receive a message like the one below.
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 aggregate_summaries
polaris add_license
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 add_license#
polaris add_license --help
>>> Options:
>>> --lincense_path TEXT Path to the license file to be used henceforth **[required]**