updated to create distribution first (#29)

* updated to create distribution first * added build command and removed twine installation
NREL · Jun 5, 2024 · a5a2d0a · a5a2d0a
commit a5a2d0a
Show file tree

Hide file tree

Showing 61 changed files with 9,031 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 106b74bed5da436d5d4879714fecf9c1
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
diff --git a/_sources/api/der-scenario.rst.txt b/_sources/api/der-scenario.rst.txt
@@ -0,0 +1,7 @@
+========
+Scenario
+========
+
+.. autofunction:: emerge.scenarios.scenario.create_der_scenarios
+
+.. autofunction:: emerge.scenarios.scenario.generate_scenarios
diff --git a/_sources/api/enumerations.rst.txt b/_sources/api/enumerations.rst.txt
@@ -0,0 +1,12 @@
+============
+Enumerations
+============
+
+.. autoclass:: emerge.scenarios.data_model.DERType
+    :members:
+
+.. autoclass:: emerge.scenarios.data_model.CapacityStrategyEnum
+    :members:
+
+.. autoclass:: emerge.scenarios.data_model.SelectionStrategyEnum
+    :members:
diff --git a/_sources/api/index.rst.txt b/_sources/api/index.rst.txt
@@ -0,0 +1,13 @@
+=============
+Documentation
+=============
+
+.. toctree::
+    :maxdepth: 2
+    :caption: References
+
+    der-scenario
+    selection-strategy
+    sizing-strategy
+    scenario-data-model
+    enumerations
diff --git a/_sources/api/scenario-data-model.rst.txt b/_sources/api/scenario-data-model.rst.txt
@@ -0,0 +1,33 @@
+====================
+Scenario Data Models
+====================
+
+.. autopydantic_model:: emerge.scenarios.data_model.CustomerModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.EnergyBasedSolarSizingStrategyInput
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.SizeWithProbabilityModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.DERScenarioInput
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.BasicDERModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.DistDERScenarioModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.LoadMetadataModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.DERScenarioInputModel
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.ScenarioBaseConfig
+   :members: 
+
+.. autopydantic_model:: emerge.scenarios.data_model.DERScenarioConfigModel
+   :members: 
diff --git a/_sources/api/selection-strategy.rst.txt b/_sources/api/selection-strategy.rst.txt
@@ -0,0 +1,15 @@
+==================
+Selection Strategy
+==================
+
+
+.. autoclass:: emerge.scenarios.selection_strategy.RandomSelectionStrategy
+    :members:
+
+.. autoclass:: emerge.scenarios.selection_strategy.CloseSelectionStrategy
+    :members:
+
+.. autoclass:: emerge.scenarios.selection_strategy.FarSelectionStrategy
+    :members:
+
+
diff --git a/_sources/api/sizing-strategy.rst.txt b/_sources/api/sizing-strategy.rst.txt
@@ -0,0 +1,13 @@
+==================
+Sizing Strategy
+==================
+
+
+.. autoclass:: emerge.scenarios.sizing_strategy.EnergyBasedSolarSizingStrategy
+    :members:
+
+.. autoclass:: emerge.scenarios.sizing_strategy.PeakMultiplierSizingStrategy
+    :members:
+
+.. autoclass:: emerge.scenarios.sizing_strategy.FixedSizingStrategy
+    :members:
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
@@ -0,0 +1,43 @@
+# Emerge
+
+<p align="center"> 
+<img src="_static/logo.svg" width="150" style="display:flex;justify-content:center;">
+<p align="center"> Managing power flow simulations and DER scenario generation the simple way. </p>
+</p>
+
+Currently EMERGE uses OpenDSSDirect for performing power flow. 
+
+
+![GitHub all releases](https://img.shields.io/github/downloads/NREL/emerge/total?logo=Github&logoColor=%2300ff00&style=flat-square)
+![GitHub repo size](https://img.shields.io/github/repo-size/nrel/emerge?style=flat-square)
+![CodeFactor Grade](https://img.shields.io/codefactor/grade/github/nrel/emerge?color=%23ff0000&logo=python&logoColor=%2300ff00&style=flat-square)
+[![GitHub license](https://img.shields.io/github/license/NREL/emerge?style=flat-square)](https://github.com/NREL/emerge/blob/main/LICENSE.txt)
+[![GitHub issues](https://img.shields.io/github/issues/NREL/emerge?style=flat-square)](https://github.com/NREL/emerge/issues)
+![GitHub top language](https://img.shields.io/github/languages/top/nrel/emerge?style=flat-square)
+---
+## Installation Instruction
+
+You can install latest version of EMERGE from PyPi.
+
+```bash
+pip install NREL-Emerge
+```
+
+```{toctree}
+:caption: Documentation
+:hidden: true
+
+api/index
+```
+
+```{toctree}
+:caption: Usage
+
+usage/index
+```
+
+```{eval-rst}
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+```
diff --git a/_sources/usage/developing-scenarios.md.txt b/_sources/usage/developing-scenarios.md.txt
@@ -0,0 +1,168 @@
+# Developing Scenarios
+You can develop scenarios in two ways.
+
+## Developing Scenario Using Python 
+
+Here is an example snippet you can use to develop and write der deployment scenario.
+EMERGE only supports writing scenarios in OpenDSS file format.
+
+```python
+from emerge.scenarios import data_model
+from emerge.scenarios.scenario import generate_scenarios
+
+config = data_model.DERScenarioConfigModel(
+    master_file="Master.dss",
+    output_folder="der_scenarios",
+    pct_resolution=20,
+    num_of_penetration=5,
+    max_num_of_samples=25,
+    der_scenario=[
+        data_model.DERScenarioInputModel(
+            sizing_strategy=data_model.CapacityStrategyEnum.peak_multiplier,
+            der_type=data_model.DERType.solar,
+            der_tag="solar",
+            file_name="pvsystem.dss",
+            peakmult_sizing_input={
+                "0": data_model.SizeWithProbabilityModel(
+                    sizes=0.87, profile="residential_solar", probabilites=1
+                ),
+                "1": data_model.SizeWithProbabilityModel(
+                    sizes=2.68, profile="commercial_solar", probabilites=1
+                ),
+            },
+            selection_strategy=data_model.SelectionStrategyEnum.random_allocation,
+            other_ders=[
+                data_model._DERScenarioInput(
+                    sizing_strategy=data_model.CapacityStrategyEnum.peak_multiplier,
+                    der_type=data_model.DERType.load,
+                    der_tag="battery",
+                    peakmult_sizing_input={
+                        "0": data_model.SizeWithProbabilityModel(
+                            sizes=0.356, profile="residential_battery", probabilites=1
+                        ),
+                        "1": data_model.SizeWithProbabilityModel(
+                            sizes=0.2625, profile="commercial_battery", probabilites=1
+                        ),
+                    },
+                ),
+                data_model._DERScenarioInput(
+                    sizing_strategy=data_model.CapacityStrategyEnum.fixed_sizing,
+                    der_type=data_model.DERType.load,
+                    der_tag="ev",
+                    fixed_sizing_input={
+                        "0": data_model.SizeWithProbabilityModel(
+                            sizes=[1.2, 7.6],
+                            probabilites=[0.8, 0.2],
+                            profile = ["residential_level1_ev", "residential_level2_ev"],
+                        )
+                    }
+                )
+            ],
+        )
+    ],
+)
+
+generate_scenarios(config_data=config)
+```
+
+In the above example, we are generating scenarios for 5 penetration levels in the step of 20% (percentage is based on sum of kw from all loads before applying loadshapes.) and each scenario is generated 25 times indicated by `max_num_sample`. User can configure multiple combination of DERs in `der_scenario` field. In this case our primary DER is roof top solar but we also want the same customer to have battery and electric vehicle as specified in `other_ders` field. The solar is sized based using peak multiplier strategy (i.e. size is determined by multiplying user specified multiplier with peak of individual load). 
+
+You can pass different multipliers for different groups of loads. In this case we have two groups of load "0" and "1". By default EMEREG reads `class` attribute for each load in OpenDSS to determine which group they belong to. You can also use `yearly` attribute to determine class of the load. All roof top solars are selected based on random selection strategy.
+
+Battries are sized using peak multiplier sizing strategy howvever electric vehicles are  sized based on fixed sizing strategy. Notice you don't have to specify selection strategy for other ders that is because it is decided using primary der which is solar in this case. For electric vehicles we are only selecting load of type "0" and distributing level 1 charger (1.2 kW) for 20% of customers and level 2 charger (7.6 kW) for 80% of the customer. 
+
+
+## Developing scenarios using Command Line Interface 
+
+To develop scenarios using command line interface you can use following command. 
+
+```
+(cleap) C:\Users\john>emerge generate-scenarios --help
+Usage: emerge generate-scenarios [OPTIONS]
+
+  Function to create PV deloyment scenarios.
+
+Options:
+  -c, --config TEXT  Path to config file for generating scenarios
+  --help             Show this message and exit.
+```
+
+You will need to create a JSON file and pass it's path to -c flag.
+
+```
+emerge generate-scenarios -c scenario.json
+```
+
+Here is an example JSON. 
+
+```json
+{
+    "master_file": "Master_new.dss",
+    "output_folder": "der_scenarios",
+    "pct_resolution": 20,
+    "num_of_penetration": 5,
+    "max_num_of_samples": 25,
+    "der_scenario": [
+      {
+        "sizing_strategy": "peak_multiplier",
+        "der_type": "solar",
+        "der_tag": "solar",
+        "file_name": "pvsystems.dss",
+        "peakmult_sizing_input": {
+          "0":  {
+            "sizes":0.87,
+            "profile":"residential_solar",
+            "probabilites":1
+          },
+          "1": {
+            "sizes":2.68,
+            "profile":"commercial_solar",
+            "probabilites":1
+          }
+        },
+        "selection_strategy": "random_allocation",
+        "other_ders": [{
+            "sizing_strategy": "peak_multiplier",
+            "der_type": "load",
+            "peakmult_sizing_input": {
+                "0":  {
+                    "sizes":0.356,
+                    "profile":"residential_battery",
+                    "probabilites":1
+                  },
+                "1": {
+                    "sizes":0.2625,
+                    "profile":"commerical_battery",
+                    "probabilites":1
+                  }
+            },
+            "der_tag": "battery"
+        },
+        {
+          "sizing_strategy": "fixed_sizing",
+          "der_type": "load",
+          "fixed_sizing_input": {
+            "0":  {
+                "sizes":[1.2, 7.6],
+                "profile": ["residential_level1_ev", "residential_level2_ev"],
+                "probabilites":[0.8,0.2]
+              }
+          },
+          "der_tag": "EV"
+      }]
+      }
+    ]
+  }
+
+```
+
+## Adding Scenario JSON Schema to VSCode.
+
+You can add JSON Schema to your code editor of choice to get auto completion and validation as you type
+out your JSON file. Use the command below to generate schema and add to VScode.
+
+```
+emerge create-schemas --vscode "true"
+```
+This will create a `emerge_scenario_schema.json` file within `.vscode` directory. If the directory is not present then it will
+create one for you and dump the file. It will also update `json.schemas`` field in `settings.json` file. 
diff --git a/_sources/usage/index.rst.txt b/_sources/usage/index.rst.txt
@@ -0,0 +1,10 @@
+=====
+Usage
+=====
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Usage
+
+    developing-scenarios
+    nodal-hosting-capacity
diff --git a/_sources/usage/nodal-hosting-capacity.md.txt b/_sources/usage/nodal-hosting-capacity.md.txt
@@ -0,0 +1,26 @@
+# Solar Nodal Hosting Capacity Analysis
+
+You can run nodal hosting capacity analysis using emerge cli. Here is an example json config file you can use to run the simulation.
+
+Make sure to define load shape for solar profile in the master dss file.
+
+```json
+{
+    "start_time": "2023-01-08T00:00:00+00:00",
+    "end_time": "2023-01-15T00:00:00+00:00",
+    "profile_start_time": "2023-01-01T00:00:00+00:00",
+    "resolution_min": 60, 
+    "step_kw": 1000,
+    "max_kw": 20000,
+    "num_core": 10,
+    "pv_profile": "PV_Profile",
+    "export_sqlite_path": "hosting_capacity.db",
+    "master_dss_file": "master_with_loadshapes.dss"
+}
+```
+
+You can use following command to run nodal hosting capacity.
+
+```bash
+emerge nodal-hosting-analysis -c config.json
+```
diff --git a/_static/autodoc_pydantic.css b/_static/autodoc_pydantic.css
@@ -0,0 +1,11 @@
+.autodoc_pydantic_validator_arrow {
+  padding-left: 8px;
+  }
+
+.autodoc_pydantic_collapsable_json {
+  cursor: pointer;
+  }
+
+.autodoc_pydantic_collapsable_erd {
+  cursor: pointer;
+  }