.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source ../../../../base_classes/NXsample.nxdl.xml

.. index::
    ! NXsample (base class)
    ! sample (base class)
    see: sample (base class); NXsample

.. _NXsample:

========
NXsample
========

**Status**:

  base class, extends :ref:`NXobject`, version 1.0

**Description**:

  Template of the state of the sample. This could include scanned variables that
  are associated with one of the data dimensions, e.g. the magnetic field, or
  logged data, e.g. monitored temperature vs elapsed time.

**Symbols**:

  symbolic array lengths to be coordinated between various fields

  **n_comp**: number of compositions

  **n_Temp**: number of temperatures

  **n_eField**: number of values in applied electric field

  **n_mField**: number of values in applied magnetic field

  **n_pField**: number of values in applied pressure field

  **n_sField**: number of values in applied stress field

**Groups cited**:
  :ref:`NXbeam`, :ref:`NXdata`, :ref:`NXenvironment`, :ref:`NXgeometry`, :ref:`NXlog`, :ref:`NXpositioner`

.. index:: NXgeometry (base class); used in base class, NXbeam (base class); used in base class, NXdata (base class); used in base class, NXlog (base class); used in base class, NXenvironment (base class); used in base class, NXpositioner (base class); used in base class

**Structure**:

  .. index:: name (data field)

  **name**: :ref:`NX_CHAR <NX_CHAR>`

    Descriptive name of sample

  .. index:: chemical_formula (data field)

  **chemical_formula**: :ref:`NX_CHAR <NX_CHAR>`

    The chemical formula specified using CIF conventions.
    Abbreviated version of CIF standard:

    * Only recognized element symbols may be used.
    * Each element symbol is followed by a 'count' number. A count of '1' may be omitted.
    * A space or parenthesis must separate each cluster of (element symbol + count).
    * Where a group of elements is enclosed in parentheses, the multiplier for the 
      group must follow the closing parentheses. That is, all element and group 
      multipliers are assumed to be printed as subscripted numbers.
    * Unless the elements are ordered in a manner that corresponds to their chemical 
      structure, the order of the elements within any group or moiety depends on 
      whether or not carbon is present.
    * If carbon is present, the order should be:

      - C, then H, then the other elements in alphabetical order of their symbol. 
      - If carbon is not present, the elements are listed purely in alphabetic order of their symbol.

    * This is the *Hill* system used by Chemical Abstracts.

  .. index:: temperature (data field)

  **temperature[n_Temp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_TEMPERATURE <NX_TEMPERATURE>`}

    Sample temperature. This could be a scanned variable

  .. index:: electric_field (data field)

  **electric_field[n_eField]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_VOLTAGE <NX_VOLTAGE>`}

    Applied electric field

    .. index:: direction (attribute)

    **@direction**: :ref:`NX_CHAR <NX_CHAR>`


      Any of these values: ``x`` | ``y`` | ``z``

  .. index:: magnetic_field (data field)

  **magnetic_field[n_mField]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    Applied magnetic field

    .. index:: direction (attribute)

    **@direction**: :ref:`NX_CHAR <NX_CHAR>`


      Any of these values: ``x`` | ``y`` | ``z``

  .. index:: stress_field (data field)

  **stress_field[n_sField]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    Applied external stress field

    .. index:: direction (attribute)

    **@direction**: :ref:`NX_CHAR <NX_CHAR>`


      Any of these values: ``x`` | ``y`` | ``z``

  .. index:: pressure (data field)

  **pressure[n_pField]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_PRESSURE <NX_PRESSURE>`}

    Applied pressure

  .. index:: changer_position (data field)

  **changer_position**: :ref:`NX_INT <NX_INT>` {units=\ :ref:`NX_UNITLESS <NX_UNITLESS>`}

    Sample changer position

  .. index:: unit_cell (data field)

  **unit_cell[n_comp, 6]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Unit cell parameters (lengths and angles)

  .. index:: unit_cell_volume (data field)

  **unit_cell_volume[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_VOLUME <NX_VOLUME>`}

    Volume of the unit cell

  .. index:: sample_orientation (data field)

  **sample_orientation[3]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967)

  .. index:: orientation_matrix (data field)

  **orientation_matrix[n_comp, 3, 3]**: :ref:`NX_FLOAT <NX_FLOAT>`

    Orientation matrix of single crystal sample.
    This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967)

  .. index:: mass (data field)

  **mass[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_MASS <NX_MASS>`}

    Mass of sample

  .. index:: density (data field)

  **density[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_MASS_DENSITY <NX_MASS_DENSITY>`}

    Density of sample

  .. index:: relative_molecular_mass (data field)

  **relative_molecular_mass[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_MASS <NX_MASS>`}

    Relative Molecular Mass of sample

  .. index:: type (data field)

  **type**: :ref:`NX_CHAR <NX_CHAR>`


    Any of these values:

      * ``sample``

      * ``sample+can``

      * ``can``

      * ``calibration sample``

      * ``normalisation sample``

      * ``simulated data``

      * ``none``

      * ``sample environment``


  .. index:: situation (data field)

  **situation**: :ref:`NX_CHAR <NX_CHAR>`

    The atmosphere will be one of the components, which is where 
    its details will be stored; the relevant components will be 
    indicated by the entry in the sample_component member.

    Any of these values:

      * ``air``

      * ``vacuum``

      * ``inert atmosphere``

      * ``oxidising atmosphere``

      * ``reducing atmosphere``

      * ``sealed can``

      * ``other``


  .. index:: description (data field)

  **description**: :ref:`NX_CHAR <NX_CHAR>`

    Description of the sample

  .. index:: preparation_date (data field)

  **preparation_date**: :ref:`NX_DATE_TIME <NX_DATE_TIME>`

    Date of preparation of the sample

  .. index:: component (data field)

  **component[n_comp]**: :ref:`NX_CHAR <NX_CHAR>`

    Details of the component of the sample and/or can

  .. index:: sample_component (data field)

  **sample_component[n_comp]**: :ref:`NX_CHAR <NX_CHAR>`

    Type of component

    Any of these values: ``sample`` | ``can`` | ``atmosphere`` | ``kit``

  .. index:: concentration (data field)

  **concentration[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_MASS_DENSITY <NX_MASS_DENSITY>`}

    Concentration of each component

  .. index:: volume_fraction (data field)

  **volume_fraction[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>`

    Volume fraction of each component

  .. index:: scattering_length_density (data field)

  **scattering_length_density[n_comp]**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_SCATTERING_LENGTH_DENSITY <NX_SCATTERING_LENGTH_DENSITY>`}

    Scattering length density of each component

  .. index:: unit_cell_class (data field)

  **unit_cell_class[n_comp]**: :ref:`NX_CHAR <NX_CHAR>`

    In case it is all we know and we want to record/document it

    Any of these values:

      * ``cubic``

      * ``tetragonal``

      * ``orthorhombic``

      * ``monoclinic``

      * ``triclinic``


  .. index:: unit_cell_group (data field)

  **unit_cell_group[n_comp]**: :ref:`NX_CHAR <NX_CHAR>`

    Crystallographic point or space group

  .. index:: path_length (data field)

  **path_length**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Path length through sample/can for simple case when 
    it does not vary with scattering direction

  .. index:: path_length_window (data field)

  **path_length_window**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Thickness of a beam entry/exit window on the can (mm) 
    - assumed same for entry and exit

  .. index:: thickness (data field)

  **thickness**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    sample thickness

  .. index:: external_DAC (data field)

  **external_DAC**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANY <NX_ANY>`}

    value sent to user's sample setup

  .. index:: short_title (data field)

  **short_title**: :ref:`NX_CHAR <NX_CHAR>`

    20 character fixed length sample description for legends

  .. index:: rotation_angle (data field)

  **rotation_angle**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_ANGLE <NX_ANGLE>`}

    Optional rotation angle for the case when the powder diagram has 
    been obtained through an omega-2theta scan like from a traditional 
    single detector powder diffractometer

  .. index:: x_translation (data field)

  **x_translation**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Translation of the sample along the X-direction of the laboratory coordinate system

  .. index:: distance (data field)

  **distance**: :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

    Translation of the sample along the Z-direction of the laboratory coordinate system

  **geometry**: :ref:`NXgeometry`

    The position and orientation of the center of mass of the sample

  **(beam)**: :ref:`NXbeam`

    Details of beam incident on sample - used to calculate sample/beam interaction point

  **transmission**: :ref:`NXdata`

    As a function of Wavelength

  **temperature_log**: :ref:`NXlog`

    temperature_log.value is a link to e.g. temperature_env.sensor1.value_log.value

  **temperature_env**: :ref:`NXenvironment`

    Additional sample temperature environment information

  **magnetic_field_log**: :ref:`NXlog`

    magnetic_field_log.value is a link to e.g. magnetic_field_env.sensor1.value_log.value

  **magnetic_field_env**: :ref:`NXenvironment`

    Additional sample magnetic environment information

  **external_ADC**: :ref:`NXlog`

    logged value (or logic state) read from user's setup

  **(positioner)**: :ref:`NXpositioner`

    Any positioner (motor, PZT, ...) used to locate the sample

**Source**:
  Automatically generated from https://github.com/nexusformat/definitions/blob/master/base_classes/NXsample.nxdl.xml