Installing ESA¶

Installing ESA is simple! Follow the directions below to get started.

Overview¶

TL;DR:

python -m pip install --only-binary pywin32,pypiwin32 pywin32 pypiwin32 esa

Installing ESA is easy, and most users will simply want to use Python’s package manager, Pip, to install ESA. Users who want to extend or modify ESA should install from source.

Prerequisites¶

ESA has the following prerequisites:

Microsoft Windows Operating System (PowerWorld is Windows only. The authors of ESA have only ever attempted to use Windows 10.).
Python >=3.5. Download it here.
PowerWorld Simulator with the Automation Server (SimAuto) add-on installed.
- NOTE: the authors of ESA have tested with Simulator versions 17 and 21. It is likely, but not guaranteed, that ESA will work with all Simulator versions 16-21. If you encounter a problem with a particular version, please file an issue and we may be able to help (if we can get access to that particular Simulator version).
Git Large File Storage (LFS) (OPTIONAL: required to download case files and run tests). After installing Git LFS, simply change directories to the ESA repository, and run git lfs install. You will likely need to run a git pull or git lfs pull after installing and setting up Git LFS. After initial setup, you shouldn’t need to do anything else with Git LFS.

Virtual Environment Configuration¶

Like any Python project, the use of virtual environments is strongly encouraged. If you’re new to virtual environments, Python provides a nice tutorial.

After installing Python on your machine, open up a Command Prompt window (Hit the “Windows” key and the “R” key simultaneously, type in “cmd” in the popup, then hit Enter) then set up a virtual environment like so (adapt paths as necessary):

cd C:\path\to\my\project
C:\path\to\python.exe -m venv my-venv

Then, activate the virtual environment like so (in the same terminal):

my-venv\Scripts\activate.bat

All installation directions assume your virtual environment has been activated.

Next, update pip and setuptools (in your activated virtual environment):

python -m pip install --upgrade --force-reinstall pip setuptools

Install Prerequisite Packages¶

ESA depends on the pywin32 Python package in order to interface with Windows components. Unfortunately, pywin32 does not always cleanly install automatically when installing ESA, so it’s recommended that you first manually install pywin32. In your activated virtual environment, execute the following:

python -m pip install --only-binary :all: pypiwin32 pywin32

The authors have found that the --only-binary flag is often necessary to get pywin32 to work - without it, pywin32 is unable to find some necessary libraries.

If you are using a conda environment, a simpler way is to use conda to install instead of pip:

conda install pywin32

Install ESA via Pip¶

To install ESA with pip, run the following in your activated virtual environment:

python -m pip install esa

Install ESA from Source¶

Installing ESA from source is quite simple, and does not require any extra tools. One might choose to install ESA from source if you plan to extend or modify ESA, or would like to run ESA’s suite of tests.

The first step is to obtain a copy of the ESA repository. There are two ways to obtain a copy: download a .zip archive or use Git to clone the repository. Here’s a link to ESA’s GitHub repository. On the GitHub page you can find a link to “Clone or download.”

If you choose to clone the repository with Git, you’ll also need to install Git Large File Storage. After installation, use Git Bash or a Command Prompt window to execute the following:

cd C:\Users\myuser\git\ESA
git lfs install
git pull
git lfs pull

If you choose to download a .zip archive, you’ll of course need to extract the archive to the desired directory.

Once you have a copy of the ESA repository, simply run the following in a Command Prompt window after activating your virtual environment (adapt path to match your setup):

cd C:\Users\myuser\git\ESA
python -m pip install .

If you would like to be able to run tests, you’ll need to install the testing dependencies:

python -m pip install .[test]

Similarly, to build the documentation, you’ll need:

python -m pip install .[doc]

If you want to both run tests and build the documentation:

python -m pip install .[test,doc]

You can find the specified “extras” in setup.py - look for extras_require.

Post-Installation¶

The post-installation steps found here are optional, but may save you some headache down the line.

Cursory Verification of Successful Installation¶

The simplest way to verify that ESA installed correctly is to attempt to import it. Most (but not all) installation issues will rear their heads at this point. Simply execute the following in a Command Prompt window (ensure your virtual environment is activated!):

python -c "import esa; print('Success!')"

If an error message is emitted, ESA or its dependencies are not properly installed. If you’re unable to figure it out on your own, feel free to file an issue on GitHub. We do not guarantee that we can help everyone.

Execute ESA Unittests¶

At this point in time, one can only run unittests if ESA is installed from source and if you’ve installed the test dependencies. A future version of ESA may make tests available when installing via Pip.

Using a Command Prompt window, change directories to the ESA repository and run the tests like so (adapt paths as necessary):

cd C:\Users\myuser\git\ESA
my-venv\Scripts\activate.bat
python -m unittest discover tests

During the running of the tests, you’ll see some logging output and error messages - this is expected. What’s important is that at the end, you see a message like:

Ran 73 tests in 34.542s

OK (expected failures=2)

If something is wrong, you’ll see some indications of failure. The “expected failures” are okay, and do not indicate there are any issues.

If you’ve installed the testing dependencies listed in setup.py, you should have “coverage.py” installed. If you’d like to assess ESA’s testing coverage, the incantation looks like (run from top-level of ESA repository after activating virtual environment):

coverage run
coverage report -m

Note that the arguments to coverage run are provided by .coveragerc at the top-level of the repository.

pywin32 Post-Installation¶

From the pywin32 GitHub page:

Note that if you want to use pywin32 for “system wide” features, such as registering COM objects or implementing Windows Services, then you must run the following command from an elevated command prompt:

python Scripts/pywin32_postinstall.py -install

Note that the aforementioned “Scripts” directory can be found inside your virtual environment directory.