ABCE: agent-based capacity expansion modeling

ABCE is a module to perform agent-based capacity expansion (CE) modeling for electricity market systems. It simulates decisions made over time by individual profit-motivated entities coexisting in a shared wholesale electricity market environment.

Contents

• Installation
  • Linux / MacOS / Windows Subsystem for Linux
  • Windows 10
  • Optional: installing with CPLEX
• Usage
  • Running ABCE
  • Input files
  • Outputs
• License

Installation

Linux / MacOS / Windows Subsystem for Linux

1. Clone this repository to your local machine:

   git clone https://github.com/abce-dev/abce

2. If using CPLEX, see the optional Installing with CPLEX section below

3. Inside your local abce directory, run the installation script with:

   bash ./install.sh

4. Wait for the installation script to run to completion. Review any errors/issues printed for your reference at the end of execution.

5. Restart your terminal session, or re-source your .bashrc file.

6. If using Conda to manage environments, activate the ABCE conda environment with:

   conda activate abce_env

7. Rerun the installation script to complete the environment setup:

   bash ./install.sh

8. Test the installation using one of the examples:

   cd examples/single_agent_example

   If you have CPLEX installed, update the settings.yml file in that directory to indicate "CPLEX" as the solver.

   Then run the example case:

   python ../../run.py --settings_file=./settings.yml --inputs_path=.

9. Once the previous command runs to completion without failing, generate a precompiled Julia sysimage file from within the abce/env directory.

   julia make_sysimage.jl

Windows

1. Download and install Miniconda

2. Download and install Julia 1.8. Check the box in the installer to add Julia to the PATH.

3. If using CPLEX, see the optional Installing with CPLEX section below

4. Using the Anaconda Powershell, clone this repo to your local machine:

   git clone https://github.com/abce-dev/abce

5. Create the local conda environment:

   conda env create -f .\environment_win.yml

6. Activate the abce_anv conda environment:

   conda activate abce_env

7. Set the ABCE_DIR environment variable to the absolute path to your abce repo (e.g. C:\Users\myname\abce)

8. Test the installation using one of the examples:

   cd examples\single_agent_example

   If you have CPLEX installed, update the settings.yml file in that directory to indicate "CPLEX" as the solver.

   Then run the example case:

   python ..\..\run.py --settings_file=.\settings.yml --inputs_path=.

9. Once the previous command runs to completion without failing, generate a precompiled Julia sysimage file from within the abce\env directory.

   julia make_sysimage.jl

Optional: installing with CPLEX

1. Download the CPLEX (IBM ILOG STUDIO 20.10) binaries

2. Run the CPLEX installer, following all instructions.

3. Check that CPLEX is installed properly: open the Windows Command Prompt and run the command $ cplex. The output should resemble:

(base) sdotson@research:~$ cplex

Welcome to IBM(R) ILOG(R) CPLEX(R) Interactive Optimizer 20.1.0.0
  with Simplex, Mixed Integer & Barrier Optimizers
5725-A06 5725-A29 5724-Y48 5724-Y49 5724-Y54 5724-Y55 5655-Y21
Copyright IBM Corp. 1988, 2020.  All Rights Reserved.

Type 'help' for a list of available commands.
Type 'help' followed by a command name for more
information on commands.

If the cplex command is not found, try adding the absolute path of your cplex executable to the $PATH environment variable with

$ export CPLEX_STUDIO_BINARIES=/opt/ibm/ILOG/CPLEX_Studio201/cplex/bin/x86-64_linux/

$ export PATH=$PATH:$CPLEX_STUDIO_BINARIES

Usage

Running ABCE

ABCE is invoked by the command:

python run.py

run from the top level of the local abce directory. This command can accept several optional arguments:

• -f: automatically agree to overwrite any existing database and output files.

• --verbosity=k, where k takes one of the following values:

  • 0: completely silent execution

  • 1: minimal output to mark progression through timesteps and agent turns only

  • 2 (default): basic output showing sub-steps within agent turns

  • 3: maximally verbose, showing results of many calculations and all DEBUG-level messages

• --settings_file=<user_file>: specify the desired settings file with relative or absolute path <user_file>. Default: ./settings.yml

• --inputs_path=<user_inputs_dir>: specify the location of input files, with either a relative or absolute path. Relative path will be relative to the directory from which ABCE is run, not necessarily the directory where the ABCE source code is saved. Default: ./inputs/

• -d: "demo" mode, pauses execution at the end of each time step to allow the user to review printed outputs

If you'd like to halt execution of ABCE while it is running, press Ctrl+C in the terminal session. All data and results generated up to this point will be preserved in the database file (see Outputs).

Input files

The input files required to run ABCE are as follows:

• settings.yml: contains all run-specific settings for each simulation. Data specified here supersedes data specified anywhere else.

• inputs/:

  • agent_specifications.yml: definitions for the agents: financial parameters, starting portfolios by unit type, and mandatory retirement dates for owned units

  • demand_data.csv: normalized peak demand levels per simulated year (used to scale the peak_demand parameter)

  • unit_specs.yml: construction and operations cost and parameter data for all possible unit types in the model

  • inputs/ts_data/:

    • timeseries_<quantity>_hourly.csv: hourly timeseries data for each of the following quantities in the system:

      • load: normalized to peak_demand

      • wind and solar: wind and solar availability, normalized to the start-of-year installed capacity of each technology, respectively

      • reg, spin, and nspin: ancillary service procurement requirements, in absolute terms (not scaled)

Outputs

abce/outputs/<scenario_name>/abce_db.db

The main output from ABCE is the run's database file. This file contains a running ledger of most pieces of data loaded or generated by the simulation as it runs. The database is continually updated as the code runs, so even if the code crashes or you force-quit it with Ctrl+C, the database will retain all data as it existed when execution halted.

abce/outputs/<scenario_name>/outputs.xlsx

If the code runs successfully to completion, an xlsx dump of the final state of the database is created. No postprocessing is done on the database, but it's easier to open an xlsx file than explore a .db file in most cases, so this is just for convenience.

System and agent portfolio evolution charts

ABCE also outputs plots of the evolution of the overall system portfolio and the individual agents' portfolios throughout the simulation. Results are shown for all simulated years, plus three years projected into the future based on already-set construction and retirement plans as of the final simulated year.

Use ABCE with watts

The Workflow and Template Toolkit for Simulations (watts) has a plugin for ABCE. Please see the watts documentation for usage. This workflow tool is useful for conducting sensitivity analyses and other experiments with ABCE.

License

Copyright 2023 Argonne National Laboratory

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.