Mini-ISO

Table of contents

• Mini-ISO
  • Table of contents
  • Description
    • Datasets
    • Use cases
  • How to install Mini-ISO
    • Step 1. Install git and pipx
      • MacOS
      • Windows
      • Linux (Ubuntu)
    • Step2: Install Mini ISO
  • Key modules
  • How to run Mini-ISO
  • To kill a process
    • In Linux
    • In Windows
  • Building a distribution
    • On Linux
    • On Windows
    • Running the distribution

Description

Mini-ISO is an interactive electricity market simulator for classroom use.

It provides three browser-based apps:

	Name	Description	Screenshot
1.	System Overview	Interactive simulator showing all network/market elements. Each update in the Inputs tabs triggers an update of the dispatch instructions and nodal prices displayed in the Outputs tabs.
2.	Offers Portal	Interface for offer submissions and auction results.
3.	Auction Screen	Interface to aggregate offers and clear the market.
	App Menu	In-browser selection of Mini-ISO apps

Datasets

Several datasets are shipped with this repository

	Name	#Nodes	#Generators	Description
1.	mini_iso/datasets/one-zone	1	3	A simple illustration of marginal pricing
2.	mini_iso/datasets/zones-zones	3	2	To illustrate congestion and price separation
3.	mini_iso/datasets/mini-new-england-simple	8	13	Mini New England network with one offer tranche per generator
4.	mini_iso/datasets/mini-new-england-nonuniform	8	13	Mini New England network with three offer tranches per generator

To create a new dataset, follow the format of the files in the sample directory. You'll need a three .csv files and a .json file that names them.

Use cases

Classroom scenarios:

• Use the System Overview to illustrate offer stacks, marginal prices, locational marginal prices, and network congestion.
• Add a fun element of competition!
  • Assign a group of class members to each generator in the network.
  • Ask them to submit bids in the Offers app.
  • Every few minutes, clear the market via the Auction app and ask students to record their change in revenue.

⚠️ In a realistic environment, market participants would never see each others' offers, so ask class members not to peek!

How to install Mini-ISO

Step 1. Install git and pipx

MacOS

git --version  # triggers prompts to install git
brew install pipx
pipx ensurepath
sudo pipx ensurepath --global

Windows

1. Install Python (py) using one of the following installers:

   • python-3.11.9-amd64.exe
   • python-3.12.3-amd64.exe

2. Use py to install pip and pipx:

py -m ensurepip --upgrade
py -m pip install --user pipx

Linux (Ubuntu)

sudo apt update
sudo apt install git-all
sudo apt install pipx
pipx ensurepath
sudo pipx ensurepath --global

Step2: Install Mini ISO

# Download Mini-ISO and install dependencies
git clone https://github.com/ne-pearl/mini-iso.git

# Move into mini-iso folder 
cd mini-iso

# Install Mini ISO dependencies with Poetry
pipx install poetry
poetry env use 3.11  # or 3.12 etc.
poetry install

Key modules

Path	Description
mini_iso/auction.py	Panel definition for Auction app
mini_iso/bidders.py	Panel definition for Offers app
mini_iso/clearance.py	Economic dispatch model in gurobipy
mini_iso/dashboard.py	Panel definition for System Overview app
mini_iso/typing_.py	Shared type definitions

---

How to run Mini-ISO

cd your/path/to/mini-iso
poetry env activate
poetry run panel serve mini_iso/app.py --port 5006 --args mini_iso/datasets/one-zone

To kill a process

If you encounter a message like Cannot start Bokeh server, port 5006 is already in use, try the following commands.

In Linux

lsof -i :5006  # copy process id, e.g., 12334
kill -9 12345

In Windows

Get-Process -Id (Get-NetTCPConnection -LocalPort 5006).OwningProcess | Stop-Process -Force

---

Building a distribution

The steps explain the use of PyInstaller to bundle Mini-ISO and its dependencies into a single (platform-dependent) executable file.

⚠️ This shouldn't be necessary (as all dependencies should already have been specified in pyproject.toml), I seem to have run into problems.

poetry add \
    altair dask[dataframe] gurobipy hypothesis ipython matplotlib \
    networkx pandas pandera panel pydantic pyinstaller pytest scipy
poetry update

On Linux

poetry env activate
poetry env use 3.12

# Required for python shared object files
sudo apt-get install python3.12-dev  # or python3.11-dev etc.

# Local copy of gurobi.lic from PyPI 
cp echo $(which python)/site-packages/gurobipy/.libs/gurobi.lic .

# Create redistributable (only for your platform)
cd your/path/to/mini-iso
pyinstaller \
    mini_iso/app.py \
    --hiddenimport pydantic.deprecated.decorator \
    --add-data ./gurobi.lic:gurobipy/.libs/

# To run
./dist/app/app \
    $(realpath mini_iso/datasets/mini_new_england/mini_new_england.json)

On Windows

For now, please see my notes in windows.md.

• Update this document for Windows.

Running the distribution

⚠️ When running the Mini-ISO bundle, you may encounter an error about an expired GUROBI license. This might indicate that you have an expired gurobi.lic file in your home directory (which GUROBI checks first, before the copy in the Mini-ISO folders). To resolve, please remove/rename the expired file.