Merge pull request #8 from lbonaldo/update-docs

Update documentation

docs/source/interface.rst

@@ -185,4 +185,8 @@ Once the cases are set up, the model can be run by using the ``start_runs.sh`` s
 
  (ep) $ chmod u+x run_ep.sh
 
- and then run the file again.
+ and then run the file again.
+
+.. tip:: 
+ Remember to activate the ep conda environment in the terminal before running the start_runs.sh script.
+

docs/source/setup.rst

@@ -29,7 +29,14 @@ Model outputs consist of large csv files that have been designed to work well wi
 
 Installation
 ============
-EnergyPATHWAYS can be installed using the ``environment.yml`` file provided in the repository. This file contains all the necessary packages to run EnergyPATHWAYS. To install the environment, navigate to the directory containing the ``environment.yml`` file and run the following commands::
+First download the EnergyPATHWAYS code from the `EnergyPATHWAYS GitHub repository <https://github.com/EvolvedEnergyResearch/EnergyPATHWAYS>`_ either by downloading the zip file or by cloning the repository using git::
+
+ $ git clone https://github.com/EvolvedEnergyResearch/EnergyPATHWAYS
+
+.. Note::
+ If you are using a Windows machine and do not have git installed, you can download the repository as a zip file and proceed with the installation. If you would like install git on your machine, you can download it from `here <https://git-scm.com/download/win>`_.
+
+Once you have downloaded the code, EnergyPATHWAYS can be installed using the ``environment.yml`` file provided in the repository. This file contains all the necessary packages to run EnergyPATHWAYS. To install the environment, navigate to the directory containing the ``environment.yml`` file and run the following commands::
 
  $ cd EnergyPATHWAYS
  $ conda env create -f environment.yml
@@ -49,48 +56,69 @@ After running the setup script, the excel interface will be able to call the Ene
 
  If you encounter an error saying *ERROR: <folder name> does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found,* check to make sure you are in the correct directory. If you run ``ls`` (or ``dir`` on Windows) at the command prompt you should see the ``environment.yml`` and ``pyproj.toml`` files.
 
-Additional Excel configuration
-------------------------------
+Once the installation is complete, before running EnergyPATHWAYS, you will need to set up the EP interface and the data files. The following sections describe how to perform these steps.
+
+1. EP Interface setup
+---------------------
+
+EnergyPATHWAYS comes with a user interface that allows users to create, load and run scenarios. It contains two main files:
+
+- `scenario_builder.xlsm`: An Excel file with the commands to run the model.
+- `scenario_builder.py`: A python script with main functions to interact with the model.
+
+See the :ref:`User Interface` section for more information. 
+
+To set up the EP interface, follow these steps:
 
-For Windows users
-^^^^^^^^^^^^^^^
+1. Copy the `EP interface` folder outside of EnergyPathways main folder to the working directory. 
+2. Open the `scenario_builder.xlsm` file and enable macros.
+3. Setup the `xlwings.conf` sheet in the `scenario_builder.xlsm` file to point to the conda environment you created in the previous step. This step is different for Windows and MacOS users:
 
-1. (Optional, **depreciated**) Install the ``xlwings`` Excel Add-in by running the following command in the terminal::
- 
- (ep) $ xlwings addin install
+ **For Windows users**
 
-Installing the xlwings addin will add a new ribbon tab to your Excel files. We have started using an "xlwings.conf" sheet in the scenario_builder.xlsm file instead of the ribbon tab.
+ Enter the "Interpreter_Win", "Conda path" and "Conda env" values on the "xlwings.conf" sheet of your scenario_builder.xlsm file. Find the path to your Conda "base environment" ::
 
-2. Enter the "Conda path" and "Conda env" values on the "xlwings.conf" sheet of your scenario_builder.xlsm file. Find the path to your Conda "base environment" ::
- 
- (ep) $ conda info
+ (ep) $ conda info
 
-The Conda path should be something like ``C:\Users\Username\Anaconda3``. Copy this path to the "Conda path" field on your xlwings.conf sheet. Assuming you have followed installation instructions up to this point, use ``ep`` as the "Conda env".
+ The Conda path should be something like ``C:\Users\Username\Anaconda3``. Copy this path to the "Conda path" field on your xlwings.conf sheet. Assuming you have followed installation instructions up to this point, use ``ep`` as the "Conda env" and ``python`` as the "Interpreter_Win" values.
 
-.. note:: 
- The "Conda path" and "Conda env" variables will be used to activate your conda environment before running energyPATHWAYS. The "Start Runs" button in your scenario_builder.xlsm file will likely not work if you do not provide these values.
-
- For more information on using the Xlwings ribbon and "xlwings.conf" sheet, see the `xlwings addin documentation <https://docs.xlwings.org/en/latest/addin.html>`_.
+ .. note:: 
+ The "Conda path" and "Conda env" variables will be used to activate your conda environment before running energyPATHWAYS. The "Start Runs" button in your scenario_builder.xlsm file will likely not work if you do not provide these values.
 
-For MacOS users
-^^^^^^^^^^^^^^^
+ The xlwings.conf sheet should be similar to this (replace "Username" with your actual username):
 
-1. Enter the "Interpreter_Mac" value on the "xlwings.conf" sheet of your scenario_builder.xlsm file. Find the path to your Python interpreter by running the following command in the terminal::
+ +-----------------+--------------------------------+
+ | Interpreter_Win | python |
+ +-----------------+--------------------------------+
+ | Conda Path | C:\\Users\\Username\\Anaconda3 |
+ +-----------------+--------------------------------+
+ | Conda Env | ep |
+ +-----------------+--------------------------------+
 
- (ep) $ which python
+ **For MacOS users**
 
-The Interpreter_Mac path should be something like ``/Users/Username/miniconda3/envs/ep/bin/python``. Copy this path to the "Interpreter_Mac" field on your xlwings.conf sheet.
+ Enter the "Interpreter_Mac" value on the "xlwings.conf" sheet of your scenario_builder.xlsm file. Find the path to your Python interpreter by running the following command in the terminal::
 
-Data Setup
-==========
+ (ep) $ which python
+
+ The Interpreter_Mac path should be something like ``/Users/Username/miniconda3/envs/ep/bin/python``. Copy this path to the "Interpreter_Mac" field on your xlwings.conf sheet.
+
+ The xlwings.conf sheet should be similar to this (replace "Username" with your actual username):
+
+ +-----------------+------------------------------------------------+
+ | Interpreter_Mac | /Users/Username/miniconda3/envs/ep/bin/python |
+ +-----------------+------------------------------------------------+
+
+2. Data Setup
+-------------
 
 In addition to installation of the EnergyPATHWAYS package described above, a model cannot be run until input data are provided. The input data consist of three components:
 
 1. A database describing your energy system
 2. A configuration file (e.g. ``config.INI``)
 3. A runs_key.csv file that describes the variations of your energy system that you would like to model.
 
-The first two of these are described below, and the third is covered in detail unde
+To import scenario data into the model, make sure to edit the ``database_path`` variable in the ``config.INI`` file to point to the directory where the database has been placed.
 
 Workspace Organization
 ======================
@@ -119,10 +147,21 @@ Running the Model
 
 After installing EnergyPATHWAYS and setting up the necessary input data the model can be run from the command line::
 
- $ energyPATHWAYS [options]
+ (ep) $ energyPATHWAYS [options]
 
 To get help on the various command line options, use::
 
- $ energyPATHWAYS --help
+ (ep) $ energyPATHWAYS --help
 
 In most cases, the Excel user interface, described in :doc:`Interface Section <interface>`, is the best way to interact with the model.
+
+Uninstall EnergyPATHWAYS
+========================
+
+
+To uninstall EnergyPATHWAYS, deactivate the environment and remove it::
+
+ (ep) $ conda deactivate
+ (base) $ conda remove -n ep --all
+
+Delete the EnergyPATHWAYS repository from your local computer and the EP interface folder.

environment.yml

@@ -6,6 +6,7 @@ channels:
 dependencies:
  - python=3.10
  - pip
+ - git 
  - pandas=1.5
  - numpy
  - scipy