Skip to content

Getting started

!!! info “Overview” Prerequisites: - AMPL must be installed first and be accessible from your system’s PATH. - Python 3.6 or higher is required. Installation Paths: - Option A: Quick Start for Beginners 😎 - Install EnergyScope via pip. - Ideal for users who want a simple setup without modifying the source code. - Option B: Editable Installation for Experts 🏄 - Clone the EnergyScope repository and install in editable mode. - Suitable for users who plan to modify the source code or AMPL models.

Welcome to the EnergyScope library! This guide will help you set up and start using EnergyScope, whether you’re a beginner looking to run simulations or an expert aiming to modify the source code.

Prerequisites¤

Before you begin, please ensure you have the following:

  1. Install AMPL EnergyScope relies on AMPL (A Mathematical Programming Language) for optimization modeling. AMPL must be installed first and be accessible from your system’s PATH.

  2. See the Installing AMPL section below for detailed instructions.

  3. Python

  4. Version: Python 3.6 or higher.
  5. Environment: We recommend using a virtual environment to manage dependencies.

Choose Your Path¤

Option A: Quick Start for Beginners 😎¤

If you’re new to EnergyScope and want a quick setup without delving into the source code: 1. Install EnergyScope via pip: 

pip install energyscope
2. Run the Basic Tutorial: Get started by following our Basic Run Tutorial to familiarize yourself with EnergyScope.

Option B: Editable Installation for Experts 🏄¤

If you plan to customize the source code or the underlying AMPL models: 1. Clone the EnergyScope Repository: 

git clone https://gitlab.com/energyscope/energyscope.git
2. Install EnergyScope in Editable Mode: Navigate to the cloned repository and install package in editable mode: 
cd energyscope
pip install -e .
Alternatively, if you’re working within a Jupyter notebook or an interactive environment, you can use: 
# Clone the repository
!git clone git@gitlab.com:energyscope/energyscope.git

# Install the package in editable mode
%pip install -e ./energyscope

# Add the package to the Python path (if necessary)
import sys
sys.path.append('./energyscope')
3. Modify and Run Code: You’re now ready to explore and modify the source code and AMPL models according to your needs.

Installing AMPL¤

EnergyScope uses AMPL for optimization modeling. Follow these steps to install AMPL on your system:

  1. Download AMPL
  2. Visit the AMPL Community Edition ⧉ page to download the appropriate version for your operating system.
  3. Install AMPL
  4. Windows:
    • Run the installer and follow the on-screen instructions.
  5. Linux and macOS:
    • Extract the downloaded archive to a directory where you have read and write permissions (e.g., your home directory).
  6. Activate Your License
  7. AMPL Community Edition requires a free license.
  8. During installation, you’ll receive a license UUID.
  9. Activate your license by running the following command in the AMPL command prompt: 
    shell "amplkey activate --uuid <license-uuid>";
    Replace <license-uuid> with your actual license UUID.
  10. Note: Restart AMPL after activation to start using the new license.
  11. Add AMPL to PATH
  12. Windows:
    • Add the AMPL installation directory (e.g., C:\AMPL) to your system’s PATH environment variable.
  13. Linux and macOS:
    • Open your terminal and add the following line to your .bashrc or .bash_profile: 
      export PATH="/path/to/ampl:$PATH"
  14. Replace /path/to/ampl with the actual path to your AMPL directory.
  15. Verify AMPL Installation To confirm that AMPL is correctly installed:
  16. Open Command Prompt or Terminal:
    • Open a new command prompt (Windows) or terminal window (Linux/macOS).
  17. Run AMPL: 
    ampl
    • If installed correctly, you should see the ampl: prompt you can quit with the command 
      quit;

Running EnergyScope¤

With both EnergyScope and AMPL installed, you’re ready to run simulations. - Basic Tutorial: - Start with the Basic Run Tutorial to learn how to set up and execute a basic energy model.

Need Help?

If you have any questions or run into issues: - Documentation: Check out the EnergyScope Documentation. - Community Support: Join our community ⧉ forum for discussions and help. - Contact Us: Reach out via our contact page ⧉.