Support unit prefixes

Author: jbussemaker

README.md

@@ -11,6 +11,7 @@ Convert units and quantities between standard [SysML v2](https://www.omg.org/sys
 - Get/set unit as `attribute` value, specified using Pint `Unit` objects
 - Supports numerical values, as well as `inf` (`*` in SysML v2) and `NaN` (set as `null` in SysML v2)
 - Supports compound units, for example `K·kg·s²/m³`
+- Supports unit prefixes (kilo, mega, milli, etc.)
 - Conversion functions between SysML v2 units and Pint `Unit`, and string parsing functions
 - Derive preferred units for a quantity type, for example `kg` for an `ISQ::mass` quantity
 - Syside Automator [`ReferencePrinter`](https://docs.sensmetry.com/python/latest/syside/ReferencePrinter.html) for

documentation.ipynb

@@ -95,6 +95,7 @@
     "# Read SysML v2 textual notation using Syside Automator\n",
     "model, doc, elements = read_sysml(\"\"\"\n",
     "private import SI::*;\n",
+    "private import SIPrefixes::*;\n",
     "package ThePackage {\n",
     "    part def PartWithAttributes {\n",
     "    \n",
@@ -110,11 +111,12 @@
     "        attribute speed = 300 [m/s];\n",
     "        attribute pressure = 101325 [N/m^2]; // Normally you would use [Pa]\n",
     "        \n",
-    "        // Compound unit defined in standard lib\n",
+    "        // Compound units defined in standard lib\n",
     "        attribute acceleration = 10.0 ['m⋅s⁻²'];\n",
     "\n",
-    "        // Compound unit not defined in the standard lib\n",
+    "        // Compound units not defined in the standard lib\n",
     "        attribute crazyUnits = -3.14 [K*kg*s**2/m^3];\n",
+    "        attribute filesize = 42 [mega*byte]; // Megabyte itself is not defined as a unit\n",
     "        \n",
     "        // Temperature\n",
     "        attribute absTemp = 15.0 ['°C_abs']; // = 288.15 K\n",
@@ -131,9 +133,9 @@
     "units_helper = SysMLUnitsHelper(model)\n",
     "\n",
     "# Get the attributes of the part\n",
-    "part = elements[1].children.elements[0]\n",
+    "part = elements[2].children.elements[0]\n",
     "assert part.name == 'PartWithAttributes'\n",
-    "attrs = list(part.children.elements)"
+    "attrs = {el.name: el for el in part.children.elements}"
    ]
   },
   {
@@ -149,12 +151,12 @@
    "outputs": [],
    "source": [
     "# Read attribute value quantity\n",
-    "q = units_helper.get_quantity(attrs[0])\n",
+    "q = units_helper.get_quantity(attrs['length'])\n",
     "assert q.magnitude == 1000\n",
     "assert str(q.units) == 'meter'\n",
     "\n",
     "# Only read the unit\n",
-    "units, m_unit_attr = units_helper.get_units(attrs[0])\n",
+    "units, m_unit_attr = units_helper.get_units(attrs['length'])\n",
     "assert units == ureg.m\n",
     "assert str(units) == 'meter'\n",
     "\n",
@@ -195,6 +197,7 @@
       "  pressure = 101325 N/m²\n",
       "  acceleration = 10.0 m/s²\n",
       "  crazyUnits = -3.14 K·kg·s²/m³\n",
+      "  filesize = 42 MB\n",
       "  absTemp = 15.0 °C\n",
       "  deltaTemp = 15.0 Δ°C\n",
       "  density has no value\n",
@@ -213,7 +216,7 @@
     "        print(f'  {feature.name} has no value')\n",
     "    \n",
     "print('Attribute quantities:')\n",
-    "for attr in attrs:\n",
+    "for attr in attrs.values():\n",
     "    _read_print_quantity(attr)\n",
     "print('')"
    ]
@@ -241,6 +244,7 @@
       "  pressure = inf Pa\n",
       "  acceleration = nan m/s²\n",
       "  crazyUnits = -6.28 K·kg·s²/m³\n",
+      "  filesize = 42.0 GB\n",
       "  absTemp = 288.15 K\n",
       "  deltaTemp = 15.0 K\n",
       "  density = 1.225 kg/m³\n",
@@ -250,41 +254,43 @@
    ],
    "source": [
     "# Convert value to another unit (m --> km)\n",
-    "q_m = units_helper.get_quantity(attrs[0])\n",
+    "q_m = units_helper.get_quantity(attrs['length'])\n",
     "q_km = q_m.to(ureg.km)\n",
-    "units_helper.set_quantity(attrs[0], q_km)\n",
+    "units_helper.set_quantity(attrs['length'], q_km)\n",
     "\n",
     "# kg --> lbs\n",
     "units_helper.set_quantity(\n",
-    "    attrs[1], units_helper.get_quantity(\n",
-    "        attrs[1]).to(ureg.lbs))\n",
+    "    attrs['mass'], units_helper.get_quantity(\n",
+    "        attrs['mass']).to(ureg.lbs))\n",
     "\n",
     "# Temperature conversion\n",
     "units_helper.set_quantity(\n",
-    "    attrs[8], units_helper.get_quantity(attrs[8]).to(ureg.K))\n",
+    "    attrs['absTemp'], units_helper.get_quantity(attrs['absTemp']).to(ureg.K))\n",
     "units_helper.set_quantity(\n",
-    "    attrs[9], units_helper.get_quantity(attrs[9]).to(ureg.K))\n",
+    "    attrs['deltaTemp'], units_helper.get_quantity(attrs['deltaTemp']).to(ureg.K))\n",
     "\n",
     "# Set quantity: quantity constructor\n",
     "units_helper.set_quantity(\n",
-    "    attrs[2], units_helper.quantity(150, ureg.kJ))\n",
+    "    attrs['energy'], units_helper.quantity(150, ureg.kJ))\n",
     "\n",
-    "units_helper.set_quantity(attrs[3], 3.14 * ureg.m)\n",
+    "units_helper.set_quantity(attrs['diameter'], 3.14 * ureg.m)\n",
     "\n",
     "# Set quantity: value and parsed unit str\n",
-    "units_helper.set_value_and_units(attrs[4], 42, 'km/h')\n",
+    "units_helper.set_value_and_units(attrs['speed'], 42, 'km/h')\n",
     "\n",
     "# Set special values: inf and NaN\n",
-    "units_helper.set_value_and_units(attrs[5], math.inf, 'Pa')\n",
-    "units_helper.set_value_and_units(attrs[6], math.nan, 'm/s**2')\n",
+    "units_helper.set_value_and_units(attrs['pressure'], math.inf, 'Pa')\n",
+    "units_helper.set_value_and_units(attrs['acceleration'], math.nan, 'm/s**2')\n",
     "\n",
     "# Get and set compound units\n",
-    "quantity = units_helper.get_quantity(attrs[7])\n",
+    "quantity = units_helper.get_quantity(attrs['crazyUnits'])\n",
     "assert len(list(quantity.units._units.unit_items())) > 1\n",
-    "units_helper.set_quantity(attrs[7], quantity*2)\n",
+    "units_helper.set_quantity(attrs['crazyUnits'], quantity*2)\n",
+    "\n",
+    "units_helper.set_quantity(attrs['filesize'], 42*ureg['GB'])\n",
     "\n",
     "# Get preferred units of a quantity base type\n",
-    "quantity_attr = attrs[10]\n",
+    "quantity_attr = attrs['density']\n",
     "assert units_helper.is_typed_by_quantity_value(quantity_attr)\n",
     "units = units_helper.get_quantity_value_units(quantity_attr)\n",
     "assert units == ureg['kg/m**3']\n",
@@ -297,7 +303,7 @@
     "\n",
     "# Read and print all attribute values\n",
     "print('Modified attribute quantities:')\n",
-    "for attr in attrs:\n",
+    "for attr in attrs.values():\n",
     "    _read_print_quantity(attr)\n",
     "print('')"
    ]
@@ -318,6 +324,7 @@
      "output_type": "stream",
      "text": [
       "private import SI::*;\n",
+      "private import SIPrefixes::*;\n",
       "package ThePackage {\n",
       "    part def PartWithAttributes {\n",
       "        attribute length = 1 [km];\n",
@@ -332,6 +339,7 @@
       "        attribute acceleration = null ['m⋅s⁻²'];\n",
       "\n",
       "        attribute crazyUnits = -6.28 [K * kg * s^2 * m^(-3)];\n",
+      "        attribute filesize = 42 [giga * B];\n",
       "\n",
       "        attribute absTemp = 288.15 [K];\n",
       "        attribute deltaTemp = 15 [K];\n",
@@ -681,8 +689,8 @@
       "42 meter / second\n",
       "attribute speed = 42 [SI::'m/s'];\n",
       "\n",
-      "42 kelvin * kilogram / meter ** 3\n",
-      "attribute valueWithCustomUnits = 42 [SI::K * SI::kg * SI::m^(-3)];\n",
+      "42 kilogram * megakelvin / meter ** 3\n",
+      "attribute valueWithCustomUnits = 42 [SIPrefixes::mega * (SI::kg * SI::K * SI::m^(-3))];\n",
       "\n"
      ]
     }
@@ -699,8 +707,8 @@
     "units_helper.set_quantity(attr, quantity)\n",
     "print(units_helper.to_text(attr))\n",
     "\n",
-    "# Compound units not available as a separate units attribute: K*kg/m**3\n",
-    "model, _, elements = read_sysml(\"attribute valueWithCustomUnits = 42 [SI::K * SI::kg / SI::m^3];\")\n",
+    "# Compound units not available as a separate units attribute: mega*K*kg/m**3\n",
+    "model, _, elements = read_sysml(\"attribute valueWithCustomUnits = 42 [SIPrefixes::mega * SI::K * SI::kg / SI::m^3];\")\n",
     "units_helper = SysMLUnitsHelper(model)\n",
     "\n",
     "attr = elements[0]\n",
@@ -824,8 +832,7 @@
    "id": "1571c0b9-6fc5-4ca4-91e5-8a5cc5d12697",
    "metadata": {},
    "source": [
-    "Sometimes units are converted to their base definitions, for example when prefixes (e.g. kilo, mega) are used.\n",
-    "To support this, you can use the `scale` output of `set_units` to correct your value:"
+    "Unit prefixes are automatically applied:"
    ]
   },
   {
@@ -838,17 +845,16 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "attribute myAttribute = SI::W;\n",
+      "attribute myAttribute = SIPrefixes::mega * SI::W;\n",
       "\n"
      ]
     }
    ],
    "source": [
-    "scale = units_helper.set_units(attr, 'MW')\n",
-    "assert scale == 1e6\n",
+    "units_helper.set_units(attr, 'MW')\n",
     "\n",
     "units, _ = units_helper.get_units(attr)\n",
-    "assert units == ureg.W\n",
+    "assert units == ureg('MW').units\n",
     "print(units_helper.to_text(attr))"
    ]
   },
@@ -870,17 +876,17 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "attribute myAttribute = SI::K * SI::kg * SI::m^(-1);\n",
+      "attribute myAttribute = SIPrefixes::mega * (SI::K * SI::kg * SI::m^(-1));\n",
       "\n"
      ]
     }
    ],
    "source": [
-    "units_helper.set_units(attr, 'K*kg/m')\n",
+    "units_helper.set_units(attr, 'megaK*kg/m')\n",
     "print(units_helper.to_text(attr))\n",
     "\n",
     "units, units_attr = units_helper.get_units(attr)\n",
-    "assert units == ureg('K*kg/m').units\n",
+    "assert units == ureg('megaK*kg/m').units\n",
     "assert units_attr is None  # There is no single units attribute that represents these compound units"
    ]
   },
@@ -972,7 +978,8 @@
    "source": [
     "### Convert between Pint or str units and SysML units\n",
     "\n",
-    "Note: this only works for non-compound units (working with SysML units expressions is only implemented for getting/setting units/quantities as feature values)!"
+    "Note: this only works for non-compound units!\n",
+    "Working with SysML units expressions is only implemented for getting/setting units/quantities as feature values."
    ]
   },
   {
@@ -990,7 +997,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Cannot map Pint units to SysML: kelvin * kilogram / meter\n"
+      "Could not convert pint units \"<K·kg/m> kelvin·kilogram/meter\" to SysML units\n"
      ]
     }
    ],