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

.. index::
    ! NXcxi_ptycho (contributed definition)
    ! cxi_ptycho (contributed definition)
    see: cxi_ptycho (contributed definition); NXcxi_ptycho

.. _NXcxi_ptycho:

============
NXcxi_ptycho
============

**Status**:

  contributed definition, extends :ref:`NXobject`

**Description**:

  Application definition for a ptychography experiment. This is compatible with CXI from version 1.6 (discussed with Filippe Maia) if this application definition
  is put at the top "entry" level. Above this a "cxi_version" field should be defined. The CXI format is name based, rather than class based, and so it is important
  to pay attention to the naming convention to be CXI compatible. There are duplications due to the format merger. These should be achieved by SoftLinks, 
  with hdf5 Virtual Dataset being used to restructure any data that needs to be remapped.

  An example here is that CXI expects the data to always to have shape (npts_x*npts_y, frame_size_x, frame_size_y). For nexus this is only true for arbitrary scan paths
  with raster format scans taking shape (npts_x, npts_y, frame_size_x, frame_size_y).

**Symbols**:

  These symbols will be used below to coordinate the shapes of the datasets.

  **npts_x**: The number of points in the x direction

  **npts_y**: Number of points in the y direction.

  **frame_size_x**: Number of detector pixels in x

  **frame_size_y**: Number of detector pixels in y

**Groups cited**:
  :ref:`NXbeam`, :ref:`NXcollection`, :ref:`NXdata`, :ref:`NXdetector`, :ref:`NXentry`, :ref:`NXinstrument`, :ref:`NXmonitor`, :ref:`NXsample`, :ref:`NXsource`, :ref:`NXtransformations`

.. index:: NXentry (base class); used in contributed definition, NXinstrument (base class); used in contributed definition, NXsource (base class); used in contributed definition, NXbeam (base class); used in contributed definition, NXdetector (base class); used in contributed definition, NXtransformations (base class); used in contributed definition, NXmonitor (base class); used in contributed definition, NXdata (base class); used in contributed definition, NXcollection (base class); used in contributed definition, NXsample (base class); used in contributed definition

**Structure**:

  **entry_1**: (required) :ref:`NXentry`


    .. index:: title (field)

    **title**: (required) :ref:`NX_CHAR <NX_CHAR>`


    .. index:: start_time (field)

    **start_time**: (optional) :ref:`NX_DATE_TIME <NX_DATE_TIME>`


    .. index:: end_time (field)

    **end_time**: (optional) :ref:`NX_DATE_TIME <NX_DATE_TIME>`


    .. index:: definition (field)

    **definition**: (required) :ref:`NX_CHAR <NX_CHAR>`

      Official NeXus NXDL schema to which this file conforms

      Obligatory value:  ``NXptycho``

    **instrument_1**: (required) :ref:`NXinstrument`


      **source_1**: (required) :ref:`NXsource`


        .. index:: name (field)

        **name**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: energy (field)

        **energy**: (required) :ref:`NX_FLOAT <NX_FLOAT>`

          This is the energy of the machine, not the beamline.

        .. index:: probe (field)

        **probe**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


        .. index:: type (field)

        **type**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


      **beam_1**: (required) :ref:`NXbeam`


        .. index:: energy (field)

        **energy**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: extent (field)

        **extent**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: incident_beam_divergence (field)

        **incident_beam_divergence**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: incident_beam_energy (field)

        **incident_beam_energy**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: incident_energy_spread (field)

        **incident_energy_spread**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


      **detector_1**: (required) :ref:`NXdetector`


        .. index:: axes (group attribute)

        **@axes**: (required) :ref:`NX_CHAR <NX_CHAR>`

          should have value "[, data]"

        .. index:: signal (group attribute)

        **@signal**: (required) :ref:`NX_CHAR <NX_CHAR>`

          should have value "data"

        .. index:: translation (field)

        **translation**: (required) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}

          This is an array of shape (npts_x*npts_y, 3) and can be a Virtual Dataset of x and y

          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


          .. index:: axes (field attribute)

          **@axes**: (required) :ref:`NX_CHAR <NX_CHAR>`

            this should take the value "translation:$slowaxisname:$fastaxisname"

          .. index:: interpretation (field attribute)

          **@interpretation**: (required) :ref:`NX_CHAR <NX_CHAR>`

            This should be "image"

        .. index:: data (field)

        **data[npts_x, npts_y, frame_size_x, frame_size_y]**: (required) :ref:`NX_INT <NX_INT>`


        .. index:: x_pixel_size (field)

        **x_pixel_size**: (required) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: y_pixel_size (field)

        **y_pixel_size**: (required) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: distance (field)

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

          The distance between the detector and the sample

          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: beam_center_x (field)

        **beam_center_x**: (required) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        .. index:: beam_center_y (field)

        **beam_center_y**: (required) :ref:`NX_FLOAT <NX_FLOAT>` {units=\ :ref:`NX_LENGTH <NX_LENGTH>`}


          .. index:: units (field attribute)

          **@units**: (required) :ref:`NX_CHAR <NX_CHAR>`


        **transformations**: (required) :ref:`NXtransformations`


          .. index:: vector (field)

          **vector**: (required) :ref:`NX_NUMBER <NX_NUMBER>`


        **data_1** --> /NXentry/NXinstrument/NXdetector/data

          This data must always have shape (npts_x*npts_y, frame_size_x, frame_size_y) regardless 
          of the scan pattern. Use hdf5 virtual dataset to achieve this.

      **(monitor)**: (required) :ref:`NXmonitor`


        .. index:: data (field)

        **data[npts_x, npts_y]**: (required) :ref:`NX_FLOAT <NX_FLOAT>`


  **(data)**: (required) :ref:`NXdata`


    .. index:: axes (group attribute)

    **@axes**: (required) :ref:`NX_CHAR <NX_CHAR>`

      This should be "[x,.]" for arbitrary scanning patterns, and "[x,.,.]" for raster

    .. index:: signal (group attribute)

    **@signal**: (required) :ref:`NX_CHAR <NX_CHAR>`

      This should be "data"

    .. index:: x_indices (field)

    **x_indices**: (required) :ref:`NX_CHAR <NX_CHAR>`


    .. index:: y_indices (field)

    **y_indices**: (required) :ref:`NX_CHAR <NX_CHAR>`


    **data** --> /NXentry/NXinstrument/NXdetector/data


    **x** --> /NXentry/NXsample/NXtransformations/x


    **y** --> /NXentry/NXsample/NXtransformations/y


  **data_1**: (required) :ref:`NXcollection`

    To ensure CXI compatibility the data in this group must always have shape that is
    (npts_x*npts_y, frame_size_x, frame_size_y). For nexus-style raster scans it is proposed that
    hdf5 virtual dataset is used.

    **data** --> /NXentry/NXinstrument/NXdetector/data


    **translation** --> /NXentry/NXinstrument/NXdetector/translation


  **sample_1**: (required) :ref:`NXsample`


    .. index:: name (field)

    **name**: (optional) :ref:`NX_CHAR <NX_CHAR>`


    .. index:: transformations (field)

    **transformations**: (required) NXtransformations

      This must contain two fields with the x and y motors that are linked via the 
      dependency tree according to the real-life motor layout dependency.
      For raster scans x and y will have shape (npts_x, npts_y)
      For arbitrary scans x and y will be (npts_x*npts_y,)
      An attribute with the units for each motor is required.

      .. index:: vector (field attribute)

      **@vector**: (required) :ref:`NX_NUMBER <NX_NUMBER>`


    **geometry_1**: (required) :ref:`NXcollection`


      **translation** --> /NXentry/NXinstrument/NXdetector/translation


**NXDL Source**:
  https://github.com/nexusformat/definitions/blob/master/contributed_definitions/NXcxi_ptycho.nxdl.xml