cim-profiles 0.1.0a1__tar.gz

cim_profiles-0.1.0a1/.gitignore

@@ -0,0 +1,70 @@
+.vscode/*
+.metadata/*
+# Compiled class file
+*.class
+*.puml
+*/Profiles/*.py
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+replay_pid*
+
+# Python bytecode and extensions
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Python packaging and build output
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+sdist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.python-version
+
+# Test, coverage and type-checker caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+.hypothesis/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Documentation site build (mkdocs)
+site/
+
+# Local environment files
+.env

cim_profiles-0.1.0a1/CIMTool_plugin/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Battelle Memorial Institute; All rights reserved.
+
+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.

cim_profiles-0.1.0a1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Battelle Memorial Institute; All rights reserved.
+
+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.

cim_profiles-0.1.0a1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: cim-profiles
+Version: 0.1.0a1
+Summary: CIM data profiles (Python dataclasses) and the Identity/units object model used by CIMantic Graphs
+Project-URL: Homepage, https://github.com/PNNL-CIM-Tools/CIM-Profiles
+Project-URL: Repository, https://github.com/PNNL-CIM-Tools/CIM-Profiles
+Project-URL: Issues, https://github.com/PNNL-CIM-Tools/CIM-Profiles/issues
+Author-email: "A. Anderson" <19935503+AAndersn@users.noreply.github.com>, "C. Allwardt" <3979063+craig8@users.noreply.github.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: cgmes,cim,iec-61968,iec-61970,power-systems
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <4.0,>=3.10
+Requires-Dist: pint>=0.24.4
+Description-Content-Type: text/markdown
+
+# CIM-Profiles
+
+![GitHub Tag](https://img.shields.io/github/v/tag/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Release Date](https://img.shields.io/github/release-date-pre/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/PNNL-CIM-Tools/CIM-Profiles/release.yml)
+![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/PNNL-CIM-Tools/CIM-Profiles)
+
+
+![PyPI - Version](https://img.shields.io/pypi/v/cim-profiles)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/cim-profiles?label=pypi%20downloads)
+![PyPI - Format](https://img.shields.io/pypi/format/cim-profiles)
+
+
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/t/PNNL-CIM-Tools/CIM-Profiles)
+
+![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/PNNL-CIM-Tools/CIM-Profiles/total?label=git%20downloads)
+![GitHub License](https://img.shields.io/github/license/PNNL-CIM-Tools/CIM-Profiles)
+
+CIMTool workspaces for the CIM 16–18 profiles, and the `cimprofiles` Python package built from
+them. These files originally shipped as part of cim-graph 0.1.x through 0.5.x.
+
+`cimprofiles` ships the CIM profiles as Python dataclasses, together with the object model they
+are built on (`Identity`, `CIMUnit`, profile merging). It depends only on `pint`, and it is
+released separately from [cim-graph](https://github.com/PNNL-CIM-Tools/CIM-Graph). Profile updates
+(new classes from EA tickets, new profiles) therefore don't wait for a cim-graph release.
+
+```bash
+pip install cimprofiles
+```
+
+```python
+import cimprofiles.cim18.cimhub_2026 as cim
+
+line = cim.ACLineSegment(name='line_1')
+```
+
+cim-graph 0.6 and later depend on `cimprofiles`. The old `cimgraph.data_profile.*` import paths
+still work there, with a `DeprecationWarning`.
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `cim17v40/`, `cim18v15/` | CIMTool workspaces. The Sparx EA `.eap` models are stored with Git LFS. |
+| `CIMTool_plugin/` | The cimantic-graphs XSLT builders and their documentation |
+| `src/cimprofiles/` | The Python package, with profiles grouped by CIM version (`cim16/`, `cim17/`, `cim18/`). See [`src/cimprofiles/README.md`](src/cimprofiles/README.md) for the available profiles and how merging works. |
+| `scripts/import_cimtool_output.sh` | Copies a profile generated by CIMTool into `src/cimprofiles/` and rewrites its imports |
+| `tests/` | Tests for `Identity`, UUIDs, merging and the generated profiles |
+
+## Seeded UUIDs
+
+Deterministic identifiers are what downstream converters (ArcGIS, OpenDSS, ...) rely on to give
+the same equipment the same RDF ID on every run. `Identity.identifier` is a UUID (CIM 18):
+either the one given, or a deterministic construct. There are two cases.
+
+**Read from a file:** the `rdf:ID`/`rdf:about` *is* the UUID, in any serialization
+(`urn:uuid:…`, `#_…`, `_…`, any case). The name is not used. An identifier that is not a UUID is
+replaced, with a warning, by the UUID seeded from it (below), so reading the same file again
+gives the same UUIDs. The original string is kept as the mRID, unless the file has an mRID.
+Readers key their graphs with `cimprofiles.identity.read_identifier`, which gives the same UUID.
+
+**Built** (converters, notebooks, `.cimtbl`): a new object, deterministic only for the same model
+authority, model and class, plus one of two keys. A UUID given as the mRID is used directly.
+
+- **mRID route** - with a (non-UUID) mRID, the mRID is the key and the name is not used, so a
+  renamed object keeps its UUID. CIM 18 relaxes the mRID to a freeform string unique within the
+  model, so this is the route for models keyed by mRID.
+- **Name route** - with no mRID, the name is the key, so a renamed object (bus 300 to bus 301) is
+  a different object and gets a different UUID.
+
+The seeded UUID is version 5 (RFC 9562 §5.5):
+
+```python
+namespace = uuid5(NAMESPACE_URL, model_authority)
+uuid = uuid5(namespace, f'{model_name}+{ClassName}+{mRID}+{name}+{seed}')
+```
+
+- `model_authority` is a URI (`CIMG_MODEL_AUTHORITY`, default
+  `https://github.com/PNNL-CIM-Tools/CIM-Graph`), as in `md:Model.modelingAuthoritySet`. The
+  namespace is also the identifier of the `cim:ModelAuthority` object cim-graph writes in file
+  headers, so each authority's UUIDs live in its own namespace.
+- `model_name` comes from `CIMG_MODEL_NAME` (default empty).
+- `mRID` is the object's mRID, or the non-UUID `rdf:ID`/`rdf:about` of an object read from a
+  file. It is normalized so every serialization of one object agrees: surrounding whitespace, a
+  `urn:uuid:` prefix, everything up to the last `#` and one leading `_` are removed.
+  `rdf:ID="_LINE1"`, `rdf:about="#_LINE1"` and `mRID="LINE1"` give the same UUID. Case is kept.
+- `name` (whitespace-trimmed) is used only when there is no mRID, so one of the two is always
+  empty. `seed` (passed to `obj.uuid(seed=...)`) is optional.
+- Every component keeps its position even when empty, and `%` and `+` inside a component are
+  escaped as `%25` and `%2B`, so two different inputs never produce the same string.
+- No identifying input at all (or only empty/blank values) gives a random version 4 UUID.
+
+`obj.uri()` returns the bare UUID: lowercase, or uppercase if it was read uppercase (CIMHub and
+GridAPPS-D data), so writing a file back reproduces its identifiers. Underscores and
+`urn:uuid:` prefixes belong to the serialization style and are added by cim-graph's writers
+and queries (`CIMG_IEC61970_552`: `552-NEW`, `552-LEGACY` or `CGMES`).
+
+`cimprofiles.identity.seeded_uuid` and `model_authority_namespace` implement the seeded UUID, and any
+language with a UUID library can reproduce it from this description.
+
+## Updating a profile
+
+1. Regenerate it in CIMTool with the cimantic-graphs builders (`CIMTool_plugin/builder.md`).
+2. Import it. This rewrites the `cimgraph.data_profile` imports emitted by CIMTool before 2.3.1:
+   ```bash
+   scripts/import_cimtool_output.sh cim17 <Profiles/name.py> <Profiles/name.__init__.py>
+   ```
+   The first argument is the CIM version directory. A fourth argument names the package
+   directory when it differs from the envelope name (`gridappsd_rc4_2021` for `rc4_2021`),
+   or places a part of a merged profile (`cim18v17/substation`).
+3. Remove duplicate field definitions, and rebuild the pre-baked merged profiles (cim18gmdm,
+   cgmes_3_0_0, cim18v17) if it is one of their parts:
+   ```bash
+   uv run python -m cimprofiles.dedupe_profile_fields
+   uv run python -m cimprofiles.build_merged_profiles
+   ```
+4. Run the tests: `uv run pytest`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

cim_profiles-0.1.0a1/README.md

@@ -0,0 +1,130 @@
+# CIM-Profiles
+
+![GitHub Tag](https://img.shields.io/github/v/tag/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Release Date](https://img.shields.io/github/release-date-pre/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/PNNL-CIM-Tools/CIM-Profiles/release.yml)
+![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/PNNL-CIM-Tools/CIM-Profiles)
+
+
+![PyPI - Version](https://img.shields.io/pypi/v/cim-profiles)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/cim-profiles?label=pypi%20downloads)
+![PyPI - Format](https://img.shields.io/pypi/format/cim-profiles)
+
+
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr/PNNL-CIM-Tools/CIM-Profiles)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/t/PNNL-CIM-Tools/CIM-Profiles)
+
+![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/PNNL-CIM-Tools/CIM-Profiles/total?label=git%20downloads)
+![GitHub License](https://img.shields.io/github/license/PNNL-CIM-Tools/CIM-Profiles)
+
+CIMTool workspaces for the CIM 16–18 profiles, and the `cimprofiles` Python package built from
+them. These files originally shipped as part of cim-graph 0.1.x through 0.5.x.
+
+`cimprofiles` ships the CIM profiles as Python dataclasses, together with the object model they
+are built on (`Identity`, `CIMUnit`, profile merging). It depends only on `pint`, and it is
+released separately from [cim-graph](https://github.com/PNNL-CIM-Tools/CIM-Graph). Profile updates
+(new classes from EA tickets, new profiles) therefore don't wait for a cim-graph release.
+
+```bash
+pip install cimprofiles
+```
+
+```python
+import cimprofiles.cim18.cimhub_2026 as cim
+
+line = cim.ACLineSegment(name='line_1')
+```
+
+cim-graph 0.6 and later depend on `cimprofiles`. The old `cimgraph.data_profile.*` import paths
+still work there, with a `DeprecationWarning`.
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `cim17v40/`, `cim18v15/` | CIMTool workspaces. The Sparx EA `.eap` models are stored with Git LFS. |
+| `CIMTool_plugin/` | The cimantic-graphs XSLT builders and their documentation |
+| `src/cimprofiles/` | The Python package, with profiles grouped by CIM version (`cim16/`, `cim17/`, `cim18/`). See [`src/cimprofiles/README.md`](src/cimprofiles/README.md) for the available profiles and how merging works. |
+| `scripts/import_cimtool_output.sh` | Copies a profile generated by CIMTool into `src/cimprofiles/` and rewrites its imports |
+| `tests/` | Tests for `Identity`, UUIDs, merging and the generated profiles |
+
+## Seeded UUIDs
+
+Deterministic identifiers are what downstream converters (ArcGIS, OpenDSS, ...) rely on to give
+the same equipment the same RDF ID on every run. `Identity.identifier` is a UUID (CIM 18):
+either the one given, or a deterministic construct. There are two cases.
+
+**Read from a file:** the `rdf:ID`/`rdf:about` *is* the UUID, in any serialization
+(`urn:uuid:…`, `#_…`, `_…`, any case). The name is not used. An identifier that is not a UUID is
+replaced, with a warning, by the UUID seeded from it (below), so reading the same file again
+gives the same UUIDs. The original string is kept as the mRID, unless the file has an mRID.
+Readers key their graphs with `cimprofiles.identity.read_identifier`, which gives the same UUID.
+
+**Built** (converters, notebooks, `.cimtbl`): a new object, deterministic only for the same model
+authority, model and class, plus one of two keys. A UUID given as the mRID is used directly.
+
+- **mRID route** - with a (non-UUID) mRID, the mRID is the key and the name is not used, so a
+  renamed object keeps its UUID. CIM 18 relaxes the mRID to a freeform string unique within the
+  model, so this is the route for models keyed by mRID.
+- **Name route** - with no mRID, the name is the key, so a renamed object (bus 300 to bus 301) is
+  a different object and gets a different UUID.
+
+The seeded UUID is version 5 (RFC 9562 §5.5):
+
+```python
+namespace = uuid5(NAMESPACE_URL, model_authority)
+uuid = uuid5(namespace, f'{model_name}+{ClassName}+{mRID}+{name}+{seed}')
+```
+
+- `model_authority` is a URI (`CIMG_MODEL_AUTHORITY`, default
+  `https://github.com/PNNL-CIM-Tools/CIM-Graph`), as in `md:Model.modelingAuthoritySet`. The
+  namespace is also the identifier of the `cim:ModelAuthority` object cim-graph writes in file
+  headers, so each authority's UUIDs live in its own namespace.
+- `model_name` comes from `CIMG_MODEL_NAME` (default empty).
+- `mRID` is the object's mRID, or the non-UUID `rdf:ID`/`rdf:about` of an object read from a
+  file. It is normalized so every serialization of one object agrees: surrounding whitespace, a
+  `urn:uuid:` prefix, everything up to the last `#` and one leading `_` are removed.
+  `rdf:ID="_LINE1"`, `rdf:about="#_LINE1"` and `mRID="LINE1"` give the same UUID. Case is kept.
+- `name` (whitespace-trimmed) is used only when there is no mRID, so one of the two is always
+  empty. `seed` (passed to `obj.uuid(seed=...)`) is optional.
+- Every component keeps its position even when empty, and `%` and `+` inside a component are
+  escaped as `%25` and `%2B`, so two different inputs never produce the same string.
+- No identifying input at all (or only empty/blank values) gives a random version 4 UUID.
+
+`obj.uri()` returns the bare UUID: lowercase, or uppercase if it was read uppercase (CIMHub and
+GridAPPS-D data), so writing a file back reproduces its identifiers. Underscores and
+`urn:uuid:` prefixes belong to the serialization style and are added by cim-graph's writers
+and queries (`CIMG_IEC61970_552`: `552-NEW`, `552-LEGACY` or `CGMES`).
+
+`cimprofiles.identity.seeded_uuid` and `model_authority_namespace` implement the seeded UUID, and any
+language with a UUID library can reproduce it from this description.
+
+## Updating a profile
+
+1. Regenerate it in CIMTool with the cimantic-graphs builders (`CIMTool_plugin/builder.md`).
+2. Import it. This rewrites the `cimgraph.data_profile` imports emitted by CIMTool before 2.3.1:
+   ```bash
+   scripts/import_cimtool_output.sh cim17 <Profiles/name.py> <Profiles/name.__init__.py>
+   ```
+   The first argument is the CIM version directory. A fourth argument names the package
+   directory when it differs from the envelope name (`gridappsd_rc4_2021` for `rc4_2021`),
+   or places a part of a merged profile (`cim18v17/substation`).
+3. Remove duplicate field definitions, and rebuild the pre-baked merged profiles (cim18gmdm,
+   cgmes_3_0_0, cim18v17) if it is one of their parts:
+   ```bash
+   uv run python -m cimprofiles.dedupe_profile_fields
+   uv run python -m cimprofiles.build_merged_profiles
+   ```
+4. Run the tests: `uv run pytest`.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

cim_profiles-0.1.0a1/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "cim-profiles"
+version = "0.1.0a1"
+description = "CIM data profiles (Python dataclasses) and the Identity/units object model used by CIMantic Graphs"
+authors = [
+    {name = "A. Anderson", email = "19935503+AAndersn@users.noreply.github.com"},
+    {name = "C. Allwardt", email = "3979063+craig8@users.noreply.github.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = ["cim", "power-systems", "iec-61970", "iec-61968", "cgmes"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "pint>=0.24.4",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    # build_merged_profiles reads merge_releases.yaml
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/PNNL-CIM-Tools/CIM-Profiles"
+Repository = "https://github.com/PNNL-CIM-Tools/CIM-Profiles"
+Issues = "https://github.com/PNNL-CIM-Tools/CIM-Profiles/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cimprofiles"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/cimprofiles",
+    "/tests",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]