diff --git a/Control-User-Interfaces/XML_Units.rst b/Control-User-Interfaces/XML_Units.rst new file mode 100644 index 0000000..8edff6b --- /dev/null +++ b/Control-User-Interfaces/XML_Units.rst @@ -0,0 +1,101 @@ +.. 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-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: + +.. 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 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. + +Any changes to the unit test constitute a change to the ts_xml package, and therefore must follow the development guidelines before being released. + 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).