From bc824d7c14931f1535d36e311afb5f6e092904e0 Mon Sep 17 00:00:00 2001 From: rbovill Date: Wed, 20 Mar 2024 15:21:34 -0700 Subject: [PATCH 1/3] Added the XML Units policy document to Control-User-Interfaces. --- Control-User-Interfaces/XML_Units.rst | 83 +++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 Control-User-Interfaces/XML_Units.rst diff --git a/Control-User-Interfaces/XML_Units.rst b/Control-User-Interfaces/XML_Units.rst new file mode 100644 index 0000000..8211781 --- /dev/null +++ b/Control-User-Interfaces/XML_Units.rst @@ -0,0 +1,83 @@ +.. This is a template top-level index file for a directory in the procedure's arm of the documentation + +.. This is the label that can be used as for cross referencing in the given area +.. Recommended format is "Directory Name"-"Title Name" -- Spaces should be replaced by hypens +.. _XML_Units: + +################## +XML Unit Standards +################## + +.. Glossary of Terms + +.. list-table:: Glossary of Terms + :widths: 10 50 + + * - CAP + - Commissioning Activities Planning + * - CSC + - Commandable SAL Component + * - EFD + - Engineering Facility Database + * - SI + - International System of Units + * - TSSW + - Telescope & Site Software + * - XML + - eXtensible Markup Language + +.. Define policy pertaining to XML unit definitions + +It is the policy of this Project to use the `International System of Units `_ (SI), by default, in all XML Unit definitions. The Project recognizes that certain hardware and system constraints may require the use of units outside this standard. For example, many hardware components measure pressure in the common Imperial units of psi, psia or psig (all variants of pounds per square inch). Steps were taken to allow for exceptions in these cases. The process for requesting an exception is defined in the Non-SI Unit Requests section of this document. + +The Commandable SAL Component (CSC) interface definitions, the XML files, are located in the `ts_xml `_ repository. This repo is maintained by the Telescope & Site Software (TSSW) team, but is utilized by the Project as a whole. As such, this Unit Standards definition is published at the `Observatory Controls `_ level, but is cross-linked to the `TSSW Developer Guide `_ for completeness. + + +XML Unit Standards Verification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Project elected to use the `Astropy Python library `_ to verify the units defined in the XML files conform to SI-standards. Additionally, all XML formatting is defined by the schemas located in the `ts_xml `_ repository. The enforcement of these content and formatting standards is done via the `unit tests `_ that are run automatically with each new commit and pull request. They can also be run manually by following the instructions located in the `ts_xml README `_. + +The Astropy library also contains utilities for unit conversion. As such, it is possible to take non-SI units published by hardware components or third-party software tools and convert them to SI-units, in the CSC code, for the purpose of interface definitions and publishing to the Engineering Facility Database (EFD). For example, to convert psi to Pa, the following code example can be used: + +.. code-block:: python + + import astropy.units as u + from astropy.units import imperial, misc + + def psi_to_pa(value: float) -> float: + """Convert a value in PSI to a value in Pa. + + Parameters + ---------- + value: `float` + The value in PSI. + + Returns + ------- + float + The value in Pa. + """ + quantity_in_psi = value * imperial.psi + quantity_in_pa = quantity_in_psi.to(u.Pa) + return quantity_in_pa.value + +Non-SI Unit Requests +^^^^^^^^^^^^^^^^^^^^ + +To request the use of a non-SI unit, a request must be made at the weekly Commissioning Activities Planning (CAP) meeting. The request must be made and approved BEFORE the changes are implemented. Simply add an agenda item to the `Future Meetings `_ page, attend the specific meeting once accepted and present the case. If approved, continue with the development process defined in the `TSSW Developer Guide `_, specifically the `Reporting Work for XML Release `_ section. + +Types of Exceptions +------------------- + +There are actually two ways to handle non-standard unit exceptions: + +#. Improvements to the Astropy library. +#. Explicit unit test exceptions. + +For the first case, there have been times when a conventional SI unit was not included in the Astropy definition. In this case, a change request was made directly to the Astropy maintainers to add the unit to the library. In the interim, until the change is released, the second method is used and then removed. + +In the second case, the `unit test `_ that verifies unit conformity is updated to allow for the non-standard unit. Either the unit is added to the NONSTANDARD_UNITS list, or it is added to the local instance of the Astropy library using the tools provided by the library itself. Examples of both methods can be found in the unit test file linked above. + +Any changes to the unit test constitute a change to the ts_xml package, and therefore must follow the development guidelines before being released. + From 93011c18220ff262bfa34f0f3937a97197274c78 Mon Sep 17 00:00:00 2001 From: rbovill Date: Wed, 20 Mar 2024 15:59:29 -0700 Subject: [PATCH 2/3] Fixed a broken link in System-Testing-Deployments-and-Upgrades/Control-System-Upgrade/Getting-Ready/index.rst. --- .../Control-System-Upgrade/Getting-Ready/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/System-Testing-Deployments-and-Upgrades/Control-System-Upgrade/Getting-Ready/index.rst b/System-Testing-Deployments-and-Upgrades/Control-System-Upgrade/Getting-Ready/index.rst index eb849ec..db20ec1 100644 --- a/System-Testing-Deployments-and-Upgrades/Control-System-Upgrade/Getting-Ready/index.rst +++ b/System-Testing-Deployments-and-Upgrades/Control-System-Upgrade/Getting-Ready/index.rst @@ -16,7 +16,7 @@ Upgrading the Interface (XML) * This is identified by label of: ``ts_xml X.Y``. * Use the ``release_tickets`` script in the vanward_ package. #. Ensure that all work merged in the `ts_xml `_ repository has a ticket associated with it in the release. - * Folks should be following the `XML Work Reporting `_ procedure. + * Folks should be following the `XML Work Reporting `_ procedure. * Use the ``find_merges_without_release_tickets`` script in the vanward_ package. #. Send a reminder about the work closure deadline at least one day prior AND the day of the closure. #. Ensure that all work tickets are closed when the deadline passes (use Step 4 script). From 83c0168563f5a77e119c28455b45f390ac15cb1d Mon Sep 17 00:00:00 2001 From: Rob Bovill Date: Thu, 21 Mar 2024 12:04:50 -0700 Subject: [PATCH 3/3] Formatting improvements to XML_Units.rst. --- Control-User-Interfaces/XML_Units.rst | 32 +++++++++++++++++++++------ 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/Control-User-Interfaces/XML_Units.rst b/Control-User-Interfaces/XML_Units.rst index 8211781..8edff6b 100644 --- a/Control-User-Interfaces/XML_Units.rst +++ b/Control-User-Interfaces/XML_Units.rst @@ -28,17 +28,28 @@ XML Unit Standards .. Define policy pertaining to XML unit definitions -It is the policy of this Project to use the `International System of Units `_ (SI), by default, in all XML Unit definitions. The Project recognizes that certain hardware and system constraints may require the use of units outside this standard. For example, many hardware components measure pressure in the common Imperial units of psi, psia or psig (all variants of pounds per square inch). Steps were taken to allow for exceptions in these cases. The process for requesting an exception is defined in the Non-SI Unit Requests section of this document. +It is the policy of this Project to use the `International System of Units `_ (SI), by default, in all XML Unit definitions. +The Project recognizes that certain hardware and system constraints may require the use of units outside this standard. +For example, many hardware components measure pressure in the common Imperial units of psi, psia or psig (all variants of pounds per square inch). +Steps were taken to allow for exceptions in these cases. +The process for requesting an exception is defined in the Non-SI Unit Requests section of this document. -The Commandable SAL Component (CSC) interface definitions, the XML files, are located in the `ts_xml `_ repository. This repo is maintained by the Telescope & Site Software (TSSW) team, but is utilized by the Project as a whole. As such, this Unit Standards definition is published at the `Observatory Controls `_ level, but is cross-linked to the `TSSW Developer Guide `_ for completeness. +The Commandable SAL Component (CSC) interface definitions, the XML files, are located in the `ts_xml `_ repository. +This repo is maintained by the Telescope & Site Software (TSSW) team, but is utilized by the Project as a whole. +As such, this Unit Standards definition is published at the `Observatory Controls `_ level, but is cross-linked to the `TSSW Developer Guide `_ for completeness. XML Unit Standards Verification ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The Project elected to use the `Astropy Python library `_ to verify the units defined in the XML files conform to SI-standards. Additionally, all XML formatting is defined by the schemas located in the `ts_xml `_ repository. The enforcement of these content and formatting standards is done via the `unit tests `_ that are run automatically with each new commit and pull request. They can also be run manually by following the instructions located in the `ts_xml README `_. +The Project elected to use the `Astropy Python library `_ to verify the units defined in the XML files conform to SI-standard. +Additionally, all XML formatting is defined by the schemas located in the `ts_xml `_ repository. +The enforcement of these content and formatting standards is done via the `unit tests `_ that are run automatically with each new commit and pull request. +They can also be run manually by following the instructions located in the `ts_xml README `_. -The Astropy library also contains utilities for unit conversion. As such, it is possible to take non-SI units published by hardware components or third-party software tools and convert them to SI-units, in the CSC code, for the purpose of interface definitions and publishing to the Engineering Facility Database (EFD). For example, to convert psi to Pa, the following code example can be used: +The Astropy library also contains utilities for unit conversion. +As such, it is possible to take non-SI units published by hardware components or third-party software tools and convert them to SI-units, in the CSC code, for the purpose of interface definitions and publishing to the Engineering Facility Database (EFD). +For example, to convert psi to Pa, the following code example can be used: .. code-block:: python @@ -65,7 +76,10 @@ The Astropy library also contains utilities for unit conversion. As such, it is Non-SI Unit Requests ^^^^^^^^^^^^^^^^^^^^ -To request the use of a non-SI unit, a request must be made at the weekly Commissioning Activities Planning (CAP) meeting. The request must be made and approved BEFORE the changes are implemented. Simply add an agenda item to the `Future Meetings `_ page, attend the specific meeting once accepted and present the case. If approved, continue with the development process defined in the `TSSW Developer Guide `_, specifically the `Reporting Work for XML Release `_ section. +To request the use of a non-SI unit, a request must be made at the weekly Commissioning Activities Planning (CAP) meeting. +The request must be made and approved BEFORE the changes are implemented. +Simply add an agenda item to the `Future Meetings `_ page, attend the specific meeting once accepted and present the case. +If approved, continue with the development process defined in the `TSSW Developer Guide `_, specifically the `Reporting Work for XML Release `_ section. Types of Exceptions ------------------- @@ -75,9 +89,13 @@ There are actually two ways to handle non-standard unit exceptions: #. Improvements to the Astropy library. #. Explicit unit test exceptions. -For the first case, there have been times when a conventional SI unit was not included in the Astropy definition. In this case, a change request was made directly to the Astropy maintainers to add the unit to the library. In the interim, until the change is released, the second method is used and then removed. +For the first case, there have been times when a conventional SI unit was not included in the Astropy definition. +In this case, a change request is made directly to the Astropy maintainers to add the unit to the library. +In the interim, until the change is released, the second method is used and then removed. -In the second case, the `unit test `_ that verifies unit conformity is updated to allow for the non-standard unit. Either the unit is added to the NONSTANDARD_UNITS list, or it is added to the local instance of the Astropy library using the tools provided by the library itself. Examples of both methods can be found in the unit test file linked above. +In the second case, the `unit test `_ that verifies unit conformity is updated to allow for the non-standard unit. +Either the unit is added to the NONSTANDARD_UNITS list, or it is added to the local instance of the Astropy library using the tools provided by the library itself. +Examples of both methods can be found in the unit test file linked above. Any changes to the unit test constitute a change to the ts_xml package, and therefore must follow the development guidelines before being released.