diff --git a/NXDL_VERSION b/NXDL_VERSION index a3ec5a4bd3..eb39e5382f 100644 --- a/NXDL_VERSION +++ b/NXDL_VERSION @@ -1 +1 @@ -3.2 +3.3 diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 655f561077..d3e9027bc7 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. + @@ -133,13 +130,17 @@ For ``translation`` axes the direction should be chosen for increasing displacement. - + + + A fixed offset applied before the transformation (three vector components). - + + + @@ -153,20 +154,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 diff --git a/manual/source/community.rst b/manual/source/community.rst index 68ce19fca5..768fd075f6 100644 --- a/manual/source/community.rst +++ b/manual/source/community.rst @@ -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..3bc5a6a878 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/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 + + + diff --git a/nxdlTypes.xsd b/nxdlTypes.xsd index 8c327361dc..4ce9e1e8ea 100644 --- a/nxdlTypes.xsd +++ b/nxdlTypes.xsd @@ -29,55 +29,380 @@ 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` + + + + + + + + @@ -93,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] - + @@ -146,7 +471,12 @@ any valid NeXus number representation - + 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')