Enhance data model by cable type information

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased/Snapshot]
 
 ### Added
-
+- Enhance data model by cable type information [#1665](https://github.com/ie3-institute/PowerSystemDataModel/issues/1665)
 
 ### Fixed
 - Fixed issues regarding determination of additional parameters [#1661](https://github.com/ie3-institute/PowerSystemDataModel/issues/1661)

build.gradle

@@ -54,7 +54,7 @@ repositories {
 dependencies {
 
   //	 ie³ power system utils
-  implementation 'com.github.ie3-institute:PowerSystemUtils:3.2.1'
+  implementation 'com.github.ie3-institute:PowerSystemUtils:3.2.2'
 
   implementation 'tech.units:indriya:2.2.4'
 
@@ -65,6 +65,10 @@ dependencies {
 
   implementation 'org.locationtech.jts.io:jts-io-common:1.20.0'
 
+  // parsing json
+  implementation 'com.fasterxml.jackson.core:jackson-databind:2.22.0'
+  implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.15.2'
+
   // Graphs
   implementation 'org.jgrapht:jgrapht-core:1.5.3'
 

docs/readthedocs/_static/bibliography/bibtex.bib

@@ -0,0 +1,59 @@
+ @book{luecking_1981, address={Wiesbaden}, edition={1st ed. 1981}, title={Energiekabeltechnik}, ISBN={9783322843128}, DOI={10.1007/978-3-322-84312-8}, publisher={Imprint: Vieweg+Teubner Verlag}, author={Lücking, H. Wilhelm}, year={1981} }
+@misc{wiki:thermal_conductivity_resistivity,
+  author       = {{Wikipedia contributors}},
+  title        = {Thermal conductivity and resistivity --- {Wikipedia}{,} The Free Encyclopedia},
+  year         = {2026},
+  url          = {https://en.wikipedia.org/wiki/Thermal_conductivity_and_resistivity},
+  note         = {[Online; accessed 3 June 2026]}
+}
+@misc{wiki:Copper,
+  author       = {{Wikipedia contributors}},
+  title        = {Copper --- {Wikipedia}{,} The Free Encyclopedia},
+  year         = {2026},
+  url          = {https://en.wikipedia.org/wiki/Copper},
+  note         = {[Online; accessed 3 June 2026]}
+}
+@misc{wiki:Aluminium,
+  author       = {{Wikipedia contributors}},
+  title        = {Aluminium --- {Wikipedia}{,} The Free Encyclopedia},
+  year         = {2026},
+  url          = {https://en.wikipedia.org/wiki/Aluminium},
+  note         = {[Online; accessed 3 June 2026]}
+}
+@misc{wiki:specific_heat_capacities,
+  author       = {{Wikipedia contributors}},
+  title        = {Table of specific heat capacities --- {Wikipedia}{,} The Free Encyclopedia},
+  year         = {2026},
+  url          = {https://en.wikipedia.org/wiki/Table_of_specific_heat_capacities},
+  note         = {[Online; accessed 3 June 2026]}
+}
+@misc{wiki:thermal_conductivities,
+  author       = {{Wikipedia contributors}},
+  title        = {List of thermal conductivities --- {Wikipedia}{,} The Free Encyclopedia},
+  year         = {2026},
+  url          = {https://en.wikipedia.org/wiki/List_of_thermal_conductivities},
+  note         = {[Online; accessed 3 June 2026]}
+}
+
+@book{andersRatingElectricPower1997,
+  title = {Rating of Electric Power Cables: Ampacity Computations for Transmission, Distribution, and Industrial Applications},
+  shorttitle = {Rating of Electric Power Cables},
+  author = {Anders, George J.},
+  year = 1997,
+  series = {{{IEEE Press}} Power Engineering Series},
+  publisher = {McGraw-Hill [u.a.]},
+  address = {New York, NY},
+  isbn = {978-0-07-001791-7 978-0-7803-1177-0},
+  langid = {english},
+  file = {C:\Users\smdafeis\Zotero\storage\9DR3K43F\Anders - 1997 - Rating of electric power cables ampacity computations for transmission, distribution, and industria.pdf}
+}
+@techreport{CIGRE_TB880_2022,
+  author       = {{CIGR\'{E} Working Group B1.56}},
+  title        = {Power cable rating examples for calculation tool verification},
+  institution  = {{Conseil International des Grands R\'{e}seaux \'{E}lectriques (CIGR\'{E})}},
+  type         = {Technical Brochure},
+  number       = {880},
+  address      = {Paris, France},
+  year         = {2022},
+  isbn         = {978-2-85873-585-3}
+}

docs/readthedocs/conf.py

@@ -36,9 +36,13 @@
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
-    'myst_parser'
+    'myst_parser',
+    'sphinxcontrib.bibtex'
 ]
 
+bibtex_bibfiles = ["_static/bibliography/bibtex.bib"]
+bibtex_default_style = 'plain'
+
 myst_enable_extensions = ["dollarmath", "amsmath"]
 myst_heading_anchors = 4
 

docs/readthedocs/index.md

@@ -12,6 +12,7 @@ Effective handling of geographic information related to power grids is also poss
 gettingstarted
 models/models
 io/basiciousage
+references
 ```
 
 ## Contact the (Main) Maintainers

docs/readthedocs/models/input/grid/cableMaterial.md

@@ -0,0 +1,126 @@
+(cable-material)=
+# Cable Material
+
+## Overview
+
+The `CableMaterial` enum represents various materials used in electrical cable construction, providing their default thermal and electrical properties. This is primarily used for physical modeling and simulation of distribution grids, allowing for accurate calculations of thermal states, ampacity, and electrical losses.
+
+## Properties
+
+### Thermal Properties
+
+Retrieved via `getThermalProperties()`. Returns a `ThermalProperties` container providing **Thermal Resistivity** ($K \cdot m/W$) and **Thermal Capacitance** ($J / (m^3 \cdot K)$).
+
+```{list-table}
+   :widths: auto
+   :class: wrapping
+   :header-rows: 1
+
+  * - Material
+    - Thermal Resistivity []
+    - Thermal Capacitance [1/K]
+    - source 
+    - Notes
+
+  * - `Copper`
+    - 1/384 
+    - 3,449,600.0
+    - {cite:cts}`wiki:thermal_conductivity_resistivity`, {cite:cts}`wiki:Copper` 
+    - c = 385 J/(kg * K), rho= 8.96 g/cm³ => 3449600 J / (m³ * K)
+
+  * - `Aluminium`
+    - 1/237
+    - 2,420,913.3 
+    - {cite:cts}`wiki:thermal_conductivity_resistivity`, {cite:cts}`wiki:Aluminium` 
+    - c = 897 J/(kg * K), rho= 2.6989 g/cm³ => 2420913.3 J / (m³ * K)
+
+  * - `XLPE (Cross-linked polyethylene)`
+    - 3.5
+    - 2.4
+    - {cite:cts}`andersRatingElectricPower1997` p. 400
+    - -
+
+  * - `PE (Polyethylene)`
+    - 3.5
+    - 2.4
+    - {cite:cts}`andersRatingElectricPower1997` p. 400
+    - - 
+
+  * - `PVC (Polyvinyl chloride)`
+    - 3.5
+    - 1.7
+    - {cite:cts}`andersRatingElectricPower1997` p. 400
+    - -
+
+  * - `Semi-Conductive Screen`
+    - 2.5
+    - 2.4
+    - Th. Res.: {cite:cts}`CIGRE_TB880_2022` p. 28; Th. Capa.: Same as adjacent dielectric material see {cite:cts}`andersRatingElectricPower1997` p. 400
+    - -
+
+  * - `SC-Tape (Screen Tape)`
+    - 6.0
+    - 2.4
+    - Th. Res.: {cite:cts}`CIGRE_TB880_2022` p. 28; Th. Capa.: Same as adjacent dielectric material see {cite:cts}`andersRatingElectricPower1997` p. 400
+    - -
+
+  * - `Lead`
+    - 1/35
+    - 1,463,892.0
+    - Th. Res.: {cite:cts}`wiki:thermal_conductivities`; Th. Capa.: {cite:cts}`wiki:specific_heat_capacities` 
+    - c = 129 J/(kg * K), rho= 11.348 g/cm³ => 1,463,892.0 J / (m³ * K)
+
+  * - `Steel`
+    - 1/45
+    - 3,756,000.0
+    - Th. Res.:{cite:cts}`wiki:thermal_conductivity_resistivity`; Th. Capa.: {cite:cts}`wiki:specific_heat_capacities`
+    - - 
+
+  * - `Polypropylen`
+    - 6.0
+    - 2.0
+    - Th. Res.: {cite:cts}`CIGRE_TB880_2022` p. 28; Th. Capa.: Asumed to be clos to Paper-polypropylene-paper (PPL) in {cite:cts}`andersRatingElectricPower1997` p. 400
+    - - 
+```
+
+**Note:** Metals inherently define their thermal resistivity as the inverse of their thermal conductivity $\lambda$ (e.g., $\lambda_{Copper} = 384 \, W/(m \cdot K)$).
+
+### Electrical Properties
+
+Electrical parameters define the conductive aspects of the materials, heavily utilized for power flow and loss calculations.
+
+* **Electrical Resistivity:** Retrieved via `getElectricalResistivity()` (at standard reference temperature).
+* **Temperature Coefficient:** Retrieved via `getElectricalResistivityTemperatureCoefficient()`.
+
+```{list-table}
+   :widths: auto
+   :class: wrapping
+   :header-rows: 1
+
+  * - Material
+    - Electrical Resistivity []
+    - Temp. Coefficient [1/K]
+    - source
+
+  * - `Copper`
+    - $1.7241 \times 10^{-8}$
+    - $3.93 \times 10^{-3}$
+    - {cite:cts}`luecking_1981` p. 94
+
+  * - `Aluminium`
+    - $2.8264 \times 10^{-8}$
+    - $4.03 \times 10^[-3}$
+    - {cite:cts}`luecking_1981` p. 94
+
+  * - `Lead`
+    - $21.4 \times 10^{-8}$
+    - $4.0 \times 10^[-3}$
+    - {cite:cts}`luecking_1981` p. 94
+
+  * - `Steel`
+    - $13.8 \times 10^{-8}$
+    - $4.5 \times 10^[-3}$
+    - {cite:cts}`luecking_1981` p. 94
+```
+
+Calling these methods on non-conductive insulation materials will throw an `IllegalArgumentException`.