Skip to content

Commit

Permalink
merge in docs (#110)
Browse files Browse the repository at this point in the history 
* Edited authors

* changed cerf to naturf in contributing.rst

* changed cerf to naturf in footer.rst

* Edited authors

* edited index

* edited user guide requirements and added definition for FAD

* added definitions for PAD and RAD

* added definiton for RAF

* added definitions for parameters 91-95

* added headers for parameters 96-132

* added equation for parameter 117

* added definition for parameters 113-116

* added defintion for parameters 106, 108, 110, 112

* added defintion for parameters 105, 107, 109, 111

* added definitions for parameters 103 and 104

* edited getting_started

* edited user_guide

* edited user_guide

* edited user_guide

* edited authors and contributors

* edited license

* added copyright and publication

* edited copyright and publication

* added copyright and publication

* added notes about lat lon of dataset

* added definition for parameters 96-99

* added definition for parameters 118-132

* added definition for parameter 94

* added definition for parameter 100

* added references to user guide

* edited contributions

* added definition for parameter 102

* edited formatting

* Edited references

* Edited definition for parameter 94

* added reference for svf

* removed old documentation

* readding references

* added definition for parameter 101

* redid citations

* working

* added note

* edited parameter 100 definition

* first pass at a list of all outputs

* defined variables for parameter 92

* defined variables for parameter 93

* edited formula for parameter 100

* defined variable for parameters 105, 107, 109, 111

* defined variable for parameters 105, 107, 109, 111

* added note for parameter 117

* added notes

* edited descriptions for roughness length and displacement height

* clean up descriptions, fix formulas

* test $ for latex

* test \ for latex

* fix code block

* fix code block

* fix code block

* fix code block

* fix code block

* fix code block

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* render equations

* embed links

* embed links

* fix latex rendering

* latex check

* latex check

* defined plan area

* defined frontal area

* changed wording to fit new definitions

* latex check

* clarified definitions

* edited contributors

* removed cerf documentation

* edited release notes

* edited dependencies

* edited dependencies

* added assumptions, edited definitions

* removed cerf info

* add hamilton info

* updated dependencies

* update definitions

* fixed definitions

* fix Height-to-Width Ratio equation (#73)

* replaced RDH and fixed beta showing up incorrectly #81

* add lambda def to raupach roughness length

* add frontal length to docs #97

---------

Co-authored-by: levisweet <lsweet@vols.utk.edu>
Co-authored-by: lg6 <sweetlt@ornl.gov>
Co-authored-by: Levi Sweet-Breu <99049421+levisweetbreu@users.noreply.github.com>
  • Loading branch information
@erexer @levisweetbreu
4 people authored Nov 27, 2023
1 parent adda599 commit d5437c8
Show file tree
Hide file tree
Showing 11 changed files with 599 additions and 800 deletions.
41 changes: 31 additions & 10 deletions docs/source/authors.rst
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,32 @@
Authors and Contributors
========================

Authors
=======

* **Chris R. Vernon (@crvernon)**. Lead developer and maintainer
* **Jennie S. Rice**. Original product conception, algorithm development, and documentation
* **Nino Zuljevic**. Algorithm, supporting data, and code development.
* **Kendall Mongird**. Algorithm, supporting data, and documentation development
* **Kristian Nelson**. Supporting data and documentation development
* **Gokul Iyer**. Supporting data and documentation development
* **Nathalie Voisin**. Supporting data and documentation development
* **Matthew Binsted**. Supporting data and documentation development
-------

* **Levi T. Sweet-Breu (@levisweetbreu)**
* **Melissa R. Allen-Dumas (@mallen2718)**

Contributors
------------

Additional Developers
^^^^^^^^^^^^^^^^^^^^^

* **Emily Rexer (@erexer)**
* **Chris R. Vernon (@crvernon)**
* **Matthew Seals**
* **Andy Berres (@q-rai)**
* **Stefan Krawczyk (@skrawcz)**
* **Elijah ben Izzy**

Product Tester
^^^^^^^^^^^^^^

* **Pouya Vahmani**

Code Formatting
^^^^^^^^^^^^^^^

* **black (`<https://black.readthedocs.io/en/stable/>`_)**
* **ruff (`<https://beta.ruff.rs/docs/>`_)**
22 changes: 11 additions & 11 deletions docs/source/contributing.rst
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
Contributing to **cerf**
Contributing to **naturf**
========================

Whether you find a typo in the documentation, find a bug, or want to develop functionality that you think will make **cerf** more robust, you are welcome to contribute!
Whether you find a typo in the documentation, find a bug, or want to develop functionality that you think will make **naturf** more robust, you are welcome to contribute!


Opening issues
______________

If you find a bug or would like to contribute a new feature, please `open an issue <https://github.com/IMMM-SFA/cerf/issues>`_ and select the template that fits your need.
If you find a bug or would like to contribute a new feature, please `open an issue <https://github.com/IMMM-SFA/naturf/issues>`_ and select the template that fits your need.


Contribution workflow
_____________________

The following is the recommended workflow for contributing to **cerf**:
The following is the recommended workflow for contributing to **naturf**:

1. `Fork the cerf repository <https://github.com/IMMM-SFA/cerf/fork>`_ and then clone it locally:
1. `Fork the naturf repository <https://github.com/IMMM-SFA/naturf/fork>`_ and then clone it locally:

.. code-block:: bash
git clone https://github.com/<your-user-name>/cerf
git clone https://github.com/<your-user-name>/naturf
Cloning the repository will give you access to the test suite. It is important to install the package in development mode before running tests. This will give you the flexibility to make changes in the code without having to rebuild your package before running tests. To do this run the following from your terminal in the **cerf** directory containing your ``setup.py`` script:
Cloning the repository will give you access to the test suite. It is important to install the package in development mode before running tests. This will give you the flexibility to make changes in the code without having to rebuild your package before running tests. To do this run the following from your terminal in the **naturf** directory containing your ``setup.py`` script:

.. code-block:: bash
Expand All @@ -40,21 +40,21 @@ The following is the recommended workflow for contributing to **cerf**:
3. Add your recommended changes and ensure all tests pass, then commit your changes:

Ensure your tests pass locally before pushing to your remote branch where GitHub actions will launch CI services to build the package, run the test suite, and evaluate code coverage. To do this, ensure that ``pytest`` has been installed then navigate to the root of your cloned directory (e.g., <my-path>/cerf) and simply execute ``pytest`` in the terminal.
Ensure your tests pass locally before pushing to your remote branch where GitHub actions will launch CI services to build the package, run the test suite, and evaluate code coverage. To do this, ensure that ``pytest`` has been installed then navigate to the root of your cloned directory (e.g., <my-path>/naturf) and simply execute ``pytest`` in the terminal.

.. code-block:: bash
git add <my-file-name>
git commit -m '<my short message>'
Changes to the documenation can be made in the ``cerf/docs/source`` directory containing the RST files. To view your changes, ensure you have the development dependencies of **cerf** installed and run the following from the ``cerf/docs/source`` directory:
Changes to the documenation can be made in the ``naturf/docs/source`` directory containing the RST files. To view your changes, ensure you have the development dependencies of **naturf** installed and run the following from the ``naturf/docs/source`` directory:

.. code-block:: bash
make html
This will generate your new documentation in a directory named ``cerf/docs/build/html``. You can open the ``index.html`` in your browser to view the documentation site locally. If your changes are merged into the main branch of **cerf**, changes in your documentation will go live as well.
This will generate your new documentation in a directory named ``naturf/docs/build/html``. You can open the ``index.html`` in your browser to view the documentation site locally. If your changes are merged into the main branch of **naturf**, changes in your documentation will go live as well.

4. Push your changes to the remote

Expand All @@ -67,4 +67,4 @@ The following is the recommended workflow for contributing to **cerf**:
- **Purpose**: The reason for your pull request in short
- **Summary**: A description of the environment you are using (OS, Python version, etc.), logic, any caveats, and a summary of changes that were made.

6. If approved, your pull request will be merged into the main branch by a **cerf** admin and a release will be conducted subsequently. **cerf** uses `semantic naming <https://semver.org/>`_ for versioned releases. Each release receives a DOI via a linked Zenodo service automatically.
6. If approved, your pull request will be merged into the main branch by a **naturf** admin and a release will be conducted subsequently. **naturf** uses `semantic naming <https://semver.org/>`_ for versioned releases. Each release receives a DOI via a linked Zenodo service automatically.
2 changes: 1 addition & 1 deletion docs/source/footer.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Acknowledgement
===============

**cerf** is actively developed as an open-source project as a part of the `Integrated Multisector Multiscale Modeling (IM3) <https://im3.pnnl.gov/>`_ project. IM3 is a multi-institutional effort led by Pacific Northwest National Laboratory and supported by the `U.S. Department of Energy’s Office of Science <https://www.energy.gov/science/office-science>`_ as part of research in `MultiSector Dynamics <https://climatemodeling.science.energy.gov/program/multisector-dynamics>`_, Earth and Environmental Systems Modeling Program.
**naturf** is actively developed as an open-source project as a part of the `Integrated Multisector Multiscale Modeling (IM3) <https://im3.pnnl.gov/>`_ project. IM3 is a multi-institutional effort led by Pacific Northwest National Laboratory and supported by the `U.S. Department of Energy’s Office of Science <https://www.energy.gov/science/office-science>`_ as part of research in `MultiSector Dynamics <https://climatemodeling.science.energy.gov/program/multisector-dynamics>`_, Earth and Environmental Systems Modeling Program.
163 changes: 89 additions & 74 deletions docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,91 +4,106 @@ Getting started
About
-----

The Capacity Expansion Regional Feasibility model (**cerf**) helps us evaluate the feasibility and structure of future electricity capacity expansion plans by siting power plants in areas that have been deemed the least cost option. We can use **cerf** to gain an understanding of topics such as: 1) whether or not future projected electricity expansion plans from models such as GCAM are possible to achieve, 2) where and which on-the-ground barriers to siting (e.g., protected areas, cooling water availability) may influence our ability to achieve certain expansions, and 3) how power plant infrastructure build outs and value may evolve into the future when considering locational marginal pricing (LMP) based on the supply and demand of electricity from a grid operations model.
The Neighborhood Adaptive Tissues for Urban Resilience Futures tool (**naturf**) enables the examination of the effect of urban morphology at variable resolutions on the urban microclimate through the Weather Research and Forecasting model (WRF). Following the work of Ching et al. (citation) on NUDAPT/WUDAPT, **naturf** calculates 132 urban parameters based on shapefiles of building footprints and heights; however, **naturf** is capable of compiling these urban parameters at finer, sub-kilometer resolutions than offered by NUDAPT/WUDAPT.

Each grid cell in **cerf** is given an initial value of suitable (0) or unsuitable (1) based on a collection of suitability criteria gleaned from the literature. **cerf**'s default suitability layers include both those that are common to all thermal technologies as well as technology-specific suitability criteria. Common suitability layers represent categories such as protected lands, critical habitat areas, and much more. Technology-specific suitability layers are those that satisfy requirements that may not be applicable to all technologies. An example would be minimum mean annual flow requirements for cooling water availability for individual thermal technologies.
**naturf** takes in building polygon shapefiles with height data and uses the Python package **geopandas** to calculate 132 urban parameters for each building that are compiled into a binary file. The name of the binary file as well as an automatically generated index file instructs WRF to place the binary data into the correct location in a geogrid. **naturf** also uses **hamilton** as a means of organizing, streamlining, and visualizing its workflow.

Though **cerf** provides sample data to run the conterminous United States (CONUS), it could be extended to function for any country or set of regions that had the following prerequisite data sources: a spatial representation of substations or electricity transmission infrastructure, a spatial representation of gas pipeline infrastructure if applicable, any regionally applicable spatial data to construct suitability rasters from, access to hourly zonal LMP, and access to technology-specific information and each technologies accompanying electricity capacity expansion plan per region. The Global Change Analysis Model (`GCAM <https://github.com/JGCRI/gcam-core>`_) is used to build our expansion plans and establish our technology-specific requirements through the end of the century. We derive our LMP from a grid operations model that also is harmonized with GCAM to provide consistent projections of energy system evolution. See more about how to generalize **cerf** for your research `here <user_guide.rst#generalization>`_.

We introduce a metric named Net Locational Cost (NLC) that is used compete power plant technologies for each grid cell based on the least cost option to site. NLC is calculated by subtracting the Net Operating Value (NOV) of a proposed power plant from the cost of its interconnection to the grid to represent the potential deployment value. Both the NOV parameter which incorporates many technology-specific values such as variable operations and maintenance costs, carbon price, heat rate, etc. and the interconnection cost parameter used for both electricity transmission and gas pipelines are configurable per time step. All equations used in **cerf** are described in detail in the `documentation <user_guide.rst#fundamental-equations-and-concepts>`_.


Python version support
----------------------

Officially Python 3.7, 3.8, and 3.9


Installation
------------

.. note::

**cerf** is not officially supported for Ubuntu 18 users due to a system dependency (``GLIBC_2.29``) required by the ``whitebox`` package which **cerf** uses to conduct spatial analysis. Ubuntu 18 natively includes ``GLIBC_2.27``. It may be possible for Ubuntu 18 users to upgrade to ``GLIBC_2.29`` but this should be done with careful consideration. Instead, we officially support **cerf** use for Ubuntu users for versions 20.04.2 LTS and greater.

**cerf** can be installed via pip by running the following from a terminal window::

pip install cerf

Conda/Miniconda users can utilize the ``environment.yml`` stored in the root of this repository by executing the following from a terminal window::

conda env create --file environment.yml

It may be favorable to the user to create a virtual environment for the **cerf** package to minimize package version conflicts. See `creating virtual environments <https://docs.python.org/3/library/venv.html>`_ to learn how these function and can be setup.

Installing package data
-----------------------

**cerf** requires package data to be installed from Zenodo to keep the package lightweight. After **cerf** has been installed, run the following from a Python prompt:

**NOTE**: The package data will require approximately 195 MB of storage.

.. code-block:: python
import cerf
cerf.install_package_data()
This will automatically download and install the package data necessary to run the examples in accordance with the version of **cerf** you are running. You can pass an alternative directory to install the data into (default is to install it in the package data directory) using ``data_dir``. When doing so, you must modify the configuration file to point to your custom paths.
Currently, **naturf** requires the shapefile inputs to first be separated into regular tiles, and it also requires a csv containing a index number for each of the tiles in the study area (todo: clarify). In tests of Los Angeles, regular tiles of 3.2 km x 3.2 km proved to be the most computationally efficient tile sizes, but any tile size that is a power of two is recommended.


Dependencies
------------

.. list-table::
:widths: 25 25
:header-rows: 1

* - Dependency
- Minimum Version
* - affine
- 2.4.0
* - appdirs
- 1.4.4
* - attrs
- 23.1.0
* - cachetools
- 5.3.1
* - certifi
- 2023.7.22
* - click
- 8.1.7
* - click-plugins
- 1.1.1
* - cligj
- 0.7.2
* - Fiona
- 1.9.4.post1
* - geocube
- 0.4.2
* - geopandas
- 0.14.0
* - graphvix
- 0.20.1
* - joblib
- 1.3.2
* - my-py-extensions
- 1.0.0
* - networkx
- 3.1
* - numpy
- 1.26.0
* - odc-geo
- 0.4.1
* - packaging
- 23.1
* - pandas
- 2.1.0
* - pyparsing
- 3.1.1
* - pyproj
- 3.6.0
* - python-dateutil
- 2.8.2
* - pytz
- 2023.3.post1
* - rasterio
- 1.3.8
* - rioxarray
- 0.15.0
* - Rtree
- 1.0.1
* - scipy
- 1.11.2
* - sf-hamilton
- 1.29.0
* - Shapely
- 1.8.5.post1
* - six
- 1.16.0
* - snuggs
- 1.4.7
* - typing-inspect
- 0.9.0
* - typing_extensions
- 0.9.0
* - tzdata
- 2023.3
* - xarray
- 2023.8.0

============= ================
Dependency Minimum Version
============= ================
numpy 1.19.4
pandas 1.1.4
rasterio 1.2.3
xarray 0.16.1
PyYAML 5.4.1
requests 2.25.1
numpy 1.22.4
pandas 1.4.2
geocube 0.3.1
rasterio 1.2.10
xarray 2022.3.0
joblib 1.0.1
matplotlib 3.3.3
seaborn 0.11.1
whitebox 1.5.1
fiona 1.8.19
pyproj 3.0.1
rtree 0.9.7
shapely 1.7.1
geopandas 0.9.0
rtree 1.0.0
shapely 1.8.2, <2
geopandas 0.10.2
sf-hamilton[visualization] 1.10
============= ================


Optional dependencies
---------------------

================== ================
Dependency Minimum Version
================== ================
build 0.5.1
nbsphinx 0.8.6
setuptools 57.0.0
sphinx 4.0.2
sphinx-panels 0.6.0
sphinx-rtd-theme 0.5.2
twine 3.4.1
pytest 6.2.4
pytest-cov 2.12.1
================== ================
24 changes: 2 additions & 22 deletions docs/source/how_to_cite.rst
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,4 @@
How to cite **cerf**
How to cite **naturf**
====================

Current software paper status:

.. image:: https://joss.theoj.org/papers/28fee3407bbbef020fb4bb19bd451407/status.svg
:target: https://joss.theoj.org/papers/28fee3407bbbef020fb4bb19bd451407

Vernon, C.R., Rice, J.S., Zuljevic, N., Mongird, K., Nelson, K., Iyer, G., Voisin, N., Binsted, M. (2021). cerf: A Python package to evaluate the feasibility and costs of power plant siting for alternative futures. Journal of Open Source Software, 6(65), 3601, https://doi.org/10.21105/joss.03601

**BibTex**:

@article{Vernon2021,
doi = {10.21105/joss.03601},
url = {https://doi.org/10.21105/joss.03601},
year = {2021},
publisher = {The Open Journal},
volume = {6},
number = {65},
pages = {3601},
author = {Chris R. Vernon and Jennie S. Rice and Nino Zuljevic and Kendall Mongird and Kristian Nelson and Gokul Iyer and Nathalie Voisin and Matthew Binsted},
title = {cerf: A Python package to evaluate the feasibility and costs of power plant siting for alternative futures},
journal = {Journal of Open Source Software}
}
Allen-Dumas, Melissa R., Sweet-Breu, Levi, Seals, Matthew, Berres, Andy, Vernon, Chris, and Rexer, Emily. NATURF. Computer Software. https://github.com/IMMM-SFA/naturf. USDOE Office of Science (SC), Biological and Environmental Research (BER). Earth and Environmental Systems Science Division. 31 Aug. 2022. Web. doi:10.11578/dc.20220803.4.
8 changes: 4 additions & 4 deletions docs/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ naturf documentation
`Issues & Ideas <https://github.com/immm-sfa/naturf/issues>`_ |
`Interactive Quickstarter <quickstarter.rst>`_

**naturf** is an open-source geospatial Python package for evaluating and analyzing future electricity technology capacity expansion feasibility. **naturf** was created to:
**naturf** is an open-source geospatial Python package for calculating urban building parameters to be compiled and input to the Weather Research and Forecasting model (WRF). **naturf** was created to:

1) Evaluate the feasibility of a future scenario-driven electricity technology capacity expansion plan as generated by a parent model,
1) Calculate 132 urban parameters based on building footprints and height,

2) Site power plants in the least cost configuration when considering regional economics an on-the-ground barriers to siting,
2) Compile the parameters at sub-kilometer resolutions into binary files,

3) Assist planners and modelers of alternate future realizations of the electricity system to gain an understanding of how siting costs and service area congestion may respond under certain stressors.
3) Prepare binary files to be fed into WRF to understand the effect of building morphology on the urban microclimate.


.. panels::
Expand Down
Loading

0 comments on commit d5437c8

Please sign in to comment.