Merge pull request #70 from samgdotson/env-instructions

Env instructions
arfc · Oct 8, 2024 · 7e5f71b · 7e5f71b
2 parents a14b673 + 589d7de
commit 7e5f71b
Show file tree

Hide file tree

Showing 11 changed files with 557 additions and 68 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+.DS_store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -39,6 +41,7 @@ pip-delete-this-directory.txt
 
 # Unit test / coverage reports
 htmlcov/
+cov_html
 .tox/
 .nox/
 .coverage

diff --git a/README.md b/README.md
@@ -5,11 +5,13 @@ Open source multi-objective energy system framework
 [![status](https://joss.theoj.org/papers/183a04edba2d4952fa1e30c419a844b3/status.svg)](https://joss.theoj.org/papers/183a04edba2d4952fa1e30c419a844b3)
 [![Build Status](https://github.com/arfc/osier/actions/workflows/CI.yml/badge.svg)](https://github.com/arfc/osier/actions/workflows/CI.yml)
 [![Documentation Status](https://readthedocs.org/projects/osier/badge/?version=latest)](https://osier.readthedocs.io/en/latest/?badge=latest)
-
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/samgdotson/osier/env-instructions?labpath=docs%2Fsource%2Fexamples)
 
 
 ## Installation
 
+### Method 1: PyPI
+
 `osier` is available through [PyPI](https://pypi.org/project/osier/). It may be installed with 
 ```bash
 python -m pip install osier
@@ -23,8 +25,21 @@ git clone https://github.com/arfc/osier.git
 cd osier
 # for a basic installation
 pip install .
-# to also install the documentation dependencies
+# (Windows/Linux) to also install the documentation dependencies
 pip install .[doc]
+# (MacOS)
+pip install .'[doc]'
+```
+
+### Method 2: Conda/Mamba Environment
+
+Although `osier` is not yet available on `conda-forge`, you may have a more consistent experience by installing
+`osier` via a `conda` environment.
+
+```bash
+git clone [email protected]:arfc/osier.git  # requires ssh-keys
+mamba env create  # mamba and conda are interchangeable, here
+mamba activate osier-env
 ```
 
 
@@ -40,6 +55,14 @@ cd build/html
 python -m http.server
 ```
 
+## Examples
+
+The examples can be found in the `docs/source/examples/` directory. Alternatively, 
+users can run the notebooks and experiment with `osier` through the Binder app.
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/samgdotson/osier/env-instructions?labpath=docs%2Fsource%2Fexamples)
+
+
 ## Tests
 `osier`'s tests can be run by executing `pytest` in the top-level directory 
 of `osier`.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,11 +18,11 @@
 # -- Project information -----------------------------------------------------
 
 project = 'osier'
-copyright = '2022, Samuel Dotson'
+copyright = '2022-2024, Samuel Dotson'
 author = 'Samuel Dotson'
 
 # The full version, including alpha/beta/rc tags
-release = '0.2.1'
+release = '0.3.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -44,6 +44,7 @@
     "sphinx.ext.mathjax", 
     "sphinx.ext.coverage",
     "nbsphinx",
+    "nbsphinx_link"
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/examples/capacity_expansion_tutorial.ipynb b/docs/source/examples/capacity_expansion_tutorial.ipynb
diff --git a/docs/source/examples/dispatch_tutorial.ipynb b/docs/source/examples/dispatch_tutorial.ipynb
@@ -5,6 +5,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/samgdotson/osier/env-instructions?labpath=docs%2Fsource%2Fexamples%2Fdispatch_tutorial.ipynb)\n",
+    "\n",
     "# Dispatch Tutorial\n",
     "\n",
     "In this tutorial you will learn how to run a dispatch model in `osier` using\n",

diff --git a/docs/source/examples/getting_started.ipynb b/docs/source/examples/getting_started.ipynb
diff --git a/docs/source/examples/index.md b/docs/source/examples/index.md
@@ -8,6 +8,7 @@ This section has examples that guide users from basic usage to more advanced top
 ```{toctree}
 :maxdepth: 3
 
+getting_started
 tech_tutorial
 dispatch_tutorial
 capacity_expansion_tutorial

diff --git a/docs/source/examples/tech_tutorial.ipynb b/docs/source/examples/tech_tutorial.ipynb
@@ -5,6 +5,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/samgdotson/osier/env-instructions?labpath=docs%2Fsource%2Fexamples%2Ftech_tutorial.ipynb)\n",
+    "\n",
     "# `Osier` Technology Tutorial\n",
     "\n",
     "An `osier.Technology` is the fundamental object in `osier`, representing power producing technologies such as power plants or energy storage. Other modules use and modify `osier.Technology` objects. This object contains all of the information one needs to run an energy system model.\n",

diff --git a/environment.yml b/environment.yml
@@ -0,0 +1,27 @@
+name: osier-env
+channels:
+  - conda-forge
+
+dependencies:
+  - python>=3.9
+  - pip 
+  - ipython
+  - ipykernel
+  - jupyterlab
+  - pandas
+  - scipy
+  - glpk
+  - coincbc
+  - yaml
+  - numpy
+  - matplotlib
+  - pytest
+  - pytest-cov
+  - pyomo
+  - pip:
+    - pymoo
+    - pyentrp
+    - deap
+    - dill
+    - openpyxl
+    - osier
diff --git a/osier/technology.py b/osier/technology.py
@@ -20,7 +20,7 @@
              'specific_power': MW**-1,
              'specific_energy': (MW * hr)**-1,
              'mass_per_energy': megatonnes * (MW * hr)**-1,
-             'area_per_power': km * MW**-2}
+             'area_per_power': km**2 * MW**-1}
 
 _constant_types = (int, float, unyt_quantity)
 _array_types = (unyt.unyt_array, pd.core.series.Series, np.ndarray, list)

diff --git a/pyproject.toml b/pyproject.toml
@@ -63,7 +63,8 @@ doc = [
         'numpydoc',
         'pydata_sphinx_theme',
         'nbsphinx',
-        'pandoc'
+        'pandoc',
+        'nbsphinx-link',
 ]
 
 [tool.setuptools.packages.find]