Added repository contents

.gitignore

@@ -0,0 +1,12 @@
+MCOR_error_messages.log
+.DS_Store
+.cache
+.idea
+__pycache__
+venv/
+data/*
+main_files/*
+output/*
+solar_data/*
+creds.yaml
+tests/system_tests/data/solar_data/*

LICENSE

@@ -0,0 +1,13 @@
+MCOR: Microgrid Component Optimization for Resilience
+
+Copyright © 2022, Battelle Memorial Institute
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,2 +1,157 @@
-# MCOR
-Microgrid Component Optimization for Resiliency Tool
+# Microgrid Component Optimization for Resilience (MCOR) Tool
+
+The goal of the MCOR tool is to provide several viable microgrid configurations that can meet 
+the resilience goals of a site and maximize economic benefits. This means meeting a set of 
+critical loads for a specified period of time, without any power supply from the electrical 
+grid. The tool simulates power dispatch for many different system configurations, and ranks 
+the systems according to the goals of the site. 
+
+## Getting Started
+
+### Prerequisites
+
+* Python 3
+* pvlib:
+  https://github.com/pvlib/pvlib-python.git
+* numba
+  Install numba to speed up solar power calculation:
+  http://numba.pydata.org/#installing
+
+To install required packages:
+``` pip install -r requirements.txt```
+
+### Set-up
+You will need to create your own credentials file with an NREL API key in order to download 
+historical solar data from the NSRDB. To do so:
+1. Sign up for an API key here: https://developer.nrel.gov/signup/
+2. Create a file called creds.yaml in the root directory and then add your email address and 
+API key to the file. 
+The file should have the following format:
+```yaml
+nrel_api_key: <your key>
+nrel_api_email: <your email>
+```
+
+### How to run MCOR
+To run MCOR, update the parameter values in the first half of main.py (or your site-specific
+copy of main.py) under the section titled "Define simulation parameters here". Then run 
+main.py in either a terminal or your IDE of choice.
+  
+## Contents
+
+### data/
+Includes input data such as component costs, generator specs, and validation requirements.
+
+### main_files/main.py
+Script for running MCOR from the command line. This file must be copied and 
+modified to include site parameters.
+
+### output/
+Output data from an MCOR run is saved here (Excel and pkl files).
+
+### solar_data/
+Includes downloaded NREL solar data and generated solar profile files that are created when
+running MCOR.
+
+### testing/
+Unit and integration tests.
+
+### alternative_solar_profiles.py
+Alternative Solar Profiles (ASP) algorithm used for solar forecasting:
+Original author in MATLAB: James Follum and Trevor Hardy
+
+#### File contents:
+Classes:
+* AlternativeSolarProfiles
+
+Standalone functions:
+* date_parser
+
+### creds.py
+Includes credentials for NREL api key.
+
+### config.py
+Includes repository paths.
+
+### generate_solar_profile.py
+Calls the ASP code and calculates AC power production.
+
+Solar power calculations carried out with pvlib-python:
+    https://github.com/pvlib/pvlib-python
+
+For an explanation of the pvlib power calculation:
+    http://nbviewer.jupyter.org/github/pvlib/pvlib-python/blob/master/docs/tutorials/pvsystem.ipynb
+
+#### File contents:
+Classes:
+* SolarProfileGenerator
+
+Standalone functions:
+* download_solar_data
+* calc_pv_prod
+* calc_night_duration
+* parse_himawari_tmy
+
+### microgrid_optimizer.py
+Optimization class for simulating, filtering and ranking microgrid systems.
+
+#### File contents:
+Classes:
+* Optimizer
+* GridSearchOptimizer (inherits from Optimizer)
+
+Standalone functions:
+* get_electricity_rate
+
+### microgrid_simulator.py
+Microgrid simulator class. Includes the core of the system dispatch algorithm.
+
+#### File Contents:
+Classes:
+* Simulator
+* PVBattGenSimulator (inherits from Simulator)
+
+Standalone functions:
+* calculate_load_duration
+
+### microgrid_system.py
+Class structure for microgrid system and its components.
+
+#### File contents:
+Classes:
+* Component
+* PV (inherits from Component)
+* Battery (inherits from Component)
+* SimpleLiIonBattery (inherits from Battery)
+* Generator (inherits from Component)
+* FuelTank (inherits from Component)
+* MicrogridSystem
+* SimpleMicrogridSystem (inherits from MicrogridSystem)
+
+### validation.py
+Classes:
+* Error
+* ParamValidationError (inherits from Error)
+
+Standalone functions:
+* log_error
+* validate_all_parameters
+* validate_parameter
+* ...various custom validation functions
+
+## Contact
+For questions, please reach out to [email protected]
+
+## Disclaimer Notice
+This material was prepared as an account of work sponsored by an agency of the United States Government.  Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
+Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
+<div align="center">
+<pre style="align-text:center">
+PACIFIC NORTHWEST NATIONAL LABORATORY
+operated by
+BATTELLE
+for the
+UNITED STATES DEPARTMENT OF ENERGY
+under Contract DE-AC05-76RL01830
+</pre>
+</div>