From 553332393aee04846e0d248ab45e6af223ede5f2 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 13:36:23 -0500 Subject: [PATCH 1/8] refs #555 XML Schema changed, python code needs to be updated --- nxdlTypes.xsd | 407 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 368 insertions(+), 39 deletions(-) diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd index 8c327361dc..427b7e5e63 100644 --- a/nxdlTypes.xsd +++ b/nxdlTypes.xsd @@ -29,55 +29,379 @@ For further information, see http://www.nexusformat.org + + - - + + - Unit categories in NXDL specifications - describe the expected type of units for a NeXus field. + Unit categories in NXDL specifications describe the expected type of units for a NeXus field. + They should describe valid units consistent with the manual section on NeXus units (based on UDUNITS). Units are not validated by NeXus. - - example: degrees or radians or arcminutes or - usage: things like logs that aren't picky on units - example: m2 or barns - example: barns - example: pC or C - example: A - for fields where the units cancel out, example: "" or mm/mm (NOTE: not the same as NX_UNITLESS) - emittance (``length * angle``) of a radiation source, example: ``nm*rad`` - example: J or keV - example: s-1 cm-2 - example: Hz - example: m - example: g - example: g cm-3 - example: g mol-1 - example: cm-2 - example: cm-1 - (alias to NX_TIME) period of pulsed source, example: microseconds - example: W - example: Pa - (alias to NX_NUMBER) clock pulses - example: cm-2 - example: sr | steradian - example: K - example: s - (alias to NX_TIME) example: s - example: V - example: m3 - for fields that don't have a unit (e.g. hkl) so that they don't inherit the wrong units (NOTE: not the same as NX_DIMENSIONLESS) - example: angstrom - units for Q, example: angstrom-1 or nm-1 - + + + + + + + units of angle, example: m + + + + + + + + + units for things like logs that aren't picky on units + + + + + + + + + units of area, example: m2 or barns + + + + + + + + + units of area, example: barns (alias of NX_AREA) + + + + + + + + + units of electrical charge, example: c + + + + + + + + + units of electrical current, example: A + + + + + + + + + units for fields where the units cancel out, + example: "" or mm/mm + (NOTE: not the same as NX_UNITLESS) + + + + + + + + + units of emittance (``length * angle``) of a + radiation source, example: ``nm*rad`` + + + + + + + + + units of energy, example: J or keV + + + + + + + + + units of flux, example: s-1 cm-2 + + + + + + + + + units of frequency, example: Hz + + + + + + + + + units of length, example: m + + + + + + + + + units of length, example: g + + + + + + + + + units of mass density, example: g cm-3 + + + + + + + + + units of molecular weight, example: g mol-1 + + + + + + + + + units of length, example: m + + + + + + + + + units of length, example: m + + + + + + + + + units of time, period of pulsed source, + example: microseconds (alias to NX_TIME) + + + + + + + + + units of power, example: W + + + + + + + + + units of pressure, example: Pa + + + + + + + + + units of clock pulses (alias to NX_NUMBER) + + + + + + + + + units of scattering length density, example: cm-2 + + + + + + + + + + + units of solid angle, example: sr | steradian + + + + + + + + + units of temperature, example: K + + + + + + + + + units of time, example: s + + + + + + + + + units of (neutron) time of flight, + example: s (alias to NX_TIME) + + + + + + + + + units of the specified transformation + + could be any of these: ``NX_LENGTH``, ``NX_ANGLE``, or ``NX_UNITLESS`` + + There will be one or more transformations defined by one or more fields + for each transformation. The units type ``NX_TRANSFORMATION`` designates the + particular axis generating a transformation (e.g. a rotation axis or a translation + axis or a general axis). ``NX_TRANSFORMATION`` designates the + units will be appropriate to the type of transformation, + indicated in the :ref:`NXtransformations` base class + by the ``transformation_type`` value: + + * ``NX_LENGTH`` for ``translation`` + * ``NX_ANGLE`` for ``rotation`` + * ``NX_UNITLESS`` for axes for which no transformation type is specified. + + + - + + + + for fields that don't have a unit (e.g. hkl) so that they don't + inherit the wrong units (NOTE: not the same as NX_DIMENSIONLESS) + + + + + + + + + units of voltage, example: V + + + + + + + + + units of volume, example: m3 + + + + + + + + + units of wavelength, example: angstrom + + + + + + + + + units of wavenumber or Q, + example: `angstrom-1` or `nm-1` + + + + + + + + @@ -146,7 +470,12 @@ any valid NeXus number representation - + From 62abb9e56233b4a12b3bd8e8d3d83db67a7039a9 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 13:38:34 -0500 Subject: [PATCH 2/8] fixes #545 --- base_classes/NXtransformations.nxdl.xml | 75 ++++++++++++------------- 1 file changed, 36 insertions(+), 39 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 655f561077..586d65a677 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -33,13 +33,7 @@ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd" > - - + Collection of axis-based translations and rotations to describe a geometry. May also contain axes that do not move and therefore do not have a transformation @@ -49,54 +43,56 @@ A nested sequence of transformations lists the offset and rotation steps needed to describe the position and orientation of any movable or fixed device. - + There will be one or more transformations (axes) defined by one or more fields for each transformation. The all-caps name ``AXISNAME`` designates the particular axis generating a transformation (e.g. a rotation axis or a translation - axis or a general axis). The all-caps name ``AXISUNITS`` designates the - units appropriate to the transformation_type value, i.e. ``NX_LENGTH`` for - ``translation``, ``NX_ANGLE`` for ``rotation``, and ``NX_UNITLESS`` for - axes for which no transformation type is specified. - + axis or a general axis). The attribute ``units="NX_TRANSFORMATION"`` designates the + units will be appropriate to the ``transformation_type`` attribute: + + * ``NX_LENGTH`` for ``translation`` + * ``NX_ANGLE`` for ``rotation`` + * ``NX_UNITLESS`` for axes for which no transformation type is specified + This class will usually contain all axes of a sample stage or goniometer or a detector. The NeXus default McSTAS coordinate frame is assumed, but additional useful coordinate axes may be defined by using axes for which no transformation type has been specified. - + The entry point (``depends_on``) will be outside of this class and point to a field in here. Following the chain may also require following ``depends_on`` links to transformations outside, for example to a common base table. If a relative path is given, it is relative to the group enclosing the ``depends_on`` specification. - + For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is .. math:: - - T_f = T_3 T_2 T_1 - + + T_f = T_3 T_2 T_1 + In explicit terms, the transformations are a subset of affine transformations expressed as 4x4 matrices that act on homogeneous coordinates, :math:`w=(x,y,z,1)^T`. - + For rotation and translation, - - .. math:: - - T_r &= \left( \begin{matrix} R & o \\ - 0_3 & 1 \end{matrix} \right) \\ - T_t &= \left( \begin{matrix} I_3 & t + o \\ - 0_3 & 1 \end{matrix} \right) - + + .. math:: + + T_r &= \left( \begin{matrix} R & o \\ + 0_3 & 1 \end{matrix} \right) \\ + T_t &= \left( \begin{matrix} I_3 & t + o \\ + 0_3 & 1 \end{matrix} \right) + where :math:`R` is the usual 3x3 rotation matrix, :math:`o` is an offset vector, :math:`0_3` is a row of 3 zeros, :math:`I_3` is the 3x3 identity matrix and :math:`t` is the translation vector. - + :math:`o` is given the ``offset`` attribute, :math:`t` is given by the ``vector`` attribute multiplied by the field value, and :math:`R` is defined as a rotation about an axis in the direction of ``vector``, of angle of the field value. - + Units need to be appropriate for translation or rotation @@ -104,7 +100,7 @@ that does not cause confusion. When using more than one ``AXISNAME`` field, make sure that each field name is unique in the same group, as required by HDF5. - + The values given should be the start points of exposures for the corresponding frames. The end points should be given in ``AXISNAME_end``. @@ -113,15 +109,16 @@ The transformation_type may be ``translation``, in which case the values are linear displacements along the axis, ``rotation``, in which case the values are angular rotations around the axis. - - If this attribute is omitted, this field does not specify a transformation - of an object, but is used to document a general axis or direction, - such as the direction of gravity, or of the source. - As such it cannot be used in a depends_on transformation chain. + + If this attribute is omitted, this is an axis for which there + is no motion to be specifies, such as the direction of gravity, + or the direction to the source, or a basis vector of a + coordinate frame. + @@ -153,20 +150,20 @@ - + ``AXISNAME_end`` is a placeholder for a name constructed from the actual name of an axis to which ``_end`` has been appended. - + The values in this field are the end points of the motions that start at the corresponding positions given in the ``AXISNAME`` field. - + ``AXISNAME_increment_set`` is a placeholder for a name constructed from the actual name of an axis to which ``_increment_set`` has been appended. - + The value of this optional field is the intended average range through which the corresponding axis moves during the exposure of a frame. Ideally, the value of this field added to each value of ``AXISNAME`` would agree with the From d1635e7f05307de5a362e75ae19670b0b014e526 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 13:54:38 -0500 Subject: [PATCH 3/8] fixes #548 --- base_classes/NXtransformations.nxdl.xml | 8 ++++++-- nxdl.xsd | 7 +++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 586d65a677..d3e9027bc7 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -130,13 +130,17 @@ For ``translation`` axes the direction should be chosen for increasing displacement. - + + + A fixed offset applied before the transformation (three vector components). - + + + diff --git a/nxdl.xsd b/nxdl.xsd index 48953eb5e7..50a04da9d2 100644 --- a/nxdl.xsd +++ b/nxdl.xsd @@ -872,6 +872,13 @@ + + + + dimensions of an attribute with data value(s) in a NeXus file + + + From 0bd6729fc7063aa546981846c909f6d45a22f17e Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 14:02:19 -0500 Subject: [PATCH 4/8] refs #555 : Sphinx --- manual/source/community.rst | 6 +++--- manual/source/conf.py | 8 ++++++-- manual/source/utilities.rst | 2 +- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/manual/source/community.rst b/manual/source/community.rst index 993e4d8b8b..768fd075f6 100644 --- a/manual/source/community.rst +++ b/manual/source/community.rst @@ -32,7 +32,7 @@ development of NeXus with the larger community. .. _NeXus.webpage: NeXus Webpage -============ +============= First of all, there is the NeXus webpage, http://www.nexusformat.org/, @@ -50,7 +50,7 @@ code are always welcome! .. _community.Contributed.Definitions: Contributed Definitions -======================== +======================= The community is encouraged to provide new definitions (:ref:`base.class.definitions` or :ref:`application.definitions`) for consideration @@ -59,7 +59,7 @@ will be entered in the :ref:`contributed.definitions` and will be curated according to procedures set forth by the :ref:`NIAC`. Other Ways NeXus Coordinates with the Scientific Community -============================================================ +========================================================== .. toctree:: :maxdepth: 1 diff --git a/manual/source/conf.py b/manual/source/conf.py index c7c92be240..e1d3b419ee 100755 --- a/manual/source/conf.py +++ b/manual/source/conf.py @@ -216,14 +216,18 @@ # If true, show URL addresses after external links. #latex_show_urls = False -# Additional stuff for the LaTeX preamble. -latex_preamble = ''' +# Additional stuff for the LaTeX preamble_text. +preamble_text = ''' % 2012-09-25,PRJ: #240 temporary diagnostic \\listfiles % when done, remove referencing from index.rst and cp from Makefile: latexpdf \usepackage{enumitem} \setlistdepth{9} ''' +latex_elements = { + 'preamble_text': preamble_text # the new way +} +latex_preamble = preamble_text # the old way # Documents to append as an appendix to all manuals. #latex_appendices = [] diff --git a/manual/source/utilities.rst b/manual/source/utilities.rst index 99958aa2aa..76099a6100 100644 --- a/manual/source/utilities.rst +++ b/manual/source/utilities.rst @@ -157,7 +157,7 @@ The list is not intended to be a complete list of all available packages. See the program documentation for more details: https://punx.readthedocs.io -+ + Data Analysis ############# From 818324b2de9967f82db6b9cad957fd413dc455b7 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 14:06:00 -0500 Subject: [PATCH 5/8] refs #555 Sphinx --- manual/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/source/conf.py b/manual/source/conf.py index e1d3b419ee..3bc5a6a878 100755 --- a/manual/source/conf.py +++ b/manual/source/conf.py @@ -227,7 +227,7 @@ latex_elements = { 'preamble_text': preamble_text # the new way } -latex_preamble = preamble_text # the old way +#latex_preamble = preamble_text # the old way # Documents to append as an appendix to all manuals. #latex_appendices = [] From 84c8576cc999e1aef94b1d48cc04ce5a160e9c97 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 14:34:02 -0500 Subject: [PATCH 6/8] refs #555 : docs build with units described --- nxdlTypes.xsd | 7 ++++--- utils/types2rst.py | 48 ++++++++++++++++++++++++++++++++++++++++++++-- utils/units2rst.py | 27 ++++++++++++++++++++------ 3 files changed, 71 insertions(+), 11 deletions(-) diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd index 427b7e5e63..36636c1985 100644 --- a/nxdlTypes.xsd +++ b/nxdlTypes.xsd @@ -65,6 +65,7 @@ nxdl:NX_MOLECULAR_WEIGHT nxdl:NX_PER_AREA nxdl:NX_PER_LENGTH + nxdl:NX_PERIOD nxdl:NX_POWER nxdl:NX_PRESSURE nxdl:NX_PULSES @@ -243,7 +244,7 @@ units of time, period of pulsed source, - example: microseconds (alias to NX_TIME) + example: microseconds (alias to `NX_TIME`) @@ -270,7 +271,7 @@ - units of clock pulses (alias to NX_NUMBER) + units of clock pulses (alias to `NX_NUMBER`) @@ -319,7 +320,7 @@ units of (neutron) time of flight, - example: s (alias to NX_TIME) + example: s (alias to `NX_TIME`) diff --git a/utils/types2rst.py b/utils/types2rst.py index 1fc081c628..203852b80c 100755 --- a/utils/types2rst.py +++ b/utils/types2rst.py @@ -8,11 +8,55 @@ ''' -import units2rst +import os, sys +import lxml.etree + + +def worker(nodeMatchString, section = 'units'): + if len(sys.argv) != 2: + print("usage: %s nxdlTypes.xsd" % sys.argv[0]) + exit() + NXDL_TYPES_FILE = sys.argv[1] + if not os.path.exists(NXDL_TYPES_FILE): + print("Cannot find %s" % NXDL_TYPES_FILE) + exit() + + tree = lxml.etree.parse(NXDL_TYPES_FILE) + + output = ['.. auto-generated by %s -- DO NOT EDIT' % sys.argv[0]] + output.append('') + + labels = ('term', 'description') + output.append('.. nodeMatchString : %s' % nodeMatchString) + output.append('') + db = {} + + NAMESPACE = 'http://www.w3.org/2001/XMLSchema' + ns = {'xs': NAMESPACE} + root = tree.xpath('//xs:schema', namespaces=ns)[0] + s = '//xs:simpleType' + for node in tree.xpath("//xs:simpleType", namespaces=ns): + if node.get('name') == nodeMatchString: + for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns): + key = '%s' % item.get('value') + words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0] + db[key] = words.text + + print('\n'.join(output)) + + # this list is too long to make this a table in latex + # for two columns, a Sphinx fieldlist will do just as well + for key in sorted(db): + print('.. index:: ! %s (%s type)\n' % (key, section)) # index entry + print('.. _%s:\n' % key) # cross-reference point + print(':%s:' % key) + for line in db[key].splitlines(): + print(' %s' % line) + print('') if __name__ == '__main__': - units2rst.worker('NAPI', section = 'data') + worker('NAPI', section = 'data') # NeXus - Neutron and X-ray Common Data Format diff --git a/utils/units2rst.py b/utils/units2rst.py index 56958fe7f2..4d5d8049d9 100755 --- a/utils/units2rst.py +++ b/utils/units2rst.py @@ -23,7 +23,7 @@ def worker(nodeMatchString, section = 'units'): tree = lxml.etree.parse(NXDL_TYPES_FILE) - output = ['.. auto-generated -- DO NOT EDIT'] + output = ['.. auto-generated by %s -- DO NOT EDIT' % sys.argv[0]] output.append('') labels = ('term', 'description') @@ -35,12 +35,26 @@ def worker(nodeMatchString, section = 'units'): ns = {'xs': NAMESPACE} root = tree.xpath('//xs:schema', namespaces=ns)[0] s = '//xs:simpleType' - for node in tree.xpath("//xs:simpleType", namespaces=ns): + node_list = tree.xpath("//xs:simpleType", namespaces=ns) + + # get the names of all the types of units + members = [] + for node in node_list: if node.get('name') == nodeMatchString: - for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns): - key = '%s' % item.get('value') - words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0] - db[key] = words.text + union = node.xpath('xs:union', namespaces=ns) + members = union[0].get('memberTypes', '').split() + + # get the definition of each type of units + for node in node_list: + node_name = node.get('name') + if 'nxdl:' + node_name in members: + words = node.xpath('xs:annotation/xs:documentation', namespaces=ns)[0] + db[node_name] = words.text + +# for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns): +# key = '%s' % item.get('value') +# words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0] +# db[key] = words.text print('\n'.join(output)) @@ -56,6 +70,7 @@ def worker(nodeMatchString, section = 'units'): if __name__ == '__main__': + #sys.argv.append('../nxdlTypes.xsd') # FIXME: developer only -- remove for production!!! worker('anyUnitsAttr') From 07eb8db186decff3949289d0ef341e2f9ca604e8 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Sun, 9 Apr 2017 14:40:19 -0500 Subject: [PATCH 7/8] fixes #555 --- nxdlTypes.xsd | 24 +++++++++++------------ utils/types2rst.py | 48 ++-------------------------------------------- 2 files changed, 14 insertions(+), 58 deletions(-) diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd index 36636c1985..4ce9e1e8ea 100644 --- a/nxdlTypes.xsd +++ b/nxdlTypes.xsd @@ -418,18 +418,18 @@ any valid NeXus type - - any string representation - any representation of a floating point number - any representation of an integer number - any representation of an unsigned integer number (includes zero) - any representation of a positive integer number (greater than zero) - any valid NeXus number representation - alias of ISO8601 - ISO 8601 date and time representation (http://www.w3.org/TR/NOTE-datetime) - true/false value ( true | 1 | false | 0 ) - any representation of binary data - if text, line terminator is [CR][LF] - + diff --git a/utils/types2rst.py b/utils/types2rst.py index 203852b80c..1fc081c628 100755 --- a/utils/types2rst.py +++ b/utils/types2rst.py @@ -8,55 +8,11 @@ ''' -import os, sys -import lxml.etree - - -def worker(nodeMatchString, section = 'units'): - if len(sys.argv) != 2: - print("usage: %s nxdlTypes.xsd" % sys.argv[0]) - exit() - NXDL_TYPES_FILE = sys.argv[1] - if not os.path.exists(NXDL_TYPES_FILE): - print("Cannot find %s" % NXDL_TYPES_FILE) - exit() - - tree = lxml.etree.parse(NXDL_TYPES_FILE) - - output = ['.. auto-generated by %s -- DO NOT EDIT' % sys.argv[0]] - output.append('') - - labels = ('term', 'description') - output.append('.. nodeMatchString : %s' % nodeMatchString) - output.append('') - db = {} - - NAMESPACE = 'http://www.w3.org/2001/XMLSchema' - ns = {'xs': NAMESPACE} - root = tree.xpath('//xs:schema', namespaces=ns)[0] - s = '//xs:simpleType' - for node in tree.xpath("//xs:simpleType", namespaces=ns): - if node.get('name') == nodeMatchString: - for item in node.xpath('xs:restriction//xs:enumeration', namespaces=ns): - key = '%s' % item.get('value') - words = item.xpath('xs:annotation/xs:documentation', namespaces=ns)[0] - db[key] = words.text - - print('\n'.join(output)) - - # this list is too long to make this a table in latex - # for two columns, a Sphinx fieldlist will do just as well - for key in sorted(db): - print('.. index:: ! %s (%s type)\n' % (key, section)) # index entry - print('.. _%s:\n' % key) # cross-reference point - print(':%s:' % key) - for line in db[key].splitlines(): - print(' %s' % line) - print('') +import units2rst if __name__ == '__main__': - worker('NAPI', section = 'data') + units2rst.worker('NAPI', section = 'data') # NeXus - Neutron and X-ray Common Data Format From b459b6610847f26eb45483fdb23055c60ea57449 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Mon, 1 May 2017 10:20:47 -0500 Subject: [PATCH 8/8] #555, #558: bumping NXDL version number to 3.3 NOTE: This is different than the "3.1" used in the XML namespace. --- NXDL_VERSION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/NXDL_VERSION b/NXDL_VERSION index a3ec5a4bd3..eb39e5382f 100644 --- a/NXDL_VERSION +++ b/NXDL_VERSION @@ -1 +1 @@ -3.2 +3.3