emthub 0.0.1__tar.gz

emthub-0.0.1/LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Meltran, Inc
+
+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.

emthub-0.0.1/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.1
+Name: emthub
+Version: 0.0.1
+Summary: EMTHub: Electromagnetic transient model-building and validation.
+Home-page: https://github.com/temcdrm/EMTHub
+Author: Tom McDermott
+Author-email: tom@meltran.com
+License: BSD
+Project-URL: Bug Tracker, https://github.com/temcdrm/EMTHub/issues
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: SPARQLWrapper>=2.0.0
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: pandas>=1.4.3
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: scipy>=1.8.1
+
+# EMTHub™
+
+Software and data schemas for standards-based model building and 
+validation to perform electromagnetic transient (EMT) studies of electric 
+utility power systems. The focus is on inverter-based resources (IBR), 
+e.g., wind, solar, and storage, in electric utility systems. 
+
+Use the Green Code button to download.
+
+- End users may now follow the two-step installation described in the next section.
+- Developers may now use `git clone https://github.com/temcdrm/emthub.git` from a local directory.
+
+## Users
+
+The Blazegraph triple-store database is required, but unlike [CIMHub](https://github.com/GRIDAPPSD/CIMHub/tree/feature/SETO), Java, Docker, and OpenDSS are not required.
+
+- Install Blazegraph 2.1.6 from [Blazegraph Releases](https://github.com/blazegraph/database/releases).
+- Invoke `pip install emthub --upgrade`.
+
+### Alternative Transients Program (ATP)
+
+Some optional features of the software require a license to use ATP. See [ATP Web Site](https://atp-emtp.org/) for more information, and to apply for an ATP license.
+
+## Developers
+
+Install Blazegraph and clone this repository, then use `pip install -e .` to install the Python emthub package from your git clone.
+
+To deploy the project on PyPi, staring in the directory of your git clone, where `setup.py` is located:
+
+- Make sure that the version number in `setup.cfg` and `src\emthub\version.py` is new.
+- Invoke `rd /s /q dist` on Windows (would be `rm -rf dist` on Linux or Mac OS X)
+- `python -m build`
+- `twine check dist/*` should not show any errors
+- `twine upload -r testpypi dist/*` requires project credentials for pecblocks on test.pypi.org (Note: this will reject if version already exists, also note that testpypi is a separate register to pypi)
+- `pip install -i https://test.pypi.org/simple/ emthub==0.0.1` for local testing of the deployable package, example version 0.0.1 (Note: consider doing this in a separate Python test environment)
+- `twine upload dist/*` for final deployment
+
+Copyright 2024, Meltran, Inc
+

emthub-0.0.1/README.md

@@ -0,0 +1,39 @@
+# EMTHub™
+
+Software and data schemas for standards-based model building and 
+validation to perform electromagnetic transient (EMT) studies of electric 
+utility power systems. The focus is on inverter-based resources (IBR), 
+e.g., wind, solar, and storage, in electric utility systems. 
+
+Use the Green Code button to download.
+
+- End users may now follow the two-step installation described in the next section.
+- Developers may now use `git clone https://github.com/temcdrm/emthub.git` from a local directory.
+
+## Users
+
+The Blazegraph triple-store database is required, but unlike [CIMHub](https://github.com/GRIDAPPSD/CIMHub/tree/feature/SETO), Java, Docker, and OpenDSS are not required.
+
+- Install Blazegraph 2.1.6 from [Blazegraph Releases](https://github.com/blazegraph/database/releases).
+- Invoke `pip install emthub --upgrade`.
+
+### Alternative Transients Program (ATP)
+
+Some optional features of the software require a license to use ATP. See [ATP Web Site](https://atp-emtp.org/) for more information, and to apply for an ATP license.
+
+## Developers
+
+Install Blazegraph and clone this repository, then use `pip install -e .` to install the Python emthub package from your git clone.
+
+To deploy the project on PyPi, staring in the directory of your git clone, where `setup.py` is located:
+
+- Make sure that the version number in `setup.cfg` and `src\emthub\version.py` is new.
+- Invoke `rd /s /q dist` on Windows (would be `rm -rf dist` on Linux or Mac OS X)
+- `python -m build`
+- `twine check dist/*` should not show any errors
+- `twine upload -r testpypi dist/*` requires project credentials for pecblocks on test.pypi.org (Note: this will reject if version already exists, also note that testpypi is a separate register to pypi)
+- `pip install -i https://test.pypi.org/simple/ emthub==0.0.1` for local testing of the deployable package, example version 0.0.1 (Note: consider doing this in a separate Python test environment)
+- `twine upload dist/*` for final deployment
+
+Copyright 2024, Meltran, Inc
+

emthub-0.0.1/setup.cfg

@@ -0,0 +1,50 @@
+[bdist_wheel]
+universal = 1
+
+[metadata]
+name = emthub
+version = 0.0.1
+author = Tom McDermott
+author_email = tom@meltran.com
+description = EMTHub: Electromagnetic transient model-building and validation.
+long_description = file: README.md
+long_description_content_type = text/markdown
+license_files = LICENSE.txt
+license = BSD
+url = https://github.com/temcdrm/EMTHub
+project_urls = 
+	Bug Tracker = https://github.com/temcdrm/EMTHub/issues
+classifiers = 
+	License :: OSI Approved :: BSD License
+	Operating System :: OS Independent
+	Programming Language :: Python :: 3.8
+	Development Status :: 3 - Alpha
+	Environment :: Console
+	Intended Audience :: Developers
+	Intended Audience :: Education
+	Intended Audience :: Science/Research
+	Topic :: Scientific/Engineering
+
+[options]
+zip_safe = False
+include_package_data = True
+package_dir = 
+	= src
+install_requires = 
+	SPARQLWrapper>=2.0.0
+	numpy>=1.23.0
+	pandas>=1.4.3
+	lxml>=4.9.0
+	scipy>=1.8.1
+
+[options.packages.find]
+where = src_python
+
+[options.package_data]
+cimhub = 
+	*.json
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

emthub-0.0.1/setup.py

@@ -0,0 +1,3 @@
+import setuptools
+setuptools.setup()
+

emthub-0.0.1/src/emthub/ClearDB.py

@@ -0,0 +1,26 @@
+# Copyright (C) 2018-2023 Battelle Memorial Institute
+# Copyright (C) 2024 Meltran, Inc
+"""Clear the Blazegraph database.
+"""
+from SPARQLWrapper import SPARQLWrapper2
+import re
+import emthub.EMTHubConfig as EMTHubConfig
+
+drop_all = """drop all
+"""
+
+def clear_db (cfg_file=None):
+  """ Clear the database.
+
+  Blazegraph must already be started. If not already configured, cfg_file must be provided.
+
+  Args:
+    cfg_file (str): configuration file for Blazegraph.
+  """
+  if cfg_file is not None:
+    EMTHubConfig.ConfigFromJsonFile (cfg_file)
+  sparql = SPARQLWrapper2 (EMTHubConfig.blazegraph_url)
+  sparql.method = 'POST'
+  sparql.setQuery (drop_all)
+  ret = sparql.query()
+

emthub-0.0.1/src/emthub/CountClasses.py

@@ -0,0 +1,96 @@
+# Copyright (C) 2018-2023 Battelle Memorial Institute
+# Copyright (C) 2024 Meltran, Inc
+"""List and count the instances of classes found in a Blazegraph database.
+"""
+from SPARQLWrapper import SPARQLWrapper2
+import os
+import emthub.EMTHubConfig as EMTHubConfig
+
+def clear_database (sparql):
+  sparql.method = 'POST'
+  sparql.setQuery(EMTHubConfig.prefix + 
+  """
+  DROP ALL
+  """)
+  return sparql.query()
+
+def count_classes (sparql):
+  sparql.method = 'GET'
+  sparql.setQuery(EMTHubConfig.prefix + 
+  """
+  SELECT ?class (COUNT(?class) as ?cnt)
+  WHERE {
+    ?s a ?rawclass .
+    bind(strafter(str(?rawclass),"#") as ?class)
+  } group by ?class order by ?class
+  """)
+  return sparql.query()
+
+def count_platform_circuit_classes (cfg_file=None, xml_path = '../model_output_tests/'):
+  """ Counts the class instances found in CIMHub's distribution test feeders.
+
+  Blazegraph must already be started. If not already configured, cfg_file must be provided.
+  The test feeder CIM XML files, as exported from OpenDSS, must already exist in xml_path.
+  Use this function as a template for summarizing BES test cases.
+  Writes to console, and writes summary files to xml_path.
+
+  Args:
+    cfg_file (str): configuration file for Blazegraph.
+    xml_path (str): relative path for reading CIM XML and writing summary files.
+  """
+  if cfg_file is not None:
+    EMTHubConfig.ConfigFromJsonFile (cfg_file)
+
+  sparql = SPARQLWrapper2(EMTHubConfig.blazegraph_url)
+
+  xml_files = {'ACEP_PSIL':{}, 
+               'EPRI_DPV_J1':{}, 
+               'IEEE123':{}, 
+               'IEEE123_PV':{}, 
+               'IEEE13':{}, 
+               'IEEE13_Assets':{},
+               'IEEE37':{}, 
+               'IEEE8500':{}, 
+               'IEEE8500_3subs':{}, 
+               'R2_12_47_2':{}, 
+               'Transactive':{}
+               }
+  all_classes = []
+
+  for fname in xml_files:
+    clear_database (sparql)
+    cmd = 'curl -D- -H "Content-Type: application/xml" --upload-file ' + xml_path + fname + '.xml' + ' -X POST ' + EMTHubConfig.blazegraph_url
+    os.system (cmd)
+    ret = count_classes (sparql)
+    for b in ret.bindings:
+      cls = b['class'].value
+      cnt = b['cnt'].value
+      xml_files[fname][cls] = cnt
+      if cls not in all_classes:
+        all_classes.append (cls)
+
+  csvfile = xml_path + 'class_counts.csv'
+  mdfile = xml_path + 'class_counts.md'
+  print ('Writing Class Summaries to {:s} and {:s}'.format (csvfile, mdfile))
+  fp1 = open (csvfile, 'w')
+  fp2 = open (mdfile, 'w')
+
+  print ('Class,' + ','.join(xml_files.keys()), file=fp1)
+  print ('| Class | ' + ' | '.join(xml_files.keys()) + ' |', file=fp2)
+  mdhdr = '| :--- |'
+  for fname in xml_files.keys():
+    mdhdr = mdhdr + ' :---: |'
+  print (mdhdr, file=fp2)
+
+  for cls in sorted (all_classes):
+    counts = []
+    for fname in xml_files.keys():
+      cnt = '0'
+      if cls in xml_files[fname]:
+        cnt = xml_files[fname][cls]
+      counts.append (cnt)
+    print (cls + ',' + ','.join(counts), file=fp1)
+    print ('| ' + cls + ' | ' + ' | '.join(counts) + ' |', file=fp2)
+
+  fp1.close()
+  fp2.close()

emthub-0.0.1/src/emthub/EMTHubConfig.py

@@ -0,0 +1,63 @@
+# Copyright (C) 2018-2023 Battelle Memorial Institute
+# Copyright (C) 2024 Meltran, Inc
+# file: EMTHubConfig.py
+"""Set the CIM namespace and Blazegraph URL.
+"""
+import json
+import urllib.request
+
+DB_URL = ''
+EMTHUB_PATH = ''
+EMTHUB_PROG = ''
+
+#******************************************************************************
+# URL for the lyrasis Blazegraph container
+blazegraph_url = "http://localhost:8889/bigdata/namespace/kb/sparql"
+
+#******************************************************************************
+# Default prefix for blazegraph queries; canonical version is now CIM100
+
+cim100 = '<http://iec.ch/TC57/CIM100#'
+# Prefix for all queries.
+prefix = """PREFIX r: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX c: {cimURL}>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+""".format(cimURL=cim100)
+
+def ConfigFromJsonFile (fname):
+  """ Sets the CIM namespace and Blazegraph database URL.
+
+  Blazegraph must already be started. The configuration file should be JSON
+  and include the following:
+
+  - blazegraph_url (required): for HTTP queries to Blazegraph
+  - cim_ns (required): namespace for the version of CIM used
+  - use_proxy: *true* if your computer runs a proxy server, e.g., using a VPN
+
+  Args:
+    fname (str): a JSON configuration file for Blazegraph.
+  """
+  global blazegraph_url, prefix, cim_ns, DB_URL, EMTHUB_PATH, EMTHUB_PROG
+  with open(fname) as fp: 
+    cfg = json.load(fp)
+    if 'blazegraph_url' in cfg:
+      blazegraph_url = cfg['blazegraph_url']
+      DB_URL = blazegraph_url
+#      print ('Configured URL to', blazegraph_url)
+    if 'cim_ns' in cfg:
+      cim_ns = cfg['cim_ns']
+      prefix = """PREFIX r: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+PREFIX c: {cimURL}>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+""".format(cimURL=cim_ns)
+#      print ('Configured CIM Namespace to', cim_ns)
+    if 'use_proxy' in cfg:
+      if cfg['use_proxy'] == True:
+        proxy_support = urllib.request.ProxyHandler({})
+        opener = urllib.request.build_opener(proxy_support)
+        urllib.request.install_opener(opener)
+    if 'EMTHUB_PATH' in cfg:
+      EMTHUB_PATH = cfg['EMTHUB_PATH']
+    if 'EMTHUB_PROG' in cfg:
+      EMTHUB_PROG = cfg['EMTHUB_PROG']
+

emthub-0.0.1/src/emthub/ListBES.py

@@ -0,0 +1,45 @@
+# Copyright (C) 2018-2023 Battelle Memorial Institute
+# Copyright (C) 2024 Meltran, Inc
+"""List the bulk electric systems found in a Blazegraph database.
+"""
+from SPARQLWrapper import SPARQLWrapper2
+import emthub.EMTHubConfig as EMTHubConfig
+import sys
+
+def list_bes (cfg_file=None):
+  """ List the names and mRID values of bulk electric systems (BES) found in the Blazegraph database.
+
+  Blazegraph must already be started. If not already configured, cfg_file must be provided.
+  Writes a list of BES names and mRIDs to the console.
+
+  Args:
+    cfg_file (str): configuration file for Blazegraph.
+  """
+
+  if cfg_file is not None:
+    EMTHubConfig.ConfigFromJsonFile (cfg_file)
+
+  sparql = SPARQLWrapper2(EMTHubConfig.blazegraph_url)
+
+  sparql.setQuery(EMTHubConfig.prefix + 
+      """
+      SELECT ?name ?id WHERE {
+       ?s r:type c:ConnectivityNodeContainer.
+       ?s c:IdentifiedObject.name ?name.
+       ?s c:IdentifiedObject.mRID ?id.
+      }
+      ORDER by ?name
+  """)
+
+  ret = sparql.query()
+  #print ('binding keys are:',ret.variables)
+  print ('Bulk Electric System names and mRIDs:')
+  for b in ret.bindings:
+    print (b['name'].value,b['id'].value)
+
+if __name__ == '__main__':
+  cfg_file = None
+  if len(sys.argv) > 1:
+    cfg_file = sys.argv[1]
+  list_bes (cfg_file)
+

emthub-0.0.1/src/emthub/ListFeeders.py

@@ -0,0 +1,54 @@
+# Copyright (C) 2018-2023 Battelle Memorial Institute
+# Copyright (C) 2024 Meltran, Inc
+"""List the distribution feeders found in a Blazegraph database.
+"""
+from SPARQLWrapper import SPARQLWrapper2
+import emthub.EMTHubConfig as EMTHubConfig
+import sys
+
+def list_feeders (cfg_file=None):
+  """ List the names and mRID values of distribution feeders found in the Blazegraph database.
+
+  Blazegraph must already be started. If not already configured, cfg_file must be provided.
+  Writes a list of feeder names and mRIDs to the console.
+
+  Args:
+    cfg_file (str): configuration file for Blazegraph.
+  """
+
+  if cfg_file is not None:
+    EMTHubConfig.ConfigFromJsonFile (cfg_file)
+
+  sparql = SPARQLWrapper2(EMTHubConfig.blazegraph_url)
+
+  sparql.setQuery(EMTHubConfig.prefix + 
+      """
+      SELECT ?feeder ?fid ?station ?sid ?subregion ?sgrid ?region ?rgnid WHERE {
+       ?s r:type c:Feeder.
+       ?s c:IdentifiedObject.name ?feeder.
+       ?s c:IdentifiedObject.mRID ?fid.
+       ?s c:Feeder.NormalEnergizingSubstation ?sub.
+       ?sub c:IdentifiedObject.name ?station.
+       ?sub c:IdentifiedObject.mRID ?sid.
+       ?sub c:Substation.Region ?sgr.
+       ?sgr c:IdentifiedObject.name ?subregion.
+       ?sgr c:IdentifiedObject.mRID ?sgrid.
+       ?sgr c:SubGeographicalRegion.Region ?rgn.
+       ?rgn c:IdentifiedObject.name ?region.
+       ?rgn c:IdentifiedObject.mRID ?rgnid.
+      }
+      ORDER by ?station ?feeder
+  """)
+
+  ret = sparql.query()
+  #print ('binding keys are:',ret.variables)
+  print ('Feeder names and mRIDs:')
+  for b in ret.bindings:
+    print (b['feeder'].value,b['fid'].value)
+
+if __name__ == '__main__':
+  cfg_file = None
+  if len(sys.argv) > 1:
+    cfg_file = sys.argv[1]
+  list_feeders (cfg_file)
+