Skip to content

ST6RI-606 Code generator tooling for ISQ, SI, US Customary Units libraries#621

Merged
seidewitz merged 7 commits intomasterfrom
ST6RI-606
Mar 13, 2025
Merged

ST6RI-606 Code generator tooling for ISQ, SI, US Customary Units libraries#621
seidewitz merged 7 commits intomasterfrom
ST6RI-606

Conversation

@hpdekoning
Copy link
Member

@hpdekoning hpdekoning commented Feb 15, 2025 •
edited by seidewitz
Loading

This PR provides a new quantities_lib_generator tool under tool-support.

This tool is able to reproduce the SysML release 2024-12 ISQ library packages with a few differences that are all due to minor naming mistakes in the published release 2024-12 libraries and also three editorial issues.

In particular the naming of coordinate frames in release 2024-12 was inconsistent:

  • Most vector quantities and related coordinate frames were using e.g. Cartesian3dXxxVector instead of CartesianXxx3dVector, The latter is the correct naming convention that naturally fits with the quantity taxonomy. More specialized concepts prepend qualifiers to the name, e.g., a specialization chain from VectorQuantityValue to '3dVectorQuantityValue' to Position3dVector to CartesianPosition3dVector or CylindricalPosition3dVector.
  • Also VectorQuantityValue was used in many places instead of the correct '3dVectorQuantityValue'. Same for VectorMeasurementReference instead of '3dCoordinateFrame'.

Also, the following editorial issues were found and fixed:

  1. In ISQCondensedMatter.sysml Item 12-19 Hall coefficient: replaced erroneous unit m^3/Cm^3s^-1A^-1 with correct m^3/C, m^3s^-1*A^-1 (in the Excel workbook data/iso-iec-80000/iso_iec_80000_quantities_and_units.xlsx). As a consequence, the declaration of attribute def HallCoefficientUnit was changed.
  2. ISQSpaceTime.sysml contained redundant private import ScalarValues::String; . It was not generated, which is in line with all other ISQ libraries.
  3. The ISO/IEC 80000 references were checked and where needed updated to the latest correct titles, editions and URIs. This results in minor editorial corrections in the doc content of the libraries.

A detailed review of all differences between the ISQ library packages in folder libs_baseline_release-2024-12 and the auto-generated library packages in folder libs_generated has been performed. No other differences than those documented above have been found.

There are currently no changes to the generation of SI and USCustomaryUnits.

@hpdekoning hpdekoning requested review from himi and seidewitz February 15, 2025 01:26
@hpdekoning hpdekoning self-assigned this Feb 15, 2025
@himi
Copy link
Member

himi commented Feb 16, 2025

In my first attempt, it failed with:

% python quantities_lib_generator.py 
Traceback (most recent call last):
  File "/Users/himi/git/SysML-v2-Pilot-Implementation/tool-support/quantities_lib_generator/quantities_lib_generator.py", line 55, in <module>
    from openpyxl import load_workbook
ModuleNotFoundError: No module named 'openpyxl'

So I think we should explain that we need to install opnepyxl with pip install openpyxl in README.adoc.

After that, I think it worked correctly.

@himi
Copy link
Member

himi commented Feb 16, 2025

Just for your reference, these are the meaningful diffs after I executed:

modified   tool-support/quantities_lib_generator/libs_generated/SI_collected_units.txt
@@ -5,8 +5,8 @@ A*m^2*J^-1*s^-1          for gyromagnetic ratio / GyromagneticRatio
 A*s/kg                   for gyromagnetic ratio / GyromagneticRatio
 A/m                      for linear electric current density / LinearElectricCurrentDensity
 A/m^2                    for electric current density / ElectricCurrentDensity
-B                        for storage capacity / StorageCapacity
 b                        for cross section / Area
+B                        for storage capacity / StorageCapacity
 B/s                      for transfer rate / TransferRate
 Bd                       for modulation rate / ModulationRate
 bit                      for storage capacity / StorageCapacity
@@ -192,8 +192,8 @@ rad*m^2/mol              for molar optical rotatory power / MolarOpticalRotatory
 rad*s^-1                 for angular velocity / AngularVelocity
 rad*s^-2                 for angular acceleration / AngularAcceleration
 rad/m                    for phase coefficient / PhaseCoefficient
-S                        for conductance / Conductance
 s                        for duration / Duration
+S                        for conductance / Conductance
 s*A                      for elementary charge / ElectricCharge
 S*m^2/mol                for molar conductivity / MolarConductivity
 S/m                      for conductivity / Conductivity
modified   tool-support/quantities_lib_generator/libs_generated/SI_snippet.sysml
@@ -34,8 +34,8 @@
     /*
      * Units recognized in SI
      */
-    attribute <B> byte : StorageCapacityUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = bit; :>> conversionFactor = 8; } }
     attribute <b> barn : AreaUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = 'm²'; :>> conversionFactor = 1.0e-28; } }
+    attribute <B> byte : StorageCapacityUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = bit; :>> conversionFactor = 8; } }
     attribute <Da> dalton : MassUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = kg; :>> conversionFactor = 1.66053906660e-27; } }
     attribute <eV> electronvolt : EnergyUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = J; :>> conversionFactor = 1.602176487e-19; } }
     attribute <o> octet : StorageCapacityUnit { :>> unitConversion: ConversionByConvention { :>> referenceUnit = bit; :>> conversionFactor = 8; } }

I think it comes from the order of b and B, but they are effectively equivalent. I have no idea why this script changed the order of these, maybe caused by the sorting option.

@himi
Copy link
Member

himi commented Feb 16, 2025

BTW, is there any official or formal procedure to incorporate SI_snippet.sysml into SI.sysml? Maybe we can automate it by preparing SI.sysml template.

@hpdekoning
Copy link
Member Author

hpdekoning commented Feb 23, 2025

Thanks @himi for your review. I agree with your comments and will address them tomorrow my morning.

@seidewitz seidewitz self-assigned this Feb 25, 2025
@seidewitz seidewitz added this to the 2025-02 milestone Feb 25, 2025
@hpdekoning
Copy link
Member Author

hpdekoning commented Mar 12, 2025 •
edited
Loading

@himi Regarding your comment:

Just for your reference, these are the meaningful diffs after I executed:
...

I think it comes from the order of b and B, but they are effectively equivalent. I have no idea why this script changed the order of these, maybe caused by the sorting option.

The reason that the order in which b (bit) and B (Byte) appear has changed, is due to a small correction in the Generator.__init__ constructor, where storage capacity with byte and octet were changed from SpecialQuantity to RecognizedQuantity. But as you say, the generated SI_snippet.sysml is equivalent.

I have another refactoring prepared for the RTF to clean up the specification of the predefined SI units by moving them to the "Units" worksheet in the "iso_iec_80000_quantities_and_units.xlsx" Excel workbook. It does not change the content of the generated libraries but improved the tool's maintainability.

@hpdekoning
Copy link
Member Author

hpdekoning commented Mar 12, 2025

@himi Regarding your comment:

BTW, is there any official or formal procedure to incorporate SI_snippet.sysml into SI.sysml? Maybe we can automate it by preparing SI.sysml template.

There is currently only an informal procedure to manually paste the whole SI_snippets.sysml block into the SI.sysml standard library. For the SysML v2.0 there is no need to do this as library content has effectively not changed. Certainly automation should be supported and can be implemented as part of the refactoring mentioned above. It should be part of an update in response to a future SysML v2.1 RTF issue. I think there will be a need to generate many more standardized derived and prefixed SI and US Customary units in the near future.

@hpdekoning
Copy link
Member Author

hpdekoning commented Mar 12, 2025 •
edited
Loading

@himi @seidewitz I have just added a commit with an updated README.adoc with instructions to install python module openpyxl, plus some other minor corrections.

seidewitz
seidewitz approved these changes Mar 13, 2025
View reviewed changes
Copy link
Member

@seidewitz seidewitz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also runs successfully in my Mac environment, after the installation of openpyxl.

@seidewitz seidewitz merged commit 1a1bc40 into master Mar 13, 2025
2 checks passed
@hpdekoning hpdekoning mentioned this pull request Mar 13, 2025
Merged
@seidewitz seidewitz mentioned this pull request Mar 27, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@seidewitz seidewitz seidewitz approved these changes

@himi himi Awaiting requested review from himi

Assignees

@seidewitz seidewitz

@hpdekoning hpdekoning

Labels

None yet

Projects

None yet

Milestone

2025-02

Development

Successfully merging this pull request may close these issues.

3 participants

@hpdekoning @himi @seidewitz