Add/rename electric quantities (#1444)

Renamed quantities to have prefix "Electric", marking old name as obsolete and adding new duplicate quantities: * `ApparentEnergy` -> `ElectricApparentEnergy` * `ApparentPower` -> `ElectricApparentPower` * `Capacitance` -> `ElectricCapacitance` * `ReactiveEnergy` -> `ElectricReactiveEnergy` * `ReactivePower` -> `ElectricReactivePower ` * `ElectricPotentialAc` * `ElectricPotentialDc` * `ElectricAdmittance` (obsolete due to being a complex number, not supported by UnitsNet, recommending `ElectricReactance` and `ElectricSusceptance` instead) Decided against adding `ElectricImpedance`, also being a complex number. New: - Add `ElectricReactance` - Add `ElectricSusceptance` - Add `EletricCurrent = ElectricApparentPower / ElectricPotential` - Add `ElectricPotential = ElectricApparentPower / ElectricCurrent` - `ElectricAdmittance`: - Add prefixes: Kilo, Mega, Giga, Tera - Add Mho unit, equivalent to Siemen - `ElectricConductance`: - Add prefixes: Mega, Giga, Tera - Add Mho unit, equivalent to Siemen - `EletricResistance`: - Add prefixes: Nano --------- Co-authored-by: Andreas Gullberg Larsen <andreas.larsen84@gmail.com>
angularsen · Dec 28, 2024 · 6b05cc8 · 6b05cc8
1 parent 52aba98
commit 6b05cc8
Show file tree

Hide file tree

Showing 177 changed files with 22,344 additions and 101 deletions.
diff --git a/CodeGen/Generators/UnitsNetGen/NumberExtensionsGenerator.cs b/CodeGen/Generators/UnitsNetGen/NumberExtensionsGenerator.cs
@@ -3,19 +3,11 @@
 
 namespace CodeGen.Generators.UnitsNetGen
 {
-    internal class NumberExtensionsGenerator : GeneratorBase
+    internal class NumberExtensionsGenerator(Quantity quantity) : GeneratorBase
     {
-        private readonly Unit[] _units;
-        private readonly string _quantityName;
-
-        public NumberExtensionsGenerator(Quantity quantity)
-        {
-            if (quantity is null)
-                throw new ArgumentNullException(nameof(quantity));
-
-            _units = quantity.Units;
-            _quantityName = quantity.Name;
-        }
+        private readonly Quantity _quantity = quantity ?? throw new ArgumentNullException(nameof(quantity));
+        private readonly Unit[] _units = quantity.Units;
+        private readonly string _quantityName = quantity.Name;
 
         public string Generate()
         {
@@ -35,7 +27,10 @@ namespace UnitsNet.NumberExtensions.NumberTo{_quantityName}
 {{
     /// <summary>
     /// A number to {_quantityName} Extensions
-    /// </summary>
+    /// </summary>");
+
+                              Writer.WLIfText(1, GetObsoleteAttributeOrNull(_quantity));
+                              Writer.WL(@$"
     public static class NumberTo{_quantityName}Extensions
     {{");
 
@@ -47,7 +42,8 @@ public static class NumberTo{_quantityName}Extensions
                 Writer.WL(2, $@"
 /// <inheritdoc cref=""{_quantityName}.From{unit.PluralName}(UnitsNet.QuantityValue)"" />");
 
-                Writer.WLIfText(2, GetObsoleteAttributeOrNull(unit.ObsoleteText));
+                // Include obsolete text from the quantity per extension method, to make it visible when the class is not explicitly referenced in code.
+                Writer.WLIfText(2, GetObsoleteAttributeOrNull(unit.ObsoleteText ?? _quantity.ObsoleteText));
 
                 Writer.WL(2, $@"public static {_quantityName} {unit.PluralName}<T>(this T value)
             where T : notnull
@@ -63,6 +59,9 @@ public static class NumberTo{_quantityName}Extensions
             return Writer.ToString();
         }
 
+        /// <inheritdoc cref="GetObsoleteAttributeOrNull(string)"/>
+        private static string? GetObsoleteAttributeOrNull(Quantity quantity) => GetObsoleteAttributeOrNull(quantity.ObsoleteText);
+
         private static string? GetObsoleteAttributeOrNull(string? obsoleteText) =>
             string.IsNullOrWhiteSpace(obsoleteText) ?
             null :

diff --git a/Common/UnitDefinitions/ApparentEnergy.json b/Common/UnitDefinitions/ApparentEnergy.json
@@ -2,6 +2,8 @@
   "Name": "ApparentEnergy",
   "BaseUnit": "VoltampereHour",
   "XmlDocSummary": "A unit for expressing the integral of apparent power over time, equal to the product of 1 volt-ampere and 1 hour, or to 3600 joules.",
+  "XmlDocRemarks": "<see cref=\"ApparentEnergy\" /> has been renamed to <see cref=\"ElectricApparentEnergy\" />, and will be removed in a later major version.",
+  "ObsoleteText": "ApparentEnergy has been renamed to ElectricApparentEnergy, and will be removed in a later major version.",
   "BaseDimensions": {
     "L": 2,
     "M": 1,

diff --git a/Common/UnitDefinitions/ApparentPower.json b/Common/UnitDefinitions/ApparentPower.json
@@ -2,6 +2,8 @@
   "Name": "ApparentPower",
   "BaseUnit": "Voltampere",
   "XmlDocSummary": "Power engineers measure apparent power as the magnitude of the vector sum of active and reactive power. Apparent power is the product of the root-mean-square of voltage and current.",
+  "XmlDocRemarks": "<see cref=\"ApparentPower\" /> has been renamed to <see cref=\"ElectricApparentPower\" />, and will be removed in a later major version.",
+  "ObsoleteText": "ApparentPower has been renamed to ElectricApparentPower, and will be removed in a later major version.",
   "BaseDimensions": {
     "L": 2,
     "M": 1,

diff --git a/Common/UnitDefinitions/Capacitance.json b/Common/UnitDefinitions/Capacitance.json
@@ -2,7 +2,8 @@
   "Name": "Capacitance",
   "BaseUnit": "Farad",
   "XmlDocSummary": "Capacitance is the ability of a body to store an electric charge.",
-  "XmlDocRemarks": "https://en.wikipedia.org/wiki/Capacitance",
+  "XmlDocRemarks": "<see cref=\"Capacitance\" /> has been renamed to <see cref=\"ElectricCapacitance\" />, and will be removed in a later major version.",
+  "ObsoleteText": "Capacitance has been renamed to ElectricCapacitance, and will be removed in a later major version.",
   "BaseDimensions": {
     "L": -2,
     "M": -1,

diff --git a/Common/UnitDefinitions/ElectricAdmittance.json b/Common/UnitDefinitions/ElectricAdmittance.json
@@ -1,7 +1,9 @@
 {
   "Name": "ElectricAdmittance",
   "BaseUnit": "Siemens",
-  "XmlDocSummary": "Electric admittance is a measure of how easily a circuit or device will allow a current to flow. It is defined as the inverse of impedance. The SI unit of admittance is the siemens (symbol S).",
+  "XmlDocSummary": "Electric admittance is a measure of how easily a circuit or device will allow a current to flow by the combined effect of conductance and susceptance in a circuit. It is defined as the inverse of impedance. The SI unit of admittance is the siemens (symbol S).",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/Electrical_admittance",
+  "ObsoleteText": "Admittance is a complex number, which is not currently supported by UnitsNet. Please use either ElectricConductance or ElectricSusceptance instead.",
   "BaseDimensions": {
     "L": -2,
     "M": -1,
@@ -14,13 +16,26 @@
       "PluralName": "Siemens",
       "FromUnitToBaseFunc": "{x}",
       "FromBaseToUnitFunc": "{x}",
-      "Prefixes": [ "Nano", "Micro", "Milli" ],
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
       "Localization": [
         {
           "Culture": "en-US",
           "Abbreviations": [ "S" ]
         }
       ]
+    },
+    {
+      "SingularName": "Mho",
+      "PluralName": "Mhos",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "℧" ]
+        }
+      ]
     }
   ]
 }
diff --git a/Common/UnitDefinitions/ElectricApparentEnergy.json b/Common/UnitDefinitions/ElectricApparentEnergy.json
@@ -0,0 +1,25 @@
+{
+  "Name": "ElectricApparentEnergy",
+  "BaseUnit": "VoltampereHour",
+  "XmlDocSummary": "A unit for expressing the integral of apparent power over time, equal to the product of 1 volt-ampere and 1 hour, or to 3600 joules.",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -2
+  },
+  "Units": [
+    {
+      "SingularName": "VoltampereHour",
+      "PluralName": "VoltampereHours",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Kilo", "Mega" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "VAh" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricApparentPower.json b/Common/UnitDefinitions/ElectricApparentPower.json
@@ -0,0 +1,26 @@
+{
+  "Name": "ElectricApparentPower",
+  "BaseUnit": "Voltampere",
+  "XmlDocSummary": "Power engineers measure apparent power as the magnitude of the vector sum of active and reactive power. It is the product of the root mean square voltage (in volts) and the root mean square current (in amperes).",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/AC_power#Active,_reactive,_apparent,_and_complex_power_in_sinusoidal_steady-state",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -3
+  },
+  "Units": [
+    {
+      "SingularName": "Voltampere",
+      "PluralName": "Voltamperes",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Micro", "Milli", "Kilo", "Mega", "Giga" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "VA" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricCapacitance.json b/Common/UnitDefinitions/ElectricCapacitance.json
@@ -0,0 +1,33 @@
+{
+  "Name": "ElectricCapacitance",
+  "BaseUnit": "Farad",
+  "XmlDocSummary": "Capacitance is the capacity of a material object or device to store electric charge.",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/Capacitance",
+  "BaseDimensions": {
+    "L": -2,
+    "M": -1,
+    "T": 4,
+    "I": 2
+  },
+  "Units": [
+    {
+      "SingularName": "Farad",
+      "PluralName": "Farads",
+      "BaseUnits": {
+        "L": "Meter",
+        "M": "Kilogram",
+        "T": "Second",
+        "I": "Ampere"
+      },
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Pico", "Nano", "Micro", "Milli", "Kilo", "Mega" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "F" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricConductance.json b/Common/UnitDefinitions/ElectricConductance.json
@@ -1,7 +1,7 @@
 {
   "Name": "ElectricConductance",
   "BaseUnit": "Siemens",
-  "XmlDocSummary": "The electrical conductance of an electrical conductor is a measure of the easeness to pass an electric current through that conductor.",
+  "XmlDocSummary": "The electrical conductance of an object is a measure of the ease with which an electric current passes. Along with susceptance, it is one of two elements of admittance. Its reciprocal quantity is electrical resistance.",
   "XmlDocRemarks": "https://en.wikipedia.org/wiki/Electrical_resistance_and_conductance",
   "BaseDimensions": {
     "L": -2,
@@ -15,13 +15,26 @@
       "PluralName": "Siemens",
       "FromUnitToBaseFunc": "{x}",
       "FromBaseToUnitFunc": "{x}",
-      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo" ],
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
       "Localization": [
         {
           "Culture": "en-US",
           "Abbreviations": [ "S" ]
         }
       ]
+    },
+    {
+      "SingularName": "Mho",
+      "PluralName": "Mhos",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "℧" ]
+        }
+      ]
     }
   ]
 }
diff --git a/Common/UnitDefinitions/ElectricCurrent.json b/Common/UnitDefinitions/ElectricCurrent.json
@@ -2,6 +2,7 @@
   "Name": "ElectricCurrent",
   "BaseUnit": "Ampere",
   "XmlDocSummary": "An electric current is a flow of electric charge. In electric circuits this charge is often carried by moving electrons in a wire. It can also be carried by ions in an electrolyte, or by both ions and electrons such as in a plasma.",
+  "XmlDocRemarks": "If you want to map more parameters into the <see cref=\"ElectricCurrent\" /> class (amps RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
   "BaseDimensions": {
     "I": 1
   },

diff --git a/Common/UnitDefinitions/ElectricImpedance.json b/Common/UnitDefinitions/ElectricImpedance.json
@@ -0,0 +1,28 @@
+{
+  "Name": "ElectricImpedance",
+  "BaseUnit": "Ohm",
+  "XmlDocSummary": "Electric impedance is the opposition to alternating current presented by the combined effect of resistance and reactance in a circuit. It is defined as the inverse of admittance. The SI unit of impedance is the ohm (symbol Ω).",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/Electrical_impedance",
+  "ObsoleteText": "Impedance is a complex number, which is not currently supported by UnitsNet. Please use either ElectricResistance or ElectricReactance instead.",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -3,
+    "I": -2
+  },
+  "Units": [
+    {
+      "SingularName": "Ohm",
+      "PluralName": "Ohms",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "Ω" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricPotential.json b/Common/UnitDefinitions/ElectricPotential.json
@@ -2,6 +2,7 @@
   "Name": "ElectricPotential",
   "BaseUnit": "Volt",
   "XmlDocSummary": "In classical electromagnetism, the electric potential (a scalar quantity denoted by Φ, ΦE or V and also called the electric field potential or the electrostatic potential) at a point is the amount of electric potential energy that a unitary point charge would have when located at that point.",
+  "XmlDocRemarks": "If you want to map more parameters into the <see cref=\"ElectricPotential\" /> class (volts RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
   "BaseDimensions": {
     "L": 2,
     "M": 1,

diff --git a/Common/UnitDefinitions/ElectricPotentialAc.json b/Common/UnitDefinitions/ElectricPotentialAc.json
@@ -2,6 +2,8 @@
   "Name": "ElectricPotentialAc",
   "BaseUnit": "VoltAc",
   "XmlDocSummary": "The Electric Potential of a system known to use Alternating Current.",
+  "XmlDocRemarks": "<see cref=\"ElectricPotentialAc\" /> has been merged into <see cref=\"ElectricPotential\" />, and will be removed in a later major version. If you want to map more parameters into the <see cref=\"ElectricPotential\" /> class (volts RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
+  "ObsoleteText": "ElectricPotentialAc has been merged into ElectricPotential, and will be removed in a later major version. If you want to map more parameters into the ElectricPotential class (volts RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
   "Units": [
     {
       "SingularName": "VoltAc",

diff --git a/Common/UnitDefinitions/ElectricPotentialDc.json b/Common/UnitDefinitions/ElectricPotentialDc.json
@@ -2,6 +2,8 @@
   "Name": "ElectricPotentialDc",
   "BaseUnit": "VoltDc",
   "XmlDocSummary": "The Electric Potential of a system known to use Direct Current.",
+  "XmlDocRemarks": "<see cref=\"ElectricPotentialDc\" /> has been merged into <see cref=\"ElectricPotential\" />, and will be removed in a later major version. If you want to map more parameters into the <see cref=\"ElectricPotential\" /> class (volts RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
+  "ObsoleteText": "ElectricPotentialDc has been merged into ElectricPotential, and will be removed in a later major version. If you want to map more parameters into the ElectricPotential class (volts RMS, phase angle, etc.), create your own wrapper type such as a record or named tuple.",
   "Units": [
     {
       "SingularName": "VoltDc",

diff --git a/Common/UnitDefinitions/ElectricReactance.json b/Common/UnitDefinitions/ElectricReactance.json
@@ -0,0 +1,27 @@
+{
+  "Name": "ElectricReactance",
+  "BaseUnit": "Ohm",
+  "XmlDocSummary": "In electrical circuits, reactance is the opposition presented to alternating current by inductance and capacitance. Along with resistance, it is one of two elements of impedance.",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/Electrical_reactance",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -3,
+    "I": -2
+  },
+  "Units": [
+    {
+      "SingularName": "Ohm",
+      "PluralName": "Ohms",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Nano", "Micro", "Milli", "Kilo", "Mega", "Giga", "Tera" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "Ω" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricReactiveEnergy.json b/Common/UnitDefinitions/ElectricReactiveEnergy.json
@@ -0,0 +1,25 @@
+{
+  "Name": "ElectricReactiveEnergy",
+  "BaseUnit": "VoltampereReactiveHour",
+  "XmlDocSummary": "The volt-ampere reactive hour (expressed as varh) is the reactive power of one Volt-ampere reactive produced in one hour.",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -2
+  },
+  "Units": [
+    {
+      "SingularName": "VoltampereReactiveHour",
+      "PluralName": "VoltampereReactiveHours",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Kilo", "Mega" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "varh" ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/Common/UnitDefinitions/ElectricReactivePower.json b/Common/UnitDefinitions/ElectricReactivePower.json
@@ -0,0 +1,26 @@
+{
+  "Name": "ElectricReactivePower",
+  "BaseUnit": "VoltampereReactive",
+  "XmlDocSummary": "In electric power transmission and distribution, volt-ampere reactive (var) is a unit of measurement of reactive power. Reactive power exists in an AC circuit when the current and voltage are not in phase.",
+  "XmlDocRemarks": "https://en.wikipedia.org/wiki/AC_power#Active,_reactive,_apparent,_and_complex_power_in_sinusoidal_steady-state",
+  "BaseDimensions": {
+    "L": 2,
+    "M": 1,
+    "T": -3
+  },
+  "Units": [
+    {
+      "SingularName": "VoltampereReactive",
+      "PluralName": "VoltamperesReactive",
+      "FromUnitToBaseFunc": "{x}",
+      "FromBaseToUnitFunc": "{x}",
+      "Prefixes": [ "Kilo", "Mega", "Giga" ],
+      "Localization": [
+        {
+          "Culture": "en-US",
+          "Abbreviations": [ "var" ]
+        }
+      ]
+    }
+  ]
+}