Added energyplus trouble shooting note to docs

Author: Oliver Smith

CITATION.cff

@@ -26,5 +26,5 @@ authors:
 license: "MIT"
 repository-code: "https://github.com/UCL/simstock"
 url: "https://simstock.readthedocs.io/"
-version: "0.3.0"
+version: "0.3.1"
 date-released: 2026-03-24

README.md

@@ -19,7 +19,7 @@ Full docs are available at [ReadtheDocs](https://simstock.readthedocs.io/en/late
 
 ## Installation
 
-> **_NOTE:_**  SimStock requires Python 3.11 to 3.13, as well as an EnergyPlus installation.
+> **_NOTE:_**  SimStock requires Python 3.11 to 3.13, as well as an EnergyPlus 8.9 installation.
 
 
 After ensuring you have EnergyPlus installed, and Python 3.11-3.13, simply run 
@@ -59,6 +59,12 @@ Below is an example of a typical Simstock work flow.
     simulation.run()
 ```
 
+### Troubleshooting
+
+SimStock requires an EnergyPlus 8.9 install. In particular, SimStock needs access to the Energy+.idd file that ships with EnergyPlus. 
+If SimStock cannot find your EnergyPlus IDD file, it will emit a ``FileNotFoundError``, see the
+[IDD troubleshooting guide](https://simstock.readthedocs.io/en/latest/installation.html#idd-troubleshooting).
+
 
 ## Community and Support
 

docs/source/conf.py

@@ -13,7 +13,7 @@
 project = 'SimStock'
 copyright = '2023, Ivan Korolija, Oliver Smith, Shyam Amrith'
 author = 'Oliver Smith'
-release = '0.3.0'
+release = '0.3.1'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/examples.rst

@@ -559,23 +559,3 @@ This will save EnergyPlus output files into a directory called ``outs/`` in your
     # To save EnergyPlus output files into some other directory:
     simulation = sim.IDFmanager(sdf, out_dir="some_other_directory")
 
-
-.. Finer grained control
-.. ---------------------
-
-.. This can be done like this. 
-
-
-.. Using built island mode
-.. -----------------------
-
-.. That can be switched on or off like this.
-
-
-.. Common problems
-.. ---------------
-
-.. .idd file not found
-.. *******************
-
-.. Specifiy this here.

docs/source/installation.rst

@@ -5,7 +5,7 @@ Installation
 
 .. admonition:: Requirements \ \ 
 
-   SimStock supports Python versions 3.11 to 3.13 and requires an installation of EnergyPlus. It is recommended that EnergyPlus .idd files are installed to ``C:\\EnergyPlus*\\Energy+.idd`` if using Windows, where ``*`` will be the EnergyPlus version number. If using Mac or Linux, it is recommended to have the EnergyPlus idd files at either ``/usr/local/EnergyPlus*/Energy+.idd`` or ``/Applications/EnergyPlus*/Energy+.idd``. Silicone Mac users should also have Rosetta installed.
+   SimStock supports Python versions 3.11 to 3.13 and requires an installation of EnergyPlus 8.9. It is recommended that EnergyPlus .idd files are installed to ``C:\\EnergyPlus*\\Energy+.idd`` if using Windows, where ``*`` will be the EnergyPlus version number. If using Mac or Linux, it is recommended to have the EnergyPlus idd files at either ``/usr/local/EnergyPlus*/Energy+.idd`` or ``/Applications/EnergyPlus*/Energy+.idd``. Silicone Mac users should also have Rosetta installed.
 
 SimStock can either being installed from PyPI (recommended for most users) or in developer mode by cloning the repository.
 
@@ -24,6 +24,35 @@ in the command line.
 
 ----
 
+.. _idd-troubleshooting:
+
+EnergyPlus IDD file location
+----------------------------
+
+SimStock requires an EnergyPlus 8.9 IDD file (typically called ``Energy+.idd``).
+When creating a ``SimstockDataframe``, SimStock first looks for 
+a user-specified IDD location. User can specify the location of their IDD file
+either by seeting it with an environment variable:
+
+.. code-block:: bash
+
+   export IDD_FILE="/path/to/Energy+.idd"
+
+or by passing the location as an optional parameter in Python, e.g.:
+
+.. code-block:: python
+
+   import simstock as sim
+   sdf = sim.read_csv("test.csv", idd_file="/path/to/Energy+.idd")
+
+If no user-specified location is found, SimStock looks for an IDD file in the default locations:
+   - Windows: ``C:\\EnergyPlus*\\Energy+.idd``
+   - macOS/Linux: ``/usr/local/EnergyPlus*/Energy+.idd`` or ``/Applications/EnergyPlus*/Energy+.idd``
+
+If no IDD file is found, SimStock raises ``FileNotFoundError``.
+
+---
+
 Installation for developers
 ===========================
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "simstock"
-version = "0.3.0"
+version = "0.3.1"
 description = "A Python package for building stock simulations"
 authors = [
     "Ivan Korolija <i.korolija@ucl.ac.uk>",

src/simstock/__init__.py

@@ -13,7 +13,7 @@
     plot
 )
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 
 __all__ = [
     "SimstockDataframe",