diff --git a/.github/nexus-fairmat-gen-docs.yml b/.github/nexus-fairmat-gen-docs.yml deleted file mode 100644 index 4d7e3813a4..0000000000 --- a/.github/nexus-fairmat-gen-docs.yml +++ /dev/null @@ -1,94 +0,0 @@ -name: Publish Sphinx Docs to GitHub Pages -on: [push] - -# see: https://sphinx-notes.github.io/pages/ -# see: https://github.com/marketplace/actions/sphinx-to-github-pages - -jobs: - - build: - runs-on: ubuntu-latest - - steps: - - name: Checkout - uses: actions/checkout@master - with: - fetch-depth: 0 # otherwise, you will fail to push refs to dest repo - - - name: Install build requirements - run: | - pip install -r requirements.txt - - name: Diagnostic - run: | - pip list - - name: Run the test suite - run: | - # stops publishing when known problems are found - python utils/test_suite.py - - name: Prepare for out-of-source Sphinx build - run: | - rm -rf ./build - mkdir ./build - python ./utils/build_preparation.py . ./build - - name: Diagnostic - run: | - ls -lAFGh - ls -lAFGh ./build - - name: Install LaTeX - run: | - sudo apt-get update -y && \ - sudo apt-get install -y \ - latexmk \ - texlive-latex-recommended \ - texlive-latex-extra \ - texlive-fonts-recommended - - name: Build impatient guide - run: | - make -C ./build/impatient-guide html latexpdf - ls -lAFGh ./build/impatient-guide/_build/latex/*.pdf - # Copy to documentation source directory - cp \ - ./build/impatient-guide/_build/latex/NXImpatient.pdf \ - ./build/manual/source/_static/ - - name: Build PDF of manual - run: | - # expect next make (PDF) to fail (thus exit 0) - # since nexus.ind not found first time - # extra option for "levels nested too deeply" error - ( \ - make latexpdf \ - LATEXOPTS="--interaction=nonstopmode" \ - -C build/manual \ - || exit 0 \ - ) - # make that missing file - makeindex build/manual/build/latex/nexus.idx - # build the PDF, still a failure will be noted - # but we can ignore it without problem - ( \ - make latexpdf \ - LATEXOPTS="--interaction=nonstopmode" \ - -C build/manual \ - || exit 0\ - ) - # Copy to documentation source directory - cp \ - ./build/manual/build/latex/nexus.pdf \ - ./build/manual/source/_static/NeXusManual.pdf - - name: Include other PDFs - run: | - wget https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf -O ./build/manual/source/_static/NeXusIntern.pdf - wget https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf -O ./build/manual/source/_static/NXtranslate.pdf - - name: Build (html) and Commit - uses: sphinx-notes/pages@master - with: - # path to conf.py directory - documentation_path: build/manual/source - - - name: Publish if refs/tags - # remove/comment next line to push right away - if: startsWith(github.ref, 'refs/tags') - uses: ad-m/github-push-action@master - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml old mode 100644 new mode 100755 index 34dc020d45..09bc967f55 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -3,10 +3,12 @@ name: CI on: push: branches: - - main # push commit to the main branch + - main + - fairmat # push commit to the fairmat branch pull_request: branches: - - main # pull request to the main branch + - main + - fairmat # pull request to the fairmat branch workflow_dispatch: # allow manual triggering inputs: deploy: @@ -14,6 +16,11 @@ on: type: boolean required: true default: false + upload: + description: 'Upload documentation (pdfs in _static/)' + type: boolean + required: true + default: false defaults: run: @@ -25,10 +32,11 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ['3.7', '3.8', '3.9', '3.10'] + python-version: ['3.8', '3.9', '3.10', '3.11'] max-parallel: 5 env: python_version: ${{ matrix.python-version }} + python_deploy_version: '3.8' # version to use for deployment steps: - name: Checkout Repository @@ -36,8 +44,13 @@ jobs: with: fetch-depth: 0 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + - name: Deploy Information - if: ${{ github.event.inputs.deploy && env.python_version == '3.7' }} + if: ${{ github.event.inputs.deploy && env.python_version == env.python_deploy_version }} run: | echo "The HTML NeXus User Manual will be pushed to" echo " https://github.com/nexusformat/definitions/tree/gh-pages" @@ -66,34 +79,39 @@ jobs: texlive-latex-recommended \ texlive-latex-extra \ texlive-fonts-recommended + tex --version - name: Generate build files + env: + GH_TOKEN: ${{ (env.python_version == env.python_deploy_version && (github.event.inputs.deploy || github.event.inputs.upload)) && secrets.GITHUB_TOKEN || 'NONE' }} run: | make prepare - - name: Build Impatient Guid + - name: Build Impatient Guide run: | make impatient-guide ls -lAFgh build/impatient-guide/build/html/index.html - ls -lAFgh build/impatient-guide/build/latex/NXImpatient.pdf + mkdir -p build/html + mv build/impatient-guide/build/html build/html/impatient - name: Build User Manual run: | make pdf make html ls -lAFgh build/manual/build/html/index.html - ls -lAFgh build/manual/build/latex/nexus.pdf + mkdir -p build/html + mv build/manual/build/html/* build/html - - name: Build and Commit the User Manual - if: ${{ github.event.inputs.deploy && env.python_version == '3.7' }} - uses: sphinx-notes/pages@master + - name: Deploy both the User Manual and the Impatient Guide + if: ${{ github.event.inputs.deploy && env.python_version == env.python_deploy_version }} + uses: JamesIves/github-pages-deploy-action@v4 with: - # path to the conf.py directory - documentation_path: build/manual/source + token: ${{ secrets.GITHUB_TOKEN }} + folder: build/html - - name: Deploy the User Manual - if: ${{ github.event.inputs.deploy && env.python_version == '3.7' }} - uses: ad-m/github-push-action@master + - name: Upload the User Manual and the Impatient Guide + if: ${{ github.event.inputs.upload && env.python_version == env.python_deploy_version }} + uses: actions/upload-artifact@v3 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - branch: gh-pages + name: nexus-definitions-docs + path: build/html diff --git a/.github/workflows/fairmat-build-pages.yaml b/.github/workflows/fairmat-build-pages.yaml new file mode 100644 index 0000000000..3335017b1c --- /dev/null +++ b/.github/workflows/fairmat-build-pages.yaml @@ -0,0 +1,49 @@ +name: GH pages fairmat proposal + +on: + push: + branches: [fairmat] + pull_request: + branches: [fairmat] + +jobs: + pages: + runs-on: ubuntu-20.04 + steps: + - name: Checkout Repository + uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: Set up Python 3.9 + uses: actions/setup-python@v4 + with: + python-version: "3.9" + - name: install dependencies + run: pip install -r requirements.txt + - name: Get branch name + id: branch-name + uses: tj-actions/branch-names@v7 + - name: test + run: make test + - name: prepare + run: make prepare + - name: html + run: make html + - name: Deploy + if: steps.branch-name.outputs.is_default == 'true' + uses: JamesIves/github-pages-deploy-action@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + folder: build/manual/build/html + branch: fairmat-docs + target-folder: docs + clean: false + - name: Deploy PR + if: steps.branch-name.outputs.is_default == 'false' + uses: JamesIves/github-pages-deploy-action@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + folder: build/manual/build/html + branch: fairmat-docs + target-folder: docs/${{ steps.branch-name.outputs.current_branch }} + clean: false \ No newline at end of file diff --git a/.github/workflows/fairmat-clean-pages.yaml b/.github/workflows/fairmat-clean-pages.yaml new file mode 100644 index 0000000000..c1cb6db0c5 --- /dev/null +++ b/.github/workflows/fairmat-clean-pages.yaml @@ -0,0 +1,27 @@ +name: GH pages cleanup + +on: + delete: + +jobs: + cleanup: + if: github.event.ref_type == 'branch' + runs-on: ubuntu-latest + steps: + - name: Checkout pages + uses: actions/checkout@v2 + with: + ref: fairmat-docs + persist-credentials: false + fetch-depth: 0 + - name: Remove branch directory + run: rm -rf docs/${{ github.event.ref }} + - name: Get current date + id: date + run: echo "::set-output name=date::$(date +'%Y-%m-%d')" + - name: Commit & Push changes + uses: actions-js/push@master + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + branch: fairmat-docs + message: Fairmat docs cleanup ${{ steps.date.outputs.date }} \ No newline at end of file diff --git a/.github/workflows/fairmat-nxdl-yaml-consistency.yaml b/.github/workflows/fairmat-nxdl-yaml-consistency.yaml new file mode 100644 index 0000000000..64a78fc19e --- /dev/null +++ b/.github/workflows/fairmat-nxdl-yaml-consistency.yaml @@ -0,0 +1,29 @@ +name: Check nxdl/yaml consistency + +on: + push: + branches: [fairmat] + pull_request: + branches: [fairmat] + +jobs: + check_nxdl: + runs-on: ubuntu-latest + steps: + - name: Set up Python 3.9 + uses: actions/setup-python@v4 + with: + python-version: "3.9" + - name: Checkout Repository + uses: actions/checkout@v2 + with: + fetch-depth: 0 + - name: install dependencies + run: pip install -r requirements.txt + - name: make nxdls + run: make nxdl + - uses: CatChen/check-git-status-action@v1 + with: + fail-if-not-clean: true + request-changes-if-not-clean: false + push-if-not-clean: false \ No newline at end of file diff --git a/.gitignore b/.gitignore index ff21c1627c..3fd234f70f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ # Hidden files .* +!.github # Python byte / compiled / optimized *.py[cod] @@ -9,6 +10,24 @@ __pycache__/ build/ makelog.txt -# Unknown -/python/ -__github_creds__.txt +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +*_parsed.yaml \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000000..20485f6286 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,4 @@ +recursive-include applications/ *.nxdl.xml +recursive-include contributed_definitions/ *.nxdl.xml +recursive-include base_classes/ *.nxdl.xml +include ./ *.xsd \ No newline at end of file diff --git a/Makefile b/Makefile index ae556d7339..78f3af7719 100644 --- a/Makefile +++ b/Makefile @@ -5,9 +5,18 @@ PYTHON = python3 SPHINX = sphinx-build -BUILD_DIR = "build" +BUILD_DIR = build +BASE_CLASS_DIR = base_classes +CONTRIB_DIR = contributed_definitions +APPDEF_DIR = applications +NYAML_SUBDIR = nyaml -.PHONY: help install style autoformat test clean prepare html pdf impatient-guide all local +YBC_NXDL_TARGETS = $(patsubst %.yaml,%.nxdl.xml,$(subst /nyaml/,/, $(wildcard $(BASE_CLASS_DIR)/nyaml/*.yaml))) +YCONTRIB_NXDL_TARGETS = $(patsubst %.yaml,%.nxdl.xml,$(subst /nyaml/,/, $(wildcard $(CONTRIB_DIR)/nyaml/*.yaml))) +YAPPDEF_NXDL_TARGETS = $(patsubst %.yaml,%.nxdl.xml,$(subst /nyaml/,/, $(wildcard $(APPDEF_DIR)/nyaml/*.yaml))) + + +.PHONY: help install style autoformat test clean prepare html pdf impatient-guide all local nxdl nyaml help :: @echo "" @@ -19,12 +28,15 @@ help :: @echo "make autoformat Format all files to the coding style conventions." @echo "make test Run NXDL syntax and documentation tests." @echo "make clean Remove all build files." + @echo "make clean-nyaml Remove all nyaml files." @echo "make prepare (Re)create all build files." @echo "make html Build HTML version of manual. Requires prepare first." @echo "make pdf Build PDF version of manual. Requires prepare first." @echo "make impatient-guide Build html & PDF versions of the Guide for the Impatient. Requires prepare first." @echo "make all Builds complete web site for the manual (in build directory)." @echo "make local (Developer use) Test, prepare and build the HTML manual." + @echo "make nxdl Build NXDL files from NYAML files in nyaml subdirectories." + @echo "make nyaml Build NYAML files to nyaml subdirectories from NXDL files." @echo "" @echo "Note: All builds of the manual will occur in the 'build/' directory." @echo " For a complete build, run 'make all' in the root directory." @@ -50,13 +62,18 @@ test :: clean :: $(RM) -rf $(BUILD_DIR) +clean-nyaml :: + $(RM) -rf $(BASE_CLASS_DIR)/$(NYAML_SUBDIR) + $(RM) -rf $(APPDEF_DIR)/$(NYAML_SUBDIR) + $(RM) -rf $(CONTRIB_DIR)/$(NYAML_SUBDIR) + prepare :: $(PYTHON) -m dev_tools manual --prepare --build-root $(BUILD_DIR) $(PYTHON) -m dev_tools impatient --prepare --build-root $(BUILD_DIR) pdf :: $(SPHINX) -M latexpdf $(BUILD_DIR)/manual/source/ $(BUILD_DIR)/manual/build - cp $(BUILD_DIR)/manual/build/latex/nexus.pdf $(BUILD_DIR)/manual/source/_static/NeXusManual.pdf + cp $(BUILD_DIR)/manual/build/latex/nexus-fairmat.pdf $(BUILD_DIR)/manual/source/_static/NeXusManual.pdf html :: $(SPHINX) -b html -W $(BUILD_DIR)/manual/source/ $(BUILD_DIR)/manual/build/html @@ -81,7 +98,21 @@ all :: @echo "HTML built: `ls -lAFgh $(BUILD_DIR)/impatient-guide/build/html/index.html`" @echo "PDF built: `ls -lAFgh $(BUILD_DIR)/impatient-guide/build/latex/NXImpatient.pdf`" @echo "HTML built: `ls -lAFgh $(BUILD_DIR)/manual/build/html/index.html`" - @echo "PDF built: `ls -lAFgh $(BUILD_DIR)/manual/build/latex/nexus.pdf`" + @echo "PDF built: `ls -lAFgh $(BUILD_DIR)/manual/build/latex/nexus-fairmat.pdf`" + +$(BASE_CLASS_DIR)/%.nxdl.xml : $(BASE_CLASS_DIR)/$(NYAML_SUBDIR)/%.yaml + nyaml2nxdl $< --output-file $@ + +$(CONTRIB_DIR)/%.nxdl.xml : $(CONTRIB_DIR)/$(NYAML_SUBDIR)/%.yaml + nyaml2nxdl $< --output-file $@ + +$(APPDEF_DIR)/%.nxdl.xml : $(APPDEF_DIR)/$(NYAML_SUBDIR)/%.yaml + nyaml2nxdl $< --output-file $@ + +nxdl: $(YBC_NXDL_TARGETS) $(YCONTRIB_NXDL_TARGETS) $(YAPPDEF_NXDL_TARGETS) + +nyaml: + $(MAKE) -f nyaml.mk # NeXus - Neutron and X-ray Common Data Format diff --git a/README.md b/README.md old mode 100644 new mode 100755 index 6bb56e3ea5..6199e223ee --- a/README.md +++ b/README.md @@ -7,6 +7,10 @@ ## NeXus definition developers +Note if this package was not properly installed using pip, it has to be first done by + + pip install -e . + After making a change to the NeXus class definitions there are two important checks to be made before commiting the change: @@ -25,6 +29,43 @@ Open the HTML manual in a web brower for visual verification firefox build/manual/build/html/index.html +Convenient editing of definitions is available in nyaml format. For this, definitions need to be converted first from xml to yaml format by the command + + make nyaml + +After editing the definitions in nyaml format in the nyaml subdirectories, the following command can be used to update the definitions in nxdl.xml format: + + make nxdl + +> [!WARNING] +> Please be aware that your nyaml files might be out of sync with the nxdl files when you update your repo. So it's best practice to stash your changes to the nyaml files and regenerate the files with `make nyaml` before adding any changes. + +### HTML pages with contributor information + +To build the html pages that contains contributor information on the sidebar set a github access token to an environment variable called GH_TOKEN. + +Note: If set this will increase the build time of the documentation by approximately a factor of 4. + + setenv GH_TOKEN + +### Working with nyaml files + +There exists a simplified format of nxdl, which is called nyaml. +There is a [tool](https://github.com/FAIRmat-NFDI/nyaml) (`nyaml2nxdl`) available to convert between nxdl and nyaml. +This tool is already installed when you installed the requirements for this repository and it is conveniently available from the make command. + +You can build nyaml files for all nxdl files with invoking + + make nyaml + +which will created `.yaml` files in a subfolder called `nyaml` in the respective directory. + +From this you can do your changes and create nxdl files with + + make nxdl + +from the yaml files. + ## Repository content These are the components that define the structure of NeXus data files @@ -49,4 +90,4 @@ package/ | directory for packaging this content utils/ | various tools used in the definitions tree www/ | launch (home) page of NeXus WWW site xslt/ | various XML stylesheet transformations -dev_tools/ | developer tools for testing and building \ No newline at end of file +dev_tools/ | developer tools for testing and building diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index 0c71dab11f..3c23badbb7 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -852,7 +852,15 @@ + minOccurs="0"> + + This group is intended for use cases that do not fit the + :ref:`incident_wavelength </NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength-field>` + and + :ref:`incident_wavelength_weights </NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength_weights-field>` + fields above, perhaps for example a 2D spectrometer. + + diff --git a/applications/nyaml/NXarchive.yaml b/applications/nyaml/NXarchive.yaml new file mode 100644 index 0000000000..44246f4a25 --- /dev/null +++ b/applications/nyaml/NXarchive.yaml @@ -0,0 +1,281 @@ +category: application +doc: | + This is a definition for data to be archived by ICAT (http://www.icatproject.org/). + + .. text from the icatproject.org site + + the database (with supporting software) that provides an + interface to all ISIS experimental data and will provide + a mechanism to link all aspects of ISIS research from + proposal through to publication. +type: group +NXarchive(NXobject): + (NXentry)entry: + \@index: + title: + experiment_identifier(NX_CHAR): + doc: | + unique identifier for the experiment + experiment_description(NX_CHAR): + doc: | + Brief description of the experiment and its objectives + collection_identifier(NX_CHAR): + doc: | + ID of user or DAQ define group of data files + collection_description(NX_CHAR): + doc: | + Brief summary of the collection, including grouping criteria + entry_identifier(NX_CHAR): + doc: | + unique identifier for this measurement as provided by the facility + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + duration(NX_FLOAT): + unit: NX_TIME + doc: | + TODO: needs documentation + collection_time(NX_FLOAT): + unit: NX_TIME + doc: | + TODO: needs documentation + run_cycle(NX_CHAR): + doc: | + TODO: needs documentation + revision(NX_CHAR): + doc: | + revision ID of this file, may be after recalibration, reprocessing etc. + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXarchive] + program(NX_CHAR): + doc: | + The program and version used for generating this file + \@version: + release_date(NX_CHAR): + unit: NX_TIME + doc: | + when this file is to be released into PD + (NXuser)user: + name(NX_CHAR): + role(NX_CHAR): + doc: | + role of the user + facility_user_id(NX_CHAR): + doc: | + ID of the user in the facility burocracy database + (NXinstrument)instrument: + (NXsource): + type(NX_CHAR): + + # TODO: suggest changing from enumeration to suggested list + enumeration: [Spallation Neutron Source, Pulsed Reactor Neutron Source, Reactor Neutron Source, Synchrotron X-Ray Source, Pulsed Muon Source, Rotating Anode X-Ray, Fixed Tube X-Ray] + name: + probe: + enumeration: [neutron, x-ray, electron] + name(NX_CHAR): + description(NX_CHAR): + doc: | + Brief description of the instrument + (NXsample)sample: + name: + doc: | + Descriptive name of sample + sample_id(NX_CHAR): + doc: | + Unique database id of the sample + description(NX_CHAR): + type(NX_CHAR): + enumeration: [sample, sample+can, calibration sample, normalisation sample, simulated data, none, sample_environment] + chemical_formula(NX_CHAR): + doc: | + Chemical formula formatted according to CIF conventions + preparation_date(NX_CHAR): + unit: NX_TIME + situation(NX_CHAR): + doc: | + Description of the environment the sample is in: + air, vacuum, oxidizing atmosphere, dehydrated, etc. + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + magnetic_field(NX_FLOAT): + unit: NX_CURRENT + electric_field(NX_FLOAT): + unit: NX_VOLTAGE + stress_field(NX_FLOAT): + unit: NX_UNITLESS + pressure(NX_FLOAT): + unit: NX_PRESSURE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e5a85aff26bd71392bbe9cc8482e9067d971b4f1af39884f60db7dc0adfe811c +# +# +# +# +# +# This is a definition for data to be archived by ICAT (http://www.icatproject.org/). +# +# .. text from the icatproject.org site +# +# the database (with supporting software) that provides an +# interface to all ISIS experimental data and will provide +# a mechanism to link all aspects of ISIS research from +# proposal through to publication. +# +# +# +# +# +# unique identifier for the experiment +# +# +# Brief description of the experiment and its objectives +# +# +# ID of user or DAQ define group of data files +# +# +# Brief summary of the collection, including grouping criteria +# +# +# unique identifier for this measurement as provided by the facility +# +# +# +# +# TODO: needs documentation +# +# +# TODO: needs documentation +# +# +# TODO: needs documentation +# +# +# revision ID of this file, may be after recalibration, reprocessing etc. +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# The program and version used for generating this file +# +# +# when this file is to be released into PD +# +# +# +# role of the user +# +# ID of the user in the facility burocracy database +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Brief description of the instrument +# +# +# +# +# Descriptive name of sample +# +# +# Unique database id of the sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Chemical formula formatted according to CIF conventions +# +# +# +# +# Description of the environment the sample is in: +# air, vacuum, oxidizing atmosphere, dehydrated, etc. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXarpes.yaml b/applications/nyaml/NXarpes.yaml new file mode 100644 index 0000000000..746d91696f --- /dev/null +++ b/applications/nyaml/NXarpes.yaml @@ -0,0 +1,226 @@ +category: application +doc: | + This is an application definition for angular resolved photo electron spectroscopy. + + It has been drawn up with hemispherical electron analysers in mind. +type: group +NXarpes(NXobject): + (NXentry): + \@entry: + doc: | + NeXus convention is to use "entry1", "entry2", ... + for analysis software to locate each entry. + title(NX_CHAR): + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + enumeration: [NXarpes] + (NXinstrument): + (NXsource): + type(NX_CHAR): + name(NX_CHAR): + probe: + enumeration: [x-ray] + (NXmonochromator)monochromator: + energy(NX_NUMBER): + unit: NX_ENERGY + (NXdetector)analyser: + data(NX_NUMBER): + lens_mode(NX_CHAR): + doc: | + setting for the electron analyser lens + acquisition_mode: + enumeration: [swept, fixed] + entrance_slit_shape: + enumeration: [curved, straight] + entrance_slit_setting(NX_NUMBER): + unit: NX_ANY + doc: | + dial setting of the entrance slit + entrance_slit_size(NX_NUMBER): + unit: NX_LENGTH + doc: | + size of the entrance slit + pass_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + energy of the electrons on the mean path of the analyser + time_per_channel(NX_NUMBER): + unit: NX_TIME + doc: | + todo: define more clearly + angles(NX_NUMBER): + unit: NX_ANGLE + doc: | + Angular axis of the analyser data + which dimension the axis applies to is defined + using the normal NXdata methods. + energies(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis of the analyser data + which dimension the axis applies to is defined + using the normal NXdata methods. + sensor_size(NX_INT): + doc: | + number of raw active elements in each dimension + dimensions: + rank: 1 + dim: [[1, 2]] + region_origin(NX_INT): + doc: | + origin of rectangular region selected for readout + dimensions: + rank: 1 + dim: [[1, 2]] + region_size(NX_INT): + doc: | + size of rectangular region selected for readout + dimensions: + rank: 1 + dim: [[1, 2]] + (NXsample): + name(NX_CHAR): + doc: | + Descriptive name of sample + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + (NXdata): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 31232b8eac61f1e491926e74795efc8930591197ca40ea19d78788a866e7c6bf +# +# +# +# +# +# This is an application definition for angular resolved photo electron spectroscopy. +# +# It has been drawn up with hemispherical electron analysers in mind. +# +# +# +# +# NeXus convention is to use "entry1", "entry2", ... +# for analysis software to locate each entry. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# setting for the electron analyser lens +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# dial setting of the entrance slit +# +# +# size of the entrance slit +# +# +# energy of the electrons on the mean path of the analyser +# +# +# todo: define more clearly +# +# +# +# Angular axis of the analyser data +# which dimension the axis applies to is defined +# using the normal NXdata methods. +# +# +# +# +# Energy axis of the analyser data +# which dimension the axis applies to is defined +# using the normal NXdata methods. +# +# +# +# number of raw active elements in each dimension +# +# +# +# +# +# origin of rectangular region selected for readout +# +# +# +# +# +# size of rectangular region selected for readout +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# diff --git a/applications/nyaml/NXcanSAS.yaml b/applications/nyaml/NXcanSAS.yaml new file mode 100644 index 0000000000..27192a0ea4 --- /dev/null +++ b/applications/nyaml/NXcanSAS.yaml @@ -0,0 +1,2422 @@ +category: application +doc: | + Implementation of the canSAS standard to store reduced small-angle scattering data of any dimension. + + .. index:: canSAS + + For more details, see: + + * http://www.cansas.org/ + * http://www.cansas.org/formats/canSAS1d/1.1/doc/ + * http://cansas-org.github.io/canSAS2012/ + * https://github.com/canSAS-org/NXcanSAS_examples + + The minimum requirements for *reduced* small-angle scattering data + as described by canSAS are summarized in the following figure: + + .. _canSAS_2012_minimum: + + .. figure:: canSAS/2012-minimum.png + :width: 60% + + The minimum requirements for *reduced* small-angle scattering data. + (:download:`full image `) + See :ref:`below ` for the minimum required + information for a NeXus data file + written to the NXcanSAS specification. + + .. rubric:: Implementation of canSAS standard in NeXus + + This application definition is an implementation of the canSAS + standard for storing both one-dimensional and multi-dimensional + *reduced* small-angle scattering data. + + * NXcanSAS is for reduced SAS data and metadata to be stored together in one file. + * *Reduced* SAS data consists of :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)` + * External file links are not to be used for the reduced data. + * A good practice/practise is, at least, to include a reference to how the data was acquired and processed. Yet this is not a requirement. + * There is no need for NXcanSAS to refer to any raw data. + + The canSAS data format has a structure similar to NeXus, not identical. + To allow canSAS data to be expressed in NeXus, yet identifiable + by the canSAS standard, an additional group attribute ``canSAS_class`` + was introduced. Here is the mapping of some common groups. + + =============== ============ ========================== + group (*) NX_class canSAS_class + =============== ============ ========================== + sasentry NXentry SASentry + sasdata NXdata SASdata + sasdetector NXdetector SASdetector + sasinstrument NXinstrument SASinstrument + sasnote NXnote SASnote + sasprocess NXprocess SASprocess + sasprocessnote NXcollection SASprocessnote + sastransmission NXdata SAStransmission_spectrum + sassample NXsample SASsample + sassource NXsource SASsource + =============== ============ ========================== + + (*) The name of each group is a suggestion, + not a fixed requirement and is chosen as fits each data file. + See the section on defining + :ref:`NXDL group and field names `. + + Refer to the NeXus Coordinate System drawing (:ref:`Design-CoordinateSystem`) + for choice and direction of :math:`x`, :math:`y`, and :math:`z` axes. + + .. _NXcanSAS_minimum: + + .. rubric:: The minimum required information for a NeXus data file + written to the NXcanSAS specification. + + .. literalinclude:: canSAS/minimum-required.txt + :tab-width: 4 + :linenos: + :language: text + +# NOTE: +# This NXDL refers to several image files (.jpg, .png) in its documentation. +# All such related resources are stored in the related subdirectory: ./canSAS/ +# In general, for an NXDL file: NXsomenxdl.nxdl.xml +# all related resources should be stored in subdirectory: ./somenxdl/ +type: group +NXcanSAS(NXobject): + (NXentry): + \@default: + exists: optional + doc: | + .. index:: plotting + + Declares which :ref:`NXdata` group + contains the data to be shown by default. + It is needed to resolve ambiguity when more than one :ref:`NXdata` group exists. + The value is the name of the default :ref:`NXdata` group. + Usually, this will be the name of the first *SASdata* group. + doc: | + .. index:: NXcanSAS (applications); SASentry + + Place the canSAS ``SASentry`` group as a child of a NeXus ``NXentry`` group + (when data from multiple techniques are being stored) + or as a replacement for the ``NXentry`` group. + + Note: It is required for all numerical objects to provide + a *units* attribute that describes the engineering units. + Use the Unidata UDunits [#]_ specification + as this is compatible with various community standards. + + .. [#] The UDunits specification also includes instructions for derived units. + \@canSAS_class: + doc: | + Official canSAS group: **SASentry** + enumeration: [SASentry] + \@version: + doc: | + Describes the version of the canSAS standard used to write this data. + This must be a text (not numerical) representation. Such as:: + + @version="1.1" + enumeration: [1.1] + definition: + doc: | + Official NeXus NXDL schema to which this subentry conforms. + enumeration: [NXcanSAS] + + # ============================ + # SASdata + # ============================ + (NXdata): + doc: | + A *SASData* group contains a single reduced small-angle scattering data set + that can be represented as :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)`. + + *Q* can be either a vector (:math:`\vec{Q}`) or a vector magnitude (:math:`|\vec{Q}|`) + + The name of each *SASdata* group must be unique within a SASentry group. + Suggest using names such as ``sasdata01``. + + NOTE: For the first *SASdata* group, be sure to write the chosen name + into the `SASentry/@default` attribute, as in:: + + SASentry/@default="sasdata01" + + A *SASdata* group has several attributes: + + * I_axes + * Q_indices + * Mask_indices + + To indicate the dependency relationships of other varied parameters, + use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices`` + or ``@Pressure_indices``). + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASdata` + enumeration: [SASdata] + + # attributes, see: http://www.cansas.org/formats/canSAS2012/1.0/doc/framework.html#terms + \@signal: + type: NX_CHAR + doc: | + Name of the default data field. + enumeration: + I: + doc: | + For canSAS **SASdata**, this is always "I". + \@I_axes: + doc: | + String array that defines the independent data fields used in + the default plot for all of the dimensions of the *signal* field + (the *signal* field is the field in this group that is named by + the ``signal`` attribute of this group). + One entry is provided for every dimension of the ``I`` data object. + Such as:: + + @I_axes="Temperature", "Time", "Pressure", "Q", "Q" + + Since there are five items in the list, the intensity field of this example + ``I`` must be a five-dimensional array (rank=5). + \@Q_indices: + type: NX_INT + doc: | + Integer or integer array that describes which indices + (of the :math:`I` data object) are used to + reference the ``Q`` data object. The items in this array + use zero-based indexing. Such as:: + + @Q_indices=1,3,4 + + which indicates that ``Q`` requires three indices + from the :math:`I` data object: one for time and + two for Q position. Thus, in this example, the + ``Q`` data is time-dependent: :math:`\vec{Q}(t)`. + \@mask: + type: NX_CHAR + doc: | + Name of the data mask field. + + .. see: https://github.com/nexusformat/definitions/issues/533 + + The data *mask* must have the same shape as the *data* field. + Positions in the mask correspond to positions in the *data* field. + The value of the mask field may be either a boolean array + where ``false`` means *no mask* and ``true`` means *mask* + or a more descriptive array as as defined in :ref:`NXdetector`. + \@Mask_indices: + exists: optional + doc: | + Integer or integer array that describes which indices + (of the :math:`I` data object) are used to + reference the ``Mask`` data object. The items in this + array use zero-based indexing. Such as:: + + @Mask_indices=3,4 + + which indicates that Q requires two indices + from the :math:`I` data object for Q position. + \@timestamp: + type: NX_DATE_TIME + exists: optional + doc: | + ISO-8601 time [#iso8601]_ + Q(NX_NUMBER): + unit: NX_PER_LENGTH + + # http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of + doc: | + .. index:: NXcanSAS (applications); Q + + Array of :math:`Q` data to accompany :math:`I`. + + .. figure:: canSAS/Q-geometry.jpg + :width: 60% + + The :math:`\vec{Q}` geometry. + (:download:`full image `) + + :math:`Q` may be represented as either + the three-dimensional scattering vector :math:`\vec{Q}` + or the magnitude of the scattering vector, :math:`|\vec{Q}|`. + + .. math:: |\vec{Q}| = (4\pi/\lambda) sin(\theta) + + When we write :math:`Q`, we may refer to either or both of + :math:`|\vec{Q}|` + or :math:`\vec{Q}`, depending on the context. + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`Q` and related terms. + + Data expressed in other units will generate + a warning from validation software and may not + be processed by some analysis software packages. + enumeration: + 1/m: + 1/nm: + doc: | + preferred + 1/angstrom: + \@uncertainties: + exists: optional + doc: | + (optional: for numerical arrays) + + Names the dataset (in this SASdata group) that provides the + uncertainty to be used for data analysis. + The name of the dataset containing the :math:`Q` uncertainty + is flexible. The name must be unique in the *SASdata* group. + + .. comment + see: https://github.com/canSAS-org/canSAS2012/issues/7 + + Such as:: + + @uncertainties="Q_uncertainties" + + The *uncertainties* field will have the same *shape* (dimensions) + as the Q field. + + These values are the estimates of uncertainty of each Q. By default, + this will be interpreted to be the estimated standard deviation. + In special cases, when a standard deviation cannot possibly be used, + its value can specify another measure of distribution width. + + There may also be a subdirectory (optional) with constituent + components. + + .. note:: To report distribution in reported :math:`Q` values, + use the ``@resolutions`` attribute. It is possible for both + ``@resolutions`` and ``uncertainties`` to be reported. + \@resolutions: + type: NX_CHAR + exists: optional + doc: | + .. index:: NXcanSAS (applications); resolutions + + (optional: for numerical arrays) + + Names the dataset (in this SASdata group) containing the :math:`Q` resolution. + The name of the dataset containing the :math:`Q` resolution + is flexible. The name must be unique in the *SASdata* group. + + .. comment + see: https://github.com/canSAS-org/canSAS2012/issues/7 + + The *resolutions* field will have the same *shape* (dimensions) + as the Q field. + + Generally, this is the principal resolution of each :math:`Q`. + Names the data object (in this SASdata group) that provides the + :math:`Q` resolution to be used for data analysis. Such as:: + + @resolutions="Qdev" + + To specify two-dimensional resolution for slit-smearing geometry, + such as (*dQw*, *dQl*), use a string array, such as:: + + @resolutions="dQw", "dQl" + + There may also be a subdirectory (optional) with constituent + components. + + This pattern will demonstrate how to introduce further as-yet + unanticipated terms related to the data. + + .. comment + see: https://github.com/nexusformat/definitions/issues/492#issuecomment-262813907 + + By default, the values of the resolutions data object are assumed to be + one standard deviation of any function used to approximate the + resolution function. This equates to the width of the gaussian + distribution if a Gaussian is chosen. See the ``@resolutions_description`` + attribute. + + .. note:: To report uncertainty in reported :math:`Q` values, + use the ``@uncertainties`` attribute. It is possible for both + ``@resolutions`` and ``uncertainties`` to be reported. + \@resolutions_description: + type: NX_CHAR + exists: optional + doc: | + (optional) + Generally, this describes the :math:`Q` ``@resolutions`` data object. + By default, the value is assumed to be "Gaussian". These are + suggestions: + + * Gaussian + * Lorentzian + * Square : + note that the full width of the square would be ~2.9 times + the standard deviation specified in the vector + * Triangular + * Sawtooth-outward : vertical edge pointing to larger Q + * Sawtooth-inward vertical edge pointing to smaller Q + * Bin : range of values contributing + (for example, when 2-D detector data have been reduced + to a 1-D :math:`I(|Q|)` dataset) + + For other meanings, it may be necessary to provide further details + such as the function used to assess the resolution. + In such cases, use additional datasets or a :ref:`NXnote` subgroup + to include that detail. + I(NX_NUMBER): + + # http://www.cansas.org/formats/canSAS2012/1.0/doc/basics.html#definition-of-intensity + doc: | + .. index:: NXcanSAS (applications); I + + Array of intensity (:math:`I`) data. + + The intensity may be represented in one of these forms: + + **absolute units**: :math:`d\Sigma/d\Omega(Q)` + differential cross-section + per unit volume per unit solid angle (such as: 1/cm/sr or 1/m/sr) + + **absolute units**: :math:`d\sigma/d\Omega(Q)` + differential cross-section + per unit atom per unit solid angle (such as: cm^2 or m^2) + + **arbitrary units**: :math:`I(Q)` + usually a ratio of two detectors + but units are meaningless (such as: a.u. or counts) + + This presents a few problems + for analysis software to sort out when reading the data. + Fortunately, it is possible to analyze the *units* to determine which type of + intensity is being reported and make choices at the time the file is read. But this is + an area for consideration and possible improvement. + + One problem arises with software that automatically converts data into some canonical + units used by that software. The software should not convert units between these different + types of intensity indiscriminately. + + A second problem is that when arbitrary units are used, then the set of possible + analytical results is restricted. With such units, no meaningful volume fraction + or number density can be determined directly from :math:`I(Q)`. + + In some cases, it is possible to apply a factor to convert the arbitrary + units to an absolute scale. This should be considered as a possibility + of the analysis process. + + Where this documentation says *typical units*, it is possible that small-angle + data may be presented in other units and still be consistent with NeXus. + See the :ref:`design-units` section. + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`I` and intensity-related terms. + + Data expressed in other units (or missing a ``@units`` attribute) + will be treated as ``arbitrary`` by some software packages. + + For software using the UDUNITS-2 library, ``arbitrary`` will be + changed to ``unknown`` for handling with that library. + enumeration: + 1/m: + doc: | + includes m2/m3 and 1/m/sr + 1/cm: + doc: | + includes cm2/cm3 and 1/cm/sr + m2/g: + cm2/g: + arbitrary: + \@uncertainties: + exists: optional + doc: | + (optional: for numerical arrays) + + Names the dataset (in this SASdata group) that provides the + uncertainty of :math:`I` to be used for data analysis. + The name of the dataset containing the :math:`I` uncertainty + is flexible. The name must be unique in the *SASdata* group. + + .. comment + see: https://github.com/canSAS-org/canSAS2012/issues/7 + + Generally, this is the estimate of the uncertainty of each :math:`I`. + Typically the estimated standard deviation. + + *Idev* is the canonical name from the 1D standard. + The NXcanSAS standard allows for the name to be described using this attribute. + Such as:: + + @uncertainties="Idev" + \@scaling_factor: + exists: optional + doc: | + (optional) + Names the field (a.k.a. dataset) that contains a factor + to multiply ``I``. By default, this value is unity. + Should an uncertainty be associated with the scaling factor + field, the field containing that uncertainty would be + designated via the ``uncertainties`` attribute. + Such as:: + + I : NX_NUMBER + @uncertainties="Idev" : NX_CHAR + @scaling_factor="I_scaling" : NX_CHAR + Idev : NX_NUMBER + I_scaling : NX_NUMBER + @uncertainties="I_scaling_dev" : NX_CHAR + I_scaling_dev : NX_NUMBER + + The exact names for ``I_scaling`` and ``I_scaling_dev`` are not + defined by NXcanSAS. The user has the flexibility to use names + different than those shown in this example. + Idev(NX_NUMBER): + exists: ['min', '0'] + doc: | + .. index:: NXcanSAS (applications); Idev + + Estimated **uncertainty** (usually standard deviation) + in :math:`I`. Must have the same units as :math:`I`. + + When present, the name of this field is also + recorded in the *uncertainties* attribute of *I*, as in:: + + I/@uncertainties="Idev" + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`I` and intensity-related terms. + + Data expressed in other units (or missing a ``@units`` attribute) + will generate a warning from any validation process + and will be treated as ``arbitrary`` by some analysis software packages. + + For software using the UDUNITS-2 library, ``arbitrary`` will be + changed to ``unknown`` for handling with that library. + enumeration: + 1/m: + doc: | + includes m2/m3 and 1/m/sr + 1/cm: + doc: | + includes cm2/cm3 and 1/cm/sr + m2/g: + cm2/g: + arbitrary: + Qdev(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + .. index:: NXcanSAS (applications); Qdev + + Estimated :math:`Q` **resolution** (usually standard deviation). + Must have the same units as :math:`Q`. + + When present, the name of this field is also + recorded in the *resolutions* attribute of *Q*, + as in:: + + Q/@resolutions="Qdev" + + or:: + + Q/@resolutions="dQw", "dQl" + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`Q` and related terms. + + Data expressed in other units may not be processed by some + software packages. + enumeration: + 1/m: + 1/nm: + doc: | + preferred + 1/angstrom: + dQw(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + .. index:: NXcanSAS (applications); dQw + + :math:`Q` **resolution** along the axis of scanning + (the high-resolution *slit width* direction). + Useful for defining resolution data from + slit-smearing instruments such as Bonse-Hart geometry. + Must have the same units as :math:`Q`. + + When present, the name of this field is also + recorded in the *resolutions* attribute of *Q*, + as in:: + + Q/@resolutions="dQw", "dQl" + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`Q` and related terms. + + Data expressed in other units may not be processed by some + software packages. + enumeration: + 1/m: + 1/nm: + doc: | + preferred + 1/angstrom: + dQl(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + .. index:: NXcanSAS (applications); dQl + + :math:`Q` **resolution** perpendicular to the axis of scanning + (the low-resolution *slit length* direction). + Useful for defining resolution data from + slit-smearing instruments such as Bonse-Hart geometry. + Must have the same units as :math:`Q`. + + When present, the name of this field is also + recorded in the *resolutions* attribute of *Q*, + as in:: + + Q/@resolutions="dQw", "dQl" + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`Q` and related terms. + + Data expressed in other units may not be processed by some + software packages. + enumeration: + 1/m: + 1/nm: + doc: | + preferred + 1/angstrom: + Qmean(NX_NUMBER): + exists: ['min', '0'] + unit: NX_PER_LENGTH + doc: | + Mean value of :math:`Q` for this data point. + Useful when describing data that has been + binned from higher-resolution data. + + It is expected that ``Q`` is provided + and that both ``Q`` and ``Qmean`` will have the same units. + \@units: + exists: optional + doc: | + Engineering units to use when expressing + :math:`Q` and related terms. + + Data expressed in other units may not be processed by some + software packages. + enumeration: + 1/m: + 1/nm: + doc: | + preferred + 1/angstrom: + ShadowFactor: + exists: ['min', '0'] + unit: NX_DIMENSIONLESS + doc: | + A numerical factor applied to pixels affected by the beam stop penumbra. + Used in data files from NIST/NCNR instruments. + + See: J.G. Barker and J.S. Pedersen (1995) *J. Appl. Cryst.* **28**, 105-114. + + # optional items + title: + exists: ['min', '1', 'max', '1'] + doc: | + Title of this *SASentry*. + Make it so that you can recognize the data by its title. + Could be the name of the sample, + the name for the measured data, or something else representative. + run: + exists: ['min', '1', 'max', 'unbounded'] + nameType: any + doc: | + Run identification for this *SASentry*. + For many facilities, this is an integer, such as en experiment number. + Use multiple instances of ``run`` as needed, keeping + in mind that HDF5 requires unique names for all entities + in a group. + \@name: + exists: optional + doc: | + Optional string attribute to identify this particular *run*. + Could use this to associate (correlate) multiple *SASdata* elements with *run* elements. + (NXinstrument): + exists: ['min', '0'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASinstrument` + enumeration: [SASinstrument] + doc: | + Description of the small-angle scattering instrument. + + Consider, carefully, the relevance to the SAS data analysis process + when adding subgroups in this **NXinstrument** group. Additional information + can be added but will likely be ignored by standardized data anlysis processes. + + The NeXus :ref:`NXbeam` base class may be added as a subgroup of this **NXinstrument** + group *or* as a subgroup of the **NXsample** group to describe properties of the beam at any + point downstream from the source. + + # =========== + # SASaperture + # =========== + (NXaperture): + exists: ['min', '0'] + doc: | + :ref:`NXaperture` is generic and limits the variation in data files. + + Possible NeXus base class alternatives are: :ref:`NXpinhole` or :ref:`NXslit`. + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASaperture` + enumeration: [SASaperture] + shape: + doc: | + describe the type of aperture (pinhole, 4-blade slit, Soller slit, ...) + x_gap(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + opening along the :math:`x` axis + y_gap(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + opening along the :math:`y` axis + + # ============== + # SAScollimation + # ============== + (NXcollimator): + exists: ['min', '0'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SAScollimation` + enumeration: [SAScollimation] + doc: | + Description of a collimating element (defines the divergence of the beam) in the instrument. + + To document a slit, pinhole, or the beam, refer to the + documentation of the ``NXinstrument`` group above. + length(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Amount/length of collimation inserted (as on a SANS instrument) + distance(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Distance from this collimation element to the sample + + # SAScollimation + + # ============================ + # SASdetector + # ============================ + (NXdetector): + exists: ['min', '0'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASdetector` + enumeration: [SASdetector] + doc: | + Description of a detector in the instrument. + name: + exists: ['max', '1'] + doc: | + Identifies the name of this detector + SDD(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Distance between sample and detector. + + Note: In NXdetector, the ``distance`` field records the + distance to the previous component ... most often the sample. + This use is the same as ``SDD`` for most SAS + instruments but not all. For example, Bonse-Hart cameras + have one or more crystals between the sample and detector. + + We define here the field ``SDD`` to document without + ambiguity the distance between sample and detector. + slit_length(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Slit length of the instrument for this detector, + expressed in the same units as :math:`Q`. + x_position(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_LENGTH + doc: | + Location of the detector in :math:`x` + y_position(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_LENGTH + doc: | + Location of the detector in :math:`y` + roll(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the detector about the :math:`z` axis (roll) + pitch(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the detector about the :math:`x` axis (roll) + yaw(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the detector about the :math:`y` axis (yaw) + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Position of the beam center on the detector. + + This is the x position where the direct beam would hit the detector plane. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. The value can be any + real number (positive, zero, or negative). + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Position of the beam center on the detector. + + This is the y position where the direct beam would hit the detector plane. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. The value can be any + real number (positive, zero, or negative). + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Size of each detector pixel. If it is scalar all pixels are the same size + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Size of each detector pixel. If it is scalar all pixels are the same size + + # SASdetector + + # ============================ + # SASsource + # ============================ + (NXsource): + exists: ['min', '0'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASsource` + enumeration: [SASsource] + doc: | + Description of the radiation source. + radiation: + exists: optional + deprecated: Use either (or both) ``probe`` or ``type`` fields from ``NXsource`` (issue #765) + doc: | + Name of the radiation used. + Note that this is **not** the name of the facility! + + This field contains a value from either the + ``probe`` or ``type`` fields in :ref:`NXsource`. Thus, + it is redundant with existing NeXus structure. + + # enumeration values from NXsource/type and NXsource/probe + enumeration: [Spallation Neutron Source, Pulsed Reactor Neutron Source, Reactor Neutron Source, Synchrotron X-ray Source, Pulsed Muon Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Free-Electron Laser, Optical Laser, Ion Source, UV Plasma Source, neutron, x-ray, muon, electron, ultraviolet, visible light, positron, proton] + beam_shape: + exists: ['min', '0', 'max', '1'] + doc: | + Text description of the shape of the beam (incident on the sample). + incident_wavelength(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_WAVELENGTH + doc: | + wavelength (:math:`\lambda`) of radiation incident on the sample + wavelength_min(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_WAVELENGTH + doc: | + Some facilities specify wavelength using a range. + This is the lowest wavelength in such a range. + wavelength_max(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_WAVELENGTH + doc: | + Some facilities specify wavelength using a range. + This is the highest wavelength in such a range. + incident_wavelength_spread(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_WAVELENGTH + doc: | + Some facilities specify wavelength using a range. + This is the width (FWHM) of such a range. + beam_size_x(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Size of the incident beam along the x axis. + beam_size_y(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Size of the incident beam along the y axis. + + # SASsource + + # SASinstrument + + # ============== + # SASsample + # ============== + (NXsample): + exists: ['min', '0'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASsample` + enumeration: [SASsample] + doc: | + Description of the sample. + name: + exists: ['max', '1'] + doc: | + **ID**: Text string that identifies this sample. + thickness(NX_FLOAT): + exists: ['min', '0', 'max', '1'] + unit: NX_LENGTH + doc: | + Thickness of this sample + transmission(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_DIMENSIONLESS + doc: | + Transmission (:math:`I/I_0`) of this sample. + There is no *units* attribute as this number is dimensionless. + + Note: the ability to store a transmission *spectrum*, + instead of a single value, is provided elsewhere in the structure, + in the *SAStransmission_spectrum* element. + temperature(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_TEMPERATURE + doc: | + Temperature of this sample. + details: + exists: ['min', '0', 'max', 'unbounded'] + nameType: any + doc: | + Any additional sample details. + x_position(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_LENGTH + doc: | + Location of the sample in :math:`x` + y_position(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_LENGTH + doc: | + Location of the sample in :math:`y` + roll(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the sample about the :math:`z` axis (roll) + pitch(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the sample about the :math:`x` axis (roll) + yaw(NX_NUMBER): + exists: ['min', '0', 'max', '1'] + unit: NX_ANGLE + doc: | + Rotation of the sample about the :math:`y` axis (yaw) + + # NXsample + + # ============== + # SASprocess + # ============== + (NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASprocess` + enumeration: [SASprocess] + doc: | + Description of a processing or analysis step. + + Add additional fields as needed to describe value(s) of any + variable, parameter, or term related to the *SASprocess* step. + Be sure to include *units* attributes for all numerical fields. + name: + exists: ['min', '0', 'max', '1'] + doc: | + Optional name for this data processing or analysis step + date(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + doc: | + Optional date for this data processing or analysis step. [#iso8601]_ + + + .. [#iso8601] ISO-8601 standard time representation. + + NeXus dates and times are reported in ISO-8601 + (e.g., ``yyyy-mm-ddThh:mm:ss``) + or modified ISO-8601 (e.g., ``yyyy-mm-dd hh:mm:ss``). + + See: http://www.w3.org/TR/NOTE-datetime + or http://en.wikipedia.org/wiki/ISO_8601 for more details. + description: + exists: ['min', '0', 'max', '1'] + doc: | + Optional description for this data processing or analysis step + term: + exists: ['min', '0', 'max', 'unbounded'] + nameType: any + doc: | + Specifies the value of a single variable, parameter, + or term (while defined here as a string, it could be a number) + related to the *SASprocess* step. + + Note: + The name *term* is not required, it could take any name, + as long as the name is unique within this group. + + # suggested at NIAC2014 + # Isn't this ALWAYS a possibility in any NeXus base class? + # Not needed to define this but it is a good suggestion for usage. + (NXnote): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Any additional notes or subprocessing steps will be documented here. + + An **NXnote** group can be added to any NeXus group at or below the + **NXentry** group. It is shown here as a suggestion of a good place + to *consider* its use. + (NXcollection): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Describes anything about *SASprocess* that is not already described. + + Any content not defined in the canSAS standard can be placed at this point. + + Note: + The name of this group is flexible, it could take any name, + as long as it is unique within the **NXprocess** group. + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASprocessnote` + enumeration: [SASprocessnote] + + # SASprocessnote + + # SASprocess + + # ============== + # SASnote + # ============== + (NXcollection): + exists: ['min', '0', 'max', 'unbounded'] + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SASnote` + enumeration: [SASnote] + doc: | + Free form description of anything not covered by other elements. + + # ============================ + # SAStransmission_spectrum + # ============================ + TRANSMISSION_SPECTRUM(NXdata): + exists: ['min', '0'] + doc: | + The *SAStransmission_spectrum* element + + This describes certain data obtained from a variable-wavelength source + such as pulsed-neutron source. + + # requested to be in the 1D format by ISIS + \@canSAS_class: + doc: | + Official canSAS group: :index:`NXcanSAS (applications); SAStransmission_spectrum` + enumeration: [SAStransmission_spectrum] + \@signal: + type: NX_CHAR + doc: | + Name of the default data field. + enumeration: + T: + doc: | + For **SAStransmission_spectrum**, this is always "T". + \@T_axes: + enumeration: + T: + doc: | + the wavelengths field (as a dimension scale) corresponding to this transmission + \@name: + doc: | + Identify what type of spectrum is being described. + It is expected that this value will take either of these two values: + + ====== ============================================== + value meaning + ====== ============================================== + sample measurement with the sample and container + can measurement with just the container + ====== ============================================== + \@timestamp: + type: NX_DATE_TIME + exists: optional + doc: | + ISO-8601 time [#iso8601]_ + lambda(NX_NUMBER): + unit: NX_WAVELENGTH + doc: | + Wavelength of the radiation. + + This array is of the same shape as ``T`` and ``Tdev``. + T(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Transmission values (:math:`I/I_0`) + as a function of wavelength. + + This array is of the same shape as ``lambda`` and ``Tdev``. + \@uncertainties: + doc: | + Names the dataset (in this SASdata group) that provides the + uncertainty of each transmission :math:`T` to be used for data analysis. + The name of the dataset containing the :math:`T` uncertainty + is expected to be ``Tdev``. + + .. comment + see: https://github.com/canSAS-org/canSAS2012/issues/7 + + Typically: + + @uncertainties="Tdev" + Tdev(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + .. index:: NXcanSAS (applications); Tdev + + Estimated uncertainty (usually standard deviation) + in :math:`T`. Must have the same units as :math:`T`. + + This is the field is named in the *uncertainties* attribute of *T*, as in:: + + T/@uncertainties="Tdev" + + This array is of the same shape as ``lambda`` and ``T``. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0138726f10e2c6809b373544080966e4d3f5a78d2311b780dcabd6ceeea535fa +# +# +# +# +# +# +# +# +# Implementation of the canSAS standard to store reduced small-angle scattering data of any dimension. +# +# .. index:: canSAS +# +# For more details, see: +# +# * http://www.cansas.org/ +# * http://www.cansas.org/formats/canSAS1d/1.1/doc/ +# * http://cansas-org.github.io/canSAS2012/ +# * https://github.com/canSAS-org/NXcanSAS_examples +# +# The minimum requirements for *reduced* small-angle scattering data +# as described by canSAS are summarized in the following figure: +# +# .. _canSAS_2012_minimum: +# +# .. figure:: canSAS/2012-minimum.png +# :width: 60% +# +# The minimum requirements for *reduced* small-angle scattering data. +# (:download:`full image <canSAS/2012-minimum.png>`) +# See :ref:`below <NXcanSAS_minimum>` for the minimum required +# information for a NeXus data file +# written to the NXcanSAS specification. +# +# .. rubric:: Implementation of canSAS standard in NeXus +# +# This application definition is an implementation of the canSAS +# standard for storing both one-dimensional and multi-dimensional +# *reduced* small-angle scattering data. +# +# * NXcanSAS is for reduced SAS data and metadata to be stored together in one file. +# * *Reduced* SAS data consists of :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)` +# * External file links are not to be used for the reduced data. +# * A good practice/practise is, at least, to include a reference to how the data was acquired and processed. Yet this is not a requirement. +# * There is no need for NXcanSAS to refer to any raw data. +# +# The canSAS data format has a structure similar to NeXus, not identical. +# To allow canSAS data to be expressed in NeXus, yet identifiable +# by the canSAS standard, an additional group attribute ``canSAS_class`` +# was introduced. Here is the mapping of some common groups. +# +# =============== ============ ========================== +# group (*) NX_class canSAS_class +# =============== ============ ========================== +# sasentry NXentry SASentry +# sasdata NXdata SASdata +# sasdetector NXdetector SASdetector +# sasinstrument NXinstrument SASinstrument +# sasnote NXnote SASnote +# sasprocess NXprocess SASprocess +# sasprocessnote NXcollection SASprocessnote +# sastransmission NXdata SAStransmission_spectrum +# sassample NXsample SASsample +# sassource NXsource SASsource +# =============== ============ ========================== +# +# (*) The name of each group is a suggestion, +# not a fixed requirement and is chosen as fits each data file. +# See the section on defining +# :ref:`NXDL group and field names <RegExpName>`. +# +# Refer to the NeXus Coordinate System drawing (:ref:`Design-CoordinateSystem`) +# for choice and direction of :math:`x`, :math:`y`, and :math:`z` axes. +# +# .. _NXcanSAS_minimum: +# +# .. rubric:: The minimum required information for a NeXus data file +# written to the NXcanSAS specification. +# +# .. literalinclude:: canSAS/minimum-required.txt +# :tab-width: 4 +# :linenos: +# :language: text +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which :ref:`NXdata` group +# contains the data to be shown by default. +# It is needed to resolve ambiguity when more than one :ref:`NXdata` group exists. +# The value is the name of the default :ref:`NXdata` group. +# Usually, this will be the name of the first *SASdata* group. +# +# +# +# .. index:: NXcanSAS (applications); SASentry +# +# Place the canSAS ``SASentry`` group as a child of a NeXus ``NXentry`` group +# (when data from multiple techniques are being stored) +# or as a replacement for the ``NXentry`` group. +# +# Note: It is required for all numerical objects to provide +# a *units* attribute that describes the engineering units. +# Use the Unidata UDunits [#]_ specification +# as this is compatible with various community standards. +# +# .. [#] The UDunits specification also includes instructions for derived units. +# +# +# +# Official canSAS group: **SASentry** +# +# +# +# +# +# +# +# Describes the version of the canSAS standard used to write this data. +# This must be a text (not numerical) representation. Such as:: +# +# @version="1.1" +# +# +# +# +# +# +# +# +# Official NeXus NXDL schema to which this subentry conforms. +# +# +# +# +# +# +# +# +# +# A *SASData* group contains a single reduced small-angle scattering data set +# that can be represented as :math:`I(\vec{Q})` or :math:`I(|\vec{Q}|)`. +# +# *Q* can be either a vector (:math:`\vec{Q}`) or a vector magnitude (:math:`|\vec{Q}|`) +# +# The name of each *SASdata* group must be unique within a SASentry group. +# Suggest using names such as ``sasdata01``. +# +# NOTE: For the first *SASdata* group, be sure to write the chosen name +# into the `SASentry/@default` attribute, as in:: +# +# SASentry/@default="sasdata01" +# +# A *SASdata* group has several attributes: +# +# * I_axes +# * Q_indices +# * Mask_indices +# +# To indicate the dependency relationships of other varied parameters, +# use attributes similar to ``@Mask_indices`` (such as ``@Temperature_indices`` +# or ``@Pressure_indices``). +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASdata` +# +# +# +# +# +# +# +# Name of the default data field. +# +# +# For canSAS **SASdata**, this is always "I". +# +# +# +# +# String array that defines the independent data fields used in +# the default plot for all of the dimensions of the *signal* field +# (the *signal* field is the field in this group that is named by +# the ``signal`` attribute of this group). +# One entry is provided for every dimension of the ``I`` data object. +# Such as:: +# +# @I_axes="Temperature", "Time", "Pressure", "Q", "Q" +# +# Since there are five items in the list, the intensity field of this example +# ``I`` must be a five-dimensional array (rank=5). +# +# +# +# +# +# Integer or integer array that describes which indices +# (of the :math:`I` data object) are used to +# reference the ``Q`` data object. The items in this array +# use zero-based indexing. Such as:: +# +# @Q_indices=1,3,4 +# +# which indicates that ``Q`` requires three indices +# from the :math:`I` data object: one for time and +# two for Q position. Thus, in this example, the +# ``Q`` data is time-dependent: :math:`\vec{Q}(t)`. +# +# +# +# +# Name of the data mask field. +# +# .. see: https://github.com/nexusformat/definitions/issues/533 +# +# The data *mask* must have the same shape as the *data* field. +# Positions in the mask correspond to positions in the *data* field. +# The value of the mask field may be either a boolean array +# where ``false`` means *no mask* and ``true`` means *mask* +# or a more descriptive array as as defined in :ref:`NXdetector`. +# +# +# +# +# Integer or integer array that describes which indices +# (of the :math:`I` data object) are used to +# reference the ``Mask`` data object. The items in this +# array use zero-based indexing. Such as:: +# +# @Mask_indices=3,4 +# +# which indicates that Q requires two indices +# from the :math:`I` data object for Q position. +# +# +# +# +# ISO-8601 time [#iso8601]_ +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); Q +# +# Array of :math:`Q` data to accompany :math:`I`. +# +# .. figure:: canSAS/Q-geometry.jpg +# :width: 60% +# +# The :math:`\vec{Q}` geometry. +# (:download:`full image <canSAS/Q-geometry.jpg>`) +# +# :math:`Q` may be represented as either +# the three-dimensional scattering vector :math:`\vec{Q}` +# or the magnitude of the scattering vector, :math:`|\vec{Q}|`. +# +# .. math:: |\vec{Q}| = (4\pi/\lambda) sin(\theta) +# +# When we write :math:`Q`, we may refer to either or both of +# :math:`|\vec{Q}|` +# or :math:`\vec{Q}`, depending on the context. +# +# +# +# Engineering units to use when expressing +# :math:`Q` and related terms. +# +# Data expressed in other units will generate +# a warning from validation software and may not +# be processed by some analysis software packages. +# +# +# +# +# preferred +# +# +# +# +# +# +# (optional: for numerical arrays) +# +# Names the dataset (in this SASdata group) that provides the +# uncertainty to be used for data analysis. +# The name of the dataset containing the :math:`Q` uncertainty +# is flexible. The name must be unique in the *SASdata* group. +# +# .. comment +# see: https://github.com/canSAS-org/canSAS2012/issues/7 +# +# Such as:: +# +# @uncertainties="Q_uncertainties" +# +# The *uncertainties* field will have the same *shape* (dimensions) +# as the Q field. +# +# These values are the estimates of uncertainty of each Q. By default, +# this will be interpreted to be the estimated standard deviation. +# In special cases, when a standard deviation cannot possibly be used, +# its value can specify another measure of distribution width. +# +# There may also be a subdirectory (optional) with constituent +# components. +# +# .. note:: To report distribution in reported :math:`Q` values, +# use the ``@resolutions`` attribute. It is possible for both +# ``@resolutions`` and ``uncertainties`` to be reported. +# +# +# +# +# +# .. index:: NXcanSAS (applications); resolutions +# +# (optional: for numerical arrays) +# +# Names the dataset (in this SASdata group) containing the :math:`Q` resolution. +# The name of the dataset containing the :math:`Q` resolution +# is flexible. The name must be unique in the *SASdata* group. +# +# .. comment +# see: https://github.com/canSAS-org/canSAS2012/issues/7 +# +# The *resolutions* field will have the same *shape* (dimensions) +# as the Q field. +# +# Generally, this is the principal resolution of each :math:`Q`. +# Names the data object (in this SASdata group) that provides the +# :math:`Q` resolution to be used for data analysis. Such as:: +# +# @resolutions="Qdev" +# +# To specify two-dimensional resolution for slit-smearing geometry, +# such as (*dQw*, *dQl*), use a string array, such as:: +# +# @resolutions="dQw", "dQl" +# +# There may also be a subdirectory (optional) with constituent +# components. +# +# This pattern will demonstrate how to introduce further as-yet +# unanticipated terms related to the data. +# +# .. comment +# see: https://github.com/nexusformat/definitions/issues/492#issuecomment-262813907 +# +# By default, the values of the resolutions data object are assumed to be +# one standard deviation of any function used to approximate the +# resolution function. This equates to the width of the gaussian +# distribution if a Gaussian is chosen. See the ``@resolutions_description`` +# attribute. +# +# .. note:: To report uncertainty in reported :math:`Q` values, +# use the ``@uncertainties`` attribute. It is possible for both +# ``@resolutions`` and ``uncertainties`` to be reported. +# +# +# +# +# +# (optional) +# Generally, this describes the :math:`Q` ``@resolutions`` data object. +# By default, the value is assumed to be "Gaussian". These are +# suggestions: +# +# * Gaussian +# * Lorentzian +# * Square : +# note that the full width of the square would be ~2.9 times +# the standard deviation specified in the vector +# * Triangular +# * Sawtooth-outward : vertical edge pointing to larger Q +# * Sawtooth-inward vertical edge pointing to smaller Q +# * Bin : range of values contributing +# (for example, when 2-D detector data have been reduced +# to a 1-D :math:`I(|Q|)` dataset) +# +# For other meanings, it may be necessary to provide further details +# such as the function used to assess the resolution. +# In such cases, use additional datasets or a :ref:`NXnote` subgroup +# to include that detail. +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); I +# +# Array of intensity (:math:`I`) data. +# +# The intensity may be represented in one of these forms: +# +# **absolute units**: :math:`d\Sigma/d\Omega(Q)` +# differential cross-section +# per unit volume per unit solid angle (such as: 1/cm/sr or 1/m/sr) +# +# **absolute units**: :math:`d\sigma/d\Omega(Q)` +# differential cross-section +# per unit atom per unit solid angle (such as: cm^2 or m^2) +# +# **arbitrary units**: :math:`I(Q)` +# usually a ratio of two detectors +# but units are meaningless (such as: a.u. or counts) +# +# This presents a few problems +# for analysis software to sort out when reading the data. +# Fortunately, it is possible to analyze the *units* to determine which type of +# intensity is being reported and make choices at the time the file is read. But this is +# an area for consideration and possible improvement. +# +# One problem arises with software that automatically converts data into some canonical +# units used by that software. The software should not convert units between these different +# types of intensity indiscriminately. +# +# A second problem is that when arbitrary units are used, then the set of possible +# analytical results is restricted. With such units, no meaningful volume fraction +# or number density can be determined directly from :math:`I(Q)`. +# +# In some cases, it is possible to apply a factor to convert the arbitrary +# units to an absolute scale. This should be considered as a possibility +# of the analysis process. +# +# Where this documentation says *typical units*, it is possible that small-angle +# data may be presented in other units and still be consistent with NeXus. +# See the :ref:`design-units` section. +# +# +# +# Engineering units to use when expressing +# :math:`I` and intensity-related terms. +# +# Data expressed in other units (or missing a ``@units`` attribute) +# will be treated as ``arbitrary`` by some software packages. +# +# For software using the UDUNITS-2 library, ``arbitrary`` will be +# changed to ``unknown`` for handling with that library. +# +# +# +# includes m2/m3 and 1/m/sr +# +# +# includes cm2/cm3 and 1/cm/sr +# +# +# +# +# +# +# +# +# (optional: for numerical arrays) +# +# Names the dataset (in this SASdata group) that provides the +# uncertainty of :math:`I` to be used for data analysis. +# The name of the dataset containing the :math:`I` uncertainty +# is flexible. The name must be unique in the *SASdata* group. +# +# .. comment +# see: https://github.com/canSAS-org/canSAS2012/issues/7 +# +# Generally, this is the estimate of the uncertainty of each :math:`I`. +# Typically the estimated standard deviation. +# +# *Idev* is the canonical name from the 1D standard. +# The NXcanSAS standard allows for the name to be described using this attribute. +# Such as:: +# +# @uncertainties="Idev" +# +# +# +# +# +# (optional) +# Names the field (a.k.a. dataset) that contains a factor +# to multiply ``I``. By default, this value is unity. +# Should an uncertainty be associated with the scaling factor +# field, the field containing that uncertainty would be +# designated via the ``uncertainties`` attribute. +# Such as:: +# +# I : NX_NUMBER +# @uncertainties="Idev" : NX_CHAR +# @scaling_factor="I_scaling" : NX_CHAR +# Idev : NX_NUMBER +# I_scaling : NX_NUMBER +# @uncertainties="I_scaling_dev" : NX_CHAR +# I_scaling_dev : NX_NUMBER +# +# The exact names for ``I_scaling`` and ``I_scaling_dev`` are not +# defined by NXcanSAS. The user has the flexibility to use names +# different than those shown in this example. +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); Idev +# +# Estimated **uncertainty** (usually standard deviation) +# in :math:`I`. Must have the same units as :math:`I`. +# +# When present, the name of this field is also +# recorded in the *uncertainties* attribute of *I*, as in:: +# +# I/@uncertainties="Idev" +# +# +# +# +# Engineering units to use when expressing +# :math:`I` and intensity-related terms. +# +# Data expressed in other units (or missing a ``@units`` attribute) +# will generate a warning from any validation process +# and will be treated as ``arbitrary`` by some analysis software packages. +# +# For software using the UDUNITS-2 library, ``arbitrary`` will be +# changed to ``unknown`` for handling with that library. +# +# +# +# includes m2/m3 and 1/m/sr +# +# +# includes cm2/cm3 and 1/cm/sr +# +# +# +# +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); Qdev +# +# Estimated :math:`Q` **resolution** (usually standard deviation). +# Must have the same units as :math:`Q`. +# +# When present, the name of this field is also +# recorded in the *resolutions* attribute of *Q*, +# as in:: +# +# Q/@resolutions="Qdev" +# +# or:: +# +# Q/@resolutions="dQw", "dQl" +# +# +# +# +# Engineering units to use when expressing +# :math:`Q` and related terms. +# +# Data expressed in other units may not be processed by some +# software packages. +# +# +# +# +# preferred +# +# +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); dQw +# +# :math:`Q` **resolution** along the axis of scanning +# (the high-resolution *slit width* direction). +# Useful for defining resolution data from +# slit-smearing instruments such as Bonse-Hart geometry. +# Must have the same units as :math:`Q`. +# +# When present, the name of this field is also +# recorded in the *resolutions* attribute of *Q*, +# as in:: +# +# Q/@resolutions="dQw", "dQl" +# +# +# +# +# Engineering units to use when expressing +# :math:`Q` and related terms. +# +# Data expressed in other units may not be processed by some +# software packages. +# +# +# +# +# preferred +# +# +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); dQl +# +# :math:`Q` **resolution** perpendicular to the axis of scanning +# (the low-resolution *slit length* direction). +# Useful for defining resolution data from +# slit-smearing instruments such as Bonse-Hart geometry. +# Must have the same units as :math:`Q`. +# +# When present, the name of this field is also +# recorded in the *resolutions* attribute of *Q*, +# as in:: +# +# Q/@resolutions="dQw", "dQl" +# +# +# +# +# Engineering units to use when expressing +# :math:`Q` and related terms. +# +# Data expressed in other units may not be processed by some +# software packages. +# +# +# +# +# preferred +# +# +# +# +# +# +# +# +# Mean value of :math:`Q` for this data point. +# Useful when describing data that has been +# binned from higher-resolution data. +# +# It is expected that ``Q`` is provided +# and that both ``Q`` and ``Qmean`` will have the same units. +# +# +# +# Engineering units to use when expressing +# :math:`Q` and related terms. +# +# Data expressed in other units may not be processed by some +# software packages. +# +# +# +# +# preferred +# +# +# +# +# +# +# +# A numerical factor applied to pixels affected by the beam stop penumbra. +# Used in data files from NIST/NCNR instruments. +# +# See: J.G. Barker and J.S. Pedersen (1995) *J. Appl. Cryst.* **28**, 105-114. +# +# +# +# +# +# +# +# +# Title of this *SASentry*. +# Make it so that you can recognize the data by its title. +# Could be the name of the sample, +# the name for the measured data, or something else representative. +# +# +# +# +# Run identification for this *SASentry*. +# For many facilities, this is an integer, such as en experiment number. +# Use multiple instances of ``run`` as needed, keeping +# in mind that HDF5 requires unique names for all entities +# in a group. +# +# +# +# Optional string attribute to identify this particular *run*. +# Could use this to associate (correlate) multiple *SASdata* elements with *run* elements. +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASinstrument` +# +# +# +# +# +# Description of the small-angle scattering instrument. +# +# Consider, carefully, the relevance to the SAS data analysis process +# when adding subgroups in this **NXinstrument** group. Additional information +# can be added but will likely be ignored by standardized data anlysis processes. +# +# The NeXus :ref:`NXbeam` base class may be added as a subgroup of this **NXinstrument** +# group *or* as a subgroup of the **NXsample** group to describe properties of the beam at any +# point downstream from the source. +# +# +# +# +# +# +# :ref:`NXaperture` is generic and limits the variation in data files. +# +# Possible NeXus base class alternatives are: :ref:`NXpinhole` or :ref:`NXslit`. +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASaperture` +# +# +# +# +# +# +# +# describe the type of aperture (pinhole, 4-blade slit, Soller slit, ...) +# +# +# +# opening along the :math:`x` axis +# +# +# opening along the :math:`y` axis +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SAScollimation` +# +# +# +# +# +# Description of a collimating element (defines the divergence of the beam) in the instrument. +# +# To document a slit, pinhole, or the beam, refer to the +# documentation of the ``NXinstrument`` group above. +# +# +# +# Amount/length of collimation inserted (as on a SANS instrument) +# +# +# +# Distance from this collimation element to the sample +# +# +# +# +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASdetector` +# +# +# +# +# +# Description of a detector in the instrument. +# +# +# +# Identifies the name of this detector +# +# +# +# Distance between sample and detector. +# +# Note: In NXdetector, the ``distance`` field records the +# distance to the previous component ... most often the sample. +# This use is the same as ``SDD`` for most SAS +# instruments but not all. For example, Bonse-Hart cameras +# have one or more crystals between the sample and detector. +# +# We define here the field ``SDD`` to document without +# ambiguity the distance between sample and detector. +# +# +# +# +# Slit length of the instrument for this detector, +# expressed in the same units as :math:`Q`. +# +# +# +# +# Location of the detector in :math:`x` +# +# +# Location of the detector in :math:`y` +# +# +# Rotation of the detector about the :math:`z` axis (roll) +# +# +# Rotation of the detector about the :math:`x` axis (roll) +# +# +# Rotation of the detector about the :math:`y` axis (yaw) +# +# +# +# +# Position of the beam center on the detector. +# +# This is the x position where the direct beam would hit the detector plane. +# This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels +# as documented by the units attribute. The value can be any +# real number (positive, zero, or negative). +# +# +# +# +# +# Position of the beam center on the detector. +# +# This is the y position where the direct beam would hit the detector plane. +# This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels +# as documented by the units attribute. The value can be any +# real number (positive, zero, or negative). +# +# +# +# +# Size of each detector pixel. If it is scalar all pixels are the same size +# +# +# +# Size of each detector pixel. If it is scalar all pixels are the same size +# +# +# +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASsource` +# +# +# +# +# +# Description of the radiation source. +# +# +# +# +# Name of the radiation used. +# Note that this is **not** the name of the facility! +# +# This field contains a value from either the +# ``probe`` or ``type`` fields in :ref:`NXsource`. Thus, +# it is redundant with existing NeXus structure. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Text description of the shape of the beam (incident on the sample). +# +# +# wavelength (:math:`\lambda`) of radiation incident on the sample +# +# +# +# Some facilities specify wavelength using a range. +# This is the lowest wavelength in such a range. +# +# +# +# +# Some facilities specify wavelength using a range. +# This is the highest wavelength in such a range. +# +# +# +# +# Some facilities specify wavelength using a range. +# This is the width (FWHM) of such a range. +# +# +# +# Size of the incident beam along the x axis. +# +# +# Size of the incident beam along the y axis. +# +# +# +# +# +# +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASsample` +# +# +# +# +# +# Description of the sample. +# +# +# +# **ID**: Text string that identifies this sample. +# +# +# Thickness of this sample +# +# +# +# Transmission (:math:`I/I_0`) of this sample. +# There is no *units* attribute as this number is dimensionless. +# +# Note: the ability to store a transmission *spectrum*, +# instead of a single value, is provided elsewhere in the structure, +# in the *SAStransmission_spectrum* element. +# +# +# +# Temperature of this sample. +# +# +# Any additional sample details. +# +# +# +# Location of the sample in :math:`x` +# +# +# Location of the sample in :math:`y` +# +# +# Rotation of the sample about the :math:`z` axis (roll) +# +# +# Rotation of the sample about the :math:`x` axis (roll) +# +# +# Rotation of the sample about the :math:`y` axis (yaw) +# +# +# +# +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASprocess` +# +# +# +# +# +# Description of a processing or analysis step. +# +# Add additional fields as needed to describe value(s) of any +# variable, parameter, or term related to the *SASprocess* step. +# Be sure to include *units* attributes for all numerical fields. +# +# +# +# Optional name for this data processing or analysis step +# +# +# +# Optional date for this data processing or analysis step. [#iso8601]_ +# +# +# .. [#iso8601] ISO-8601 standard time representation. +# +# NeXus dates and times are reported in ISO-8601 +# (e.g., ``yyyy-mm-ddThh:mm:ss``) +# or modified ISO-8601 (e.g., ``yyyy-mm-dd hh:mm:ss``). +# +# See: http://www.w3.org/TR/NOTE-datetime +# or http://en.wikipedia.org/wiki/ISO_8601 for more details. +# +# +# +# Optional description for this data processing or analysis step +# +# +# +# Specifies the value of a single variable, parameter, +# or term (while defined here as a string, it could be a number) +# related to the *SASprocess* step. +# +# Note: +# The name *term* is not required, it could take any name, +# as long as the name is unique within this group. +# +# +# +# +# +# +# Any additional notes or subprocessing steps will be documented here. +# +# An **NXnote** group can be added to any NeXus group at or below the +# **NXentry** group. It is shown here as a suggestion of a good place +# to *consider* its use. +# +# +# +# +# +# Describes anything about *SASprocess* that is not already described. +# +# Any content not defined in the canSAS standard can be placed at this point. +# +# Note: +# The name of this group is flexible, it could take any name, +# as long as it is unique within the **NXprocess** group. +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASprocessnote` +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SASnote` +# +# +# +# +# +# +# Free form description of anything not covered by other elements. +# +# +# +# +# +# +# +# The *SAStransmission_spectrum* element +# +# This describes certain data obtained from a variable-wavelength source +# such as pulsed-neutron source. +# +# +# The name of each *SAStransmission_spectrum* group must be unique within a SASentry group. +# Suggest using names such as ``sastransmission_spectrum01``. +# +# +# Official canSAS group: :index:`NXcanSAS (applications); SAStransmission_spectrum` +# +# +# +# +# +# +# Name of the default data field. +# +# +# For **SAStransmission_spectrum**, this is always "T". +# +# +# +# +# +# the wavelengths field (as a dimension scale) corresponding to this transmission +# +# +# +# +# +# Identify what type of spectrum is being described. +# It is expected that this value will take either of these two values: +# +# ====== ============================================== +# value meaning +# ====== ============================================== +# sample measurement with the sample and container +# can measurement with just the container +# ====== ============================================== +# +# +# +# +# ISO-8601 time [#iso8601]_ +# +# +# +# +# +# Wavelength of the radiation. +# +# This array is of the same shape as ``T`` and ``Tdev``. +# +# +# +# +# Transmission values (:math:`I/I_0`) +# as a function of wavelength. +# +# This array is of the same shape as ``lambda`` and ``Tdev``. +# +# +# +# Names the dataset (in this SASdata group) that provides the +# uncertainty of each transmission :math:`T` to be used for data analysis. +# The name of the dataset containing the :math:`T` uncertainty +# is expected to be ``Tdev``. +# +# .. comment +# see: https://github.com/canSAS-org/canSAS2012/issues/7 +# +# Typically: +# +# @uncertainties="Tdev" +# +# +# +# +# +# +# +# .. index:: NXcanSAS (applications); Tdev +# +# Estimated uncertainty (usually standard deviation) +# in :math:`T`. Must have the same units as :math:`T`. +# +# This is the field is named in the *uncertainties* attribute of *T*, as in:: +# +# T/@uncertainties="Tdev" +# +# This array is of the same shape as ``lambda`` and ``T``. +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXdirecttof.yaml b/applications/nyaml/NXdirecttof.yaml new file mode 100644 index 0000000000..8ced0bc49d --- /dev/null +++ b/applications/nyaml/NXdirecttof.yaml @@ -0,0 +1,102 @@ +category: application +doc: | + This is a application definition for raw data from a direct geometry TOF spectrometer +type: group +NXdirecttof(NXtofraw): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXdirecttof] + (NXinstrument): + (NXfermi_chopper)fermi_chopper: + exists: ['min', '0'] + rotation_speed(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + chopper rotation speed + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy selected + (NXdisk_chopper)disk_chopper: + exists: ['min', '0'] + rotation_speed(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + chopper rotation speed + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy selected + doc: | + We definitly want the rotation_speed and energy of the chopper. Thus either + a fermi_chopper or a disk_chopper group is required. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1d47a6d74aba3fd326b8022400cf62c8d44aa409690508a10b91dce0f188c23c +# +# +# +# +# This is a application definition for raw data from a direct geometry TOF spectrometer +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# chopper rotation speed +# +# +# energy selected +# +# +# +# +# chopper rotation speed +# +# +# energy selected +# +# +# +# We definitly want the rotation_speed and energy of the chopper. Thus either +# a fermi_chopper or a disk_chopper group is required. +# +# +# +# diff --git a/applications/nyaml/NXfluo.yaml b/applications/nyaml/NXfluo.yaml new file mode 100644 index 0000000000..34390473a8 --- /dev/null +++ b/applications/nyaml/NXfluo.yaml @@ -0,0 +1,165 @@ +category: application +doc: | + This is an application definition for raw data from an X-ray fluorescence experiment +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nE: | + Number of energies +type: group +NXfluo(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + enumeration: [NXfluo] + (NXinstrument): + (NXsource): + type: + name: + probe: + enumeration: [x-ray] + (NXmonochromator)monochromator: + wavelength(NX_FLOAT): + (NXdetector)fluorescence: + data(NX_INT): + axes: energy + signal: 1 + dimensions: + rank: 1 + dim: [[1, nE]] + energy(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nE]] + (NXsample): + name: + doc: | + Descriptive name of sample + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_INT): + (NXdata)data: + energy(link): + target: /entry/instrument/fluorescence/energy + data(link): + target: /entry/instrument/fluorescence/data + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a29da208a1ae223c660dcd483b2d1f475272c28538ec79fc7f342883ca2cd321 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of energies +# +# +# +# This is an application definition for raw data from an X-ray fluorescence experiment +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXindirecttof.yaml b/applications/nyaml/NXindirecttof.yaml new file mode 100644 index 0000000000..ea4502b226 --- /dev/null +++ b/applications/nyaml/NXindirecttof.yaml @@ -0,0 +1,111 @@ +category: application +doc: | + This is a application definition for raw data from a direct geometry TOF spectrometer +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nDet: | + Number of detectors +type: group +NXindirecttof(NXtofraw): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXindirecttof] + (NXinstrument): + (NXmonochromator)analyser: + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + analyzed energy + dimensions: + rank: 1 + dim: [[1, nDet]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + polar angle towards sample + dimensions: + rank: 1 + dim: [[1, nDet]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + distance from sample + dimensions: + rank: 1 + dim: [[1, nDet]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a8938d31a14f39d6935cd347cc25df7c67207c21c5bd8aab84182f83d2681d6e +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of detectors +# +# +# This is a application definition for raw data from a direct geometry TOF spectrometer +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# analyzed energy +# +# +# +# +# polar angle towards sample +# +# +# +# +# distance from sample +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXiqproc.yaml b/applications/nyaml/NXiqproc.yaml new file mode 100644 index 0000000000..de29062cf5 --- /dev/null +++ b/applications/nyaml/NXiqproc.yaml @@ -0,0 +1,201 @@ +category: application +doc: | + Application definition for any :math:`I(Q)` data. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nVars: | + The number of values taken by the varied variable + nQX: | + Number of values for the first dimension of Q + nQY: | + Number of values for the second dimension of Q +type: group +NXiqproc(NXobject): + (NXentry): + \@entry: + + # TODO documentation string needed here + title: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXiqproc] + (NXinstrument)instrument: + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + name(NX_CHAR): + doc: | + Name of the instrument from which this data was reduced. + (NXsample): + name: + doc: | + Descriptive name of sample + (NXprocess)reduction: + program(NX_CHAR): + version(NX_CHAR): + (NXparameters)input: + filenames(NX_CHAR): + doc: | + Raw data files used to generate this I(Q) + doc: | + Input parameters for the reduction program used + (NXparameters)output: + doc: | + Eventual output parameters from the data reduction program used + (NXdata): + data(NX_INT): + signal: 1 + doc: | + This is I(Q). The client has to analyse the dimensions + of I(Q). Often, multiple I(Q) for various environment + conditions are measured; that would be the first + dimension. Q can be multidimensional, this accounts for + the further dimensions in the data + dimensions: + rank: 3 + dim: [[1, nVars], [2, nQX], [3, nQY]] + variable(NX_NUMBER): + axis: 1 + dimensions: + rank: 1 + dim: [[1, nVars]] + \@varied_variable: + doc: | + The real name of the varied variable in the first dim of data, temperature, P, MF etc... + qx(NX_NUMBER): + axis: 2 + doc: | + Values for the first dimension of Q + dimensions: + rank: 1 + dim: [[1, nQX]] + qy(NX_NUMBER): + axis: 3 + doc: | + Values for the second dimension of Q + dimensions: + rank: 1 + dim: [[1, nQY]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 20d4c942462350f47af152e37e83f320e5814be2b399fc9a4897794d1ce4916e +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# The number of values taken by the varied variable +# +# +# Number of values for the first dimension of Q +# +# +# Number of values for the second dimension of Q +# +# +# Application definition for any :math:`I(Q)` data. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Name of the instrument from which this data was reduced. +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# Raw data files used to generate this I(Q) +# Input parameters for the reduction program used +# +# Eventual output parameters from the data reduction program used +# +# +# +# This is I(Q). The client has to analyse the dimensions +# of I(Q). Often, multiple I(Q) for various environment +# conditions are measured; that would be the first +# dimension. Q can be multidimensional, this accounts for +# the further dimensions in the data +# +# +# +# +# +# +# +# +# +# +# +# +# The real name of the varied variable in the first dim of data, temperature, P, MF etc... +# +# Values for the first dimension of Q +# +# +# +# Values for the second dimension of Q +# +# +# +# +# diff --git a/applications/nyaml/NXlauetof.yaml b/applications/nyaml/NXlauetof.yaml new file mode 100644 index 0000000000..60691e613e --- /dev/null +++ b/applications/nyaml/NXlauetof.yaml @@ -0,0 +1,244 @@ +category: application +doc: | + This is the application definition for a TOF laue diffractometer +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nXPixels: | + Number of X pixels + nYPixels: | + Number of Y pixels + nTOF: | + Time of flight +type: group +NXlauetof(NXobject): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXlauetof] + (NXinstrument)instrument: + (NXdetector)detector: + doc: | + This assumes a planar 2D detector. All angles and distances refer to the center of the + detector. + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + The polar_angle (two theta) where the detector is placed. + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + The azimuthal angle where the detector is placed. + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, nXPixels], [2, nYPixels], [3, nTOF]] + \@signal: + type: NX_POSINT + enumeration: [1] + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + distance(NX_FLOAT): + unit: NX_LENGTH + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, nTOF]] + (NXsample)sample: + name: + doc: | + Descriptive name of sample + orientation_matrix(NX_FLOAT): + doc: | + The orientation matrix according to Busing and + Levy conventions. This is not strictly necessary as + the UB can always be derived from the data. But + let us bow to common usage which includes thie + UB nearly always. + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + unit_cell(NX_FLOAT): + doc: | + The unit cell, a, b, c, alpha, beta, gamma. + Again, not strictly necessary, but normally written. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXmonitor)control: + mode: + doc: | + Count to a preset value based on either clock time (timer) or received monitor counts + (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_INT): + doc: | + use these attributes ``primary=1 signal=1`` + dimensions: + rank: 1 + dim: [[1, nTOF]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, nTOF]] + (NXdata)name: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9e664cc6cefa2508344073c6ddcac30bdfaa76a7950aaba871bf13b9f6f72be4 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of X pixels +# +# +# Number of Y pixels +# +# +# Time of flight +# +# +# +# This is the application definition for a TOF laue diffractometer +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# This assumes a planar 2D detector. All angles and distances refer to the center of the +# detector. +# +# +# The polar_angle (two theta) where the detector is placed. +# +# +# The azimuthal angle where the detector is placed. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# The orientation matrix according to Busing and +# Levy conventions. This is not strictly necessary as +# the UB can always be derived from the data. But +# let us bow to common usage which includes thie +# UB nearly always. +# +# +# +# +# +# +# +# +# The unit cell, a, b, c, alpha, beta, gamma. +# Again, not strictly necessary, but normally written. +# +# +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) or received monitor counts +# (monitor). +# +# +# +# +# +# +# preset value for time or monitor +# +# +# use these attributes ``primary=1 signal=1`` +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXmonopd.yaml b/applications/nyaml/NXmonopd.yaml new file mode 100644 index 0000000000..f6381a17ce --- /dev/null +++ b/applications/nyaml/NXmonopd.yaml @@ -0,0 +1,223 @@ +category: application +doc: | + Monochromatic Neutron and X-Ray Powder diffractometer + + Instrument + definition for a powder diffractometer at a monochromatic neutron + or X-ray beam. This is both suited for a powder diffractometer + with a single detector or a powder diffractometer with a position + sensitive detector. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + i: | + i is the number of wavelengths + nDet: | + Number of detectors +type: group +NXmonopd(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXmonopd] + (NXinstrument): + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + (NXcrystal): + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Optimum diffracted wavelength + dimensions: + rank: 1 + dim: [[1, i]] + (NXdetector): + polar_angle(NX_FLOAT): + axis: 1 + dimensions: + rank: 1 + dim: [[1, nDet]] + data(NX_INT): + signal: 1 + doc: | + detector signal (usually counts) are already + corrected for detector efficiency + dimensions: + rank: 1 + dim: [[1, nDet]] + (NXsample): + name: + doc: | + Descriptive name of sample + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + 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 + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + integral(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts + (NXdata): + polar_angle(link): + target: /NXentry/NXinstrument/NXdetector/polar_angle + doc: | + Link to polar angle in /NXentry/NXinstrument/NXdetector + data(link): + target: /NXentry/NXinstrument/NXdetector/data + doc: | + Link to data in /NXentry/NXinstrument/NXdetector + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a85a64b0de4e045e8b6275a9ef6309437ba7aaad04f28e31d62f46d4744763c1 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# i is the number of wavelengths +# +# +# Number of detectors +# +# +# +# Monochromatic Neutron and X-Ray Powder diffractometer +# +# Instrument +# definition for a powder diffractometer at a monochromatic neutron +# or X-ray beam. This is both suited for a powder diffractometer +# with a single detector or a powder diffractometer with a position +# sensitive detector. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Optimum diffracted wavelength +# +# +# +# +# +# +# +# +# +# +# +# +# +# detector signal (usually counts) are already +# corrected for detector efficiency +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# 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 +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# Total integral monitor counts +# +# +# +# +# Link to polar angle in /NXentry/NXinstrument/NXdetector +# +# +# Link to data in /NXentry/NXinstrument/NXdetector +# +# +# +# diff --git a/applications/nyaml/NXmx.yaml b/applications/nyaml/NXmx.yaml new file mode 100644 index 0000000000..f6fcb8c76b --- /dev/null +++ b/applications/nyaml/NXmx.yaml @@ -0,0 +1,1758 @@ +category: application +doc: | + functional application definition for macromolecular crystallography +symbols: + doc: | + These symbols will be used below to coordinate datasets + with the same shape. Most MX x-ray detectors will produce + two-dimensional images. Some will produce three-dimensional + images, using one of the indices to select a detector module. + dataRank: | + Rank of the ``data`` field + nP: | + Number of scan points + i: | + Number of detector pixels in the slowest direction + j: | + Number of detector pixels in the second slowest direction + k: | + Number of detector pixels in the third slowest direction + m: | + Number of channels in the incident beam spectrum, if known + groupIndex: | + An array of the hierarchical levels of the parents of detector + elements or groupings of detector elements. + A top-level element or grouping has parent level -1. +type: group +NXmx(NXobject): + (NXentry): + doc: | + Note, it is recommended that ``file_name`` and ``file_time`` are included + as attributes at the root of a file that includes :ref:`NXmx`. See + :ref:`NXroot`. + \@version: + exists: optional + doc: | + Describes the version of the NXmx definition used to write this data. + This must be a text (not numerical) representation. Such as:: + + @version="1.0" + enumeration: [1.0] + title(NX_CHAR): + exists: ['min', '0'] + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time/date of the first data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. + end_time(NX_DATE_TIME): + exists: ['min', '0'] + doc: | + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field should only be + filled when the value is accurately observed. If the data + collection aborts or otherwise prevents accurate recording of + the end_time, this field should be omitted. + end_time_estimated(NX_DATE_TIME): + doc: | + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field may be filled + with a value estimated before an observed value is available. + definition: + doc: | + NeXus NXDL schema to which this file conforms + enumeration: [NXmx] + (NXdata): + data(NX_NUMBER): + exists: recommended + doc: | + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + dimensions: + rank: dataRank + dim: [[1, nP], [2, i], [3, j], [4, k]] + dim_parameters: + required: ['false'] + (NXsample): + name(NX_CHAR): + doc: | + Descriptive name of sample + depends_on(NX_CHAR): + + # better type for paths the need to resolve + doc: | + This is a requirement to describe for any scan experiment. + + The axis on which the sample position depends may be stored + anywhere, but is normally stored in the NXtransformations + group within the NXsample group. + + If there is no goniometer, e.g. with a jet, depends_on + should be set to "." + (NXtransformations): + exists: ['min', '0'] + doc: | + This is the recommended location for sample goniometer + and other related axes. + + This is a requirement to describe for any scan experiment. + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + + Use of the depends_on field and the NXtransformations group is + strongly recommended. As noted above this should be an absolute + requirement to have for any scan experiment. + + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + exists: ['min', '0'] + (NXinstrument): + name(NX_CHAR): + exists: ['min', '1'] + + # CAUTION: keep URLs all on one line + doc: | + Name of instrument. Consistency with the controlled + vocabulary beamline naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html + and + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html + is highly recommended. + \@short_name: + exists: optional + doc: | + Short name for instrument, perhaps the acronym. + time_zone(NX_DATE_TIME): + exists: recommended + doc: | + ISO 8601 time_zone offset from UTC. + (NXattenuator): + exists: ['min', '0'] + attenuator_transmission(NX_NUMBER): + unit: NX_UNITLESS + exists: ['min', '0'] + (NXdetector_group): + exists: recommended + doc: | + Optional logical grouping of detectors. + + Each detector is represented as an NXdetector + with its own detector data array. Each detector data array + may be further decomposed into array sections by use of + NXdetector_module groups. Detectors can be grouped logically + together using NXdetector_group. Groups can be further grouped + hierarchically in a single NXdetector_group (for example, if + there are multiple detectors at an endstation or multiple + endstations at a facility). Alternatively, multiple + NXdetector_groups can be provided. + + The groups are defined hierarchically, with names given + in the group_names field, unique identifying indices given + in the field group_index, and the level in the hierarchy + given in the group_parent field. For example if an x-ray + detector group, DET, consists of four detectors in a + rectangular array:: + + DTL DTR + DLL DLR + + We could have:: + + group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] + group_index: [1, 2, 3, 4, 5] + group_parent: [-1, 1, 1, 1, 1] + group_names(NX_CHAR): + doc: | + An array of the names of the detectors or the names of + hierarchical groupings of detectors. + group_index(NX_INT): + doc: | + An array of unique identifiers for detectors or groupings + of detectors. + + Each ID is a unique ID for the corresponding detector or group + named in the field group_names. The IDs are positive integers + starting with 1. + dimensions: + rank: 1 + dim: [[1, i]] + group_parent(NX_INT): + doc: | + An array of the hierarchical levels of the parents of detectors + or groupings of detectors. + + A top-level grouping has parent level -1. + dimensions: + rank: 1 + dim: [[1, groupIndex]] + (NXdetector): + doc: | + Normally the detector group will have the name ``detector``. + However, in the case of multiple detectors, each detector + needs a uniquely named NXdetector. + depends_on(NX_CHAR): + exists: ['min', '0'] + doc: | + NeXus path to the detector positioner axis that most directly + supports the detector. In the case of a single-module + detector, the detector axis chain may start here. + (NXtransformations): + exists: ['min', '0'] + doc: | + Location for axes (transformations) to do with the + detector. In the case of a single-module detector, the + axes of the detector axis chain may be stored here. + (NXcollection): + exists: ['min', '0'] + doc: | + Suggested container for detailed non-standard detector + information like corrections applied automatically or + performance settings. + data(NX_NUMBER): + exists: recommended + doc: | + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + dimensions: + rank: dataRank + dim: [[1, nP], [2, i], [3, j], [4, k]] + dim_parameters: + required: ['false'] + description: + exists: recommended + doc: | + name/manufacturer/model/etc. information. + time_per_channel: + unit: NX_TIME + exists: ['min', '0'] + doc: | + For a time-of-flight detector this is the scaling + factor to convert from the numeric value reported to + the flight time for a given measurement. + (NXdetector_module): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + Many detectors consist of multiple smaller modules that are + operated in sync and store their data in a common dataset. + To allow consistent parsing of the experimental geometry, + this application definiton requires all detectors to + define a detector module, even if there is only one. + + This group specifies the hyperslab of data in the data + array associated with the detector that contains the + data for this module. If the module is associated with + a full data array, rather than with a hyperslab within + a larger array, then a single module should be defined, + spanning the entire array. + + Note, the pixel size is given as values in the array + fast_pixel_direction and slow_pixel_direction. + data_origin(NX_INT): + doc: | + A dimension-2 or dimension-3 field which gives the indices + of the origin of the hyperslab of data for this module in the + main area detector image in the parent NXdetector module. + + The data_origin is 0-based. + + The frame number dimension (nP) is omitted. Thus the + data_origin field for a dimension-2 dataset with indices (nP, i, j) + will be an array with indices (i, j), and for a dimension-3 + dataset with indices (nP, i, j, k) will be an array with indices + (i, j, k). + + The :ref:`order ` of indices (i, j + or i, j, k) is slow to fast. + data_size(NX_INT): + doc: | + Two or three values for the size of the module in pixels in + each direction. Dimensionality and order of indices is the + same as for data_origin. + data_stride(NX_INT): + exists: ['min', '0'] + doc: | + Two or three values for the stride of the module in pixels in + each direction. By default the stride is [1,1] or [1,1,1], + and this is the most likely case. This optional field is + included for completeness. + module_offset(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0'] + doc: | + Offset of the module in regards to the origin of the detector in an + arbitrary direction. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + \@offset: + type: NX_NUMBER + \@depends_on: + fast_pixel_direction(NX_NUMBER): + unit: NX_LENGTH + doc: | + Values along the direction of :ref:`fastest varying ` + pixel direction. The direction itself is given through the vector + attribute. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + \@offset: + type: NX_NUMBER + \@depends_on: + slow_pixel_direction(NX_NUMBER): + unit: NX_LENGTH + doc: | + Values along the direction of :ref:`slowest varying ` + pixel direction. The direction itself is given through the vector + attribute. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + \@offset: + type: NX_NUMBER + \@depends_on: + distance(NX_FLOAT): + unit: NX_LENGTH + exists: recommended + doc: | + Distance from the sample to the beam center. + Normally this value is for guidance only, the proper + geometry can be found following the depends_on axis chain, + But in appropriate cases where the dectector distance + to the sample is observable independent of the axis + chain, that may take precedence over the axis chain + calculation. + distance_derived(NX_BOOLEAN): + exists: recommended + doc: | + Boolean to indicate if the distance is a derived, rather than + a primary observation. If distance_derived true or is not specified, + the distance is assumed to be derived from detector axis + specifications. + dead_time(NX_FLOAT): + unit: NX_TIME + exists: ['min', '0'] + doc: | + Detector dead time. + count_time(NX_NUMBER): + unit: NX_TIME + exists: recommended + doc: | + Elapsed actual counting time. + beam_center_derived(NX_BOOLEAN): + exists: optional + doc: | + Boolean to indicate if the distance is a derived, rather than + a primary observation. If true or not provided, that value of + beam_center_derived is assumed to be true. + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + exists: recommended + doc: | + This is the x position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + exists: recommended + doc: | + This is the y position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + angular_calibration_applied(NX_BOOLEAN): + exists: ['min', '0'] + doc: | + True when the angular calibration has been applied in the + electronics, false otherwise. + angular_calibration(NX_FLOAT): + exists: ['min', '0'] + doc: | + Angular calibration data. + dimensions: + rank: dataRank + dim: [[1, i], [2, j], [3, k]] + dim_parameters: + required: ['false'] + flatfield_applied(NX_BOOLEAN): + exists: ['min', '0'] + doc: | + True when the flat field correction has been applied in the + electronics, false otherwise. + flatfield(NX_NUMBER): + exists: ['min', '0'] + doc: | + Flat field correction data. If provided, it is recommended + that it be compressed. + dimensions: + rank: dataRank + dim: [[1, i], [2, j], [3, k]] + dim_parameters: + required: ['false'] + flatfield_error(NX_NUMBER): + exists: ['min', '0', 'max', '0'] + doc: | + *** Deprecated form. Use plural form *** + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + dimensions: + rank: dataRank + dim: [[1, i], [2, j], [3, k]] + dim_parameters: + required: ['false'] + flatfield_errors(NX_NUMBER): + exists: ['min', '0'] + doc: | + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + dimensions: + rank: dataRank + dim: [[1, i], [2, j], [3, k]] + dim_parameters: + required: ['false'] + pixel_mask_applied(NX_BOOLEAN): + exists: ['min', '0'] + doc: | + True when the pixel mask correction has been applied in the + electronics, false otherwise. + pixel_mask(NX_INT): + exists: recommended + doc: | + The 32-bit pixel mask for the detector. Can be either one mask + for the whole dataset (i.e. an array with indices i, j) or + each frame can have its own mask (in which case it would be + an array with indices nP, i, j). + + Contains a bit field for each pixel to signal dead, + blind, high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + * bit 0: gap (pixel with no sensor) + * bit 1: dead + * bit 2: under-responding + * bit 3: over-responding + * bit 4: noisy + * bit 5: -undefined- + * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) + * bit 7: -undefined- + * bit 8: user defined mask (e.g. around beamstop) + * bits 9-30: -undefined- + * bit 31: virtual pixel (corner pixel with interpolated value) + + Normal data analysis software would not take pixels into account + when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper + two bytes would indicate special pixel properties that normally + would not be a sole reason to reject the intensity value (unless + lower bits are set. + + If the full bit depths is not required, providing a + mask with fewer bits is permissible. + + If needed, additional pixel masks can be specified by + including additional entries named pixel_mask_N, where + N is an integer. For example, a general bad pixel mask + could be specified in pixel_mask that indicates noisy + and dead pixels, and an additional pixel mask from + experiment-specific shadowing could be specified in + pixel_mask_2. The cumulative mask is the bitwise OR + of pixel_mask and any pixel_mask_N entries. + + If provided, it is recommended that it be compressed. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + countrate_correction_applied(NX_BOOLEAN): + exists: ['min', '0'] + doc: | + Counting detectors usually are not able to measure all incoming particles, + especially at higher count-rates. Count-rate correction is applied to + account for these errors. + + True when count-rate correction has been applied, false otherwise. + countrate_correction_lookup_table(NX_NUMBER): + doc: | + The countrate_correction_lookup_table defines the LUT used for count-rate + correction. It maps a measured count :math:`c` to its corrected value + :math:`countrate\_correction\_lookup\_table[c]`. + + :math:`m` denotes the length of the table. + dimensions: + rank: 1 + dim: [[1, m]] + virtual_pixel_interpolation_applied(NX_BOOLEAN): + exists: ['min', '0'] + doc: | + True when virtual pixel interpolation has been applied, false otherwise. + + When virtual pixel interpolation is applied, values of some pixels may + contain interpolated values. For example, to account for space between + readout chips on a module, physical pixels on edges and corners between + chips may have larger sensor areas and counts may be distributed between + their logical pixels. + bit_depth_readout(NX_INT): + exists: recommended + doc: | + How many bits the electronics record per pixel. + detector_readout_time(NX_FLOAT): + unit: NX_TIME + exists: ['min', '0'] + doc: | + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + frame_time(NX_FLOAT): + unit: NX_TIME + exists: ['min', '0'] + doc: | + This is time for each frame. This is exposure_time + readout + time. + gain_setting(NX_CHAR): + exists: ['min', '0'] + doc: | + The gain setting of the detector. This influences + background. This is a detector-specific value meant + to document the gain setting of the detector during + data collection, for detectors with multiple + available gain settings. + + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low`` + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. + saturation_value(NX_NUMBER): + exists: ['min', '0'] + doc: | + The value at which the detector goes into saturation. + Data above this value is known to be invalid. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + underload_value(NX_NUMBER): + exists: ['min', '0'] + doc: | + The lowest value at which pixels for this detector + would be reasonably be measured. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + sensor_material(NX_CHAR): + exists: ['min', '1'] + doc: | + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the name of this converter material. + sensor_thickness(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. This is the thickness of this + converter material. + threshold_energy(NX_FLOAT): + unit: NX_ENERGY + exists: ['min', '0'] + doc: | + Single photon counter detectors can be adjusted for a certain + energy range in which they work optimally. This is the energy + setting for this. If the detector supports multiple thresholds, + this is an array. + type: + exists: ['min', '0'] + doc: | + Description of type such as scintillator, + ccd, pixel, image + plate, CMOS, ... + (NXbeam): + exists: ['min', '1'] + \@flux: + exists: optional + doc: | + Which field contains the measured flux. One of ``flux``, + ``total_flux``, ``flux_integrated``, or ``total_flux_integrated``. + + Alternatively, the name being indicated could be a link + to a dataset in an NXmonitor group that records per shot beam data. + incident_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + exists: ['min', '1'] + doc: | + In the case of a monchromatic beam this is the scalar + wavelength. + + Several other use cases are permitted, depending on the + presence or absence of other incident_wavelength_X + fields. + + In the case of a polychromatic beam this is an array of + length **m** of wavelengths, with the relative weights + in ``incident_wavelength_weights``. + + In the case of a monochromatic beam that varies shot- + to-shot, this is an array of wavelengths, one for each + recorded shot. Here, ``incident_wavelength_weights`` and + incident_wavelength_spread are not set. + + In the case of a polychromatic beam that varies shot-to- + shot, this is an array of length **m** with the relative + weights in ``incident_wavelength_weights`` as a 2D array. + + In the case of a polychromatic beam that varies shot-to- + shot and where the channels also vary, this is a 2D array + of dimensions **nP** by **m** (slow to fast) with the + relative weights in ``incident_wavelength_weights`` as a 2D + array. + + Note, :ref:`variants ` are a good way + to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value wavelength value is + available along with the original spectrum from which it + was calibrated. + incident_wavelength_weight(NX_FLOAT): + exists: ['min', '0'] + deprecated: | + use incident_wavelength_weights, see https://github.com/nexusformat/definitions/issues/837 + doc: | + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in incident_wavelength. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **nP** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in incident_wavelength. + incident_wavelength_weights(NX_FLOAT): + exists: ['min', '0'] + doc: | + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``incident_wavelength``. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **np** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in ``incident_wavelength``. + incident_wavelength_spread(NX_FLOAT): + unit: NX_WAVELENGTH + exists: ['min', '0'] + doc: | + The wavelength spread FWHM for the corresponding + wavelength(s) in incident_wavelength. + + In the case of shot-to-shot variation in the wavelength + spread, this is a 2D array of dimension **nP** by + **m** (slow to fast) of the spreads of the + corresponding wavelengths in incident_wavelength. + incident_wavelength_spectrum(NXdata): + exists: ['min', '0'] + doc: | + This group is intended for use cases that do not fit the + :ref:`incident_wavelength ` + and + :ref:`incident_wavelength_weights ` + fields above, perhaps for example a 2D spectrometer. + flux(NX_FLOAT): + unit: NX_FLUX + exists: ['min', '0'] + doc: | + Flux density incident on beam plane area in photons + per second per unit area. + + In the case of a beam that varies in flux shot-to-shot, + this is an array of values, one for each recorded shot. + total_flux(NX_FLOAT): + unit: NX_FREQUENCY + exists: ['min', '0'] + doc: | + Flux incident on beam plane in photons per second. In other words + this is the :ref:`flux ` integrated + over area. + + Useful where spatial beam profiles are not known. + + In the case of a beam that varies in total flux shot-to-shot, + this is an array of values, one for each recorded shot. + flux_integrated(NX_FLOAT): + unit: NX_PER_AREA + exists: ['min', '0'] + doc: | + Flux density incident on beam plane area in photons + per unit area. In other words this is the :ref:`flux ` + integrated over time. + + Useful where temporal beam profiles of flux are not known. + + In the case of a beam that varies in flux shot-to-shot, + this is an array of values, one for each recorded shot. + total_flux_integrated(NX_FLOAT): + unit: NX_DIMENSIONLESS + exists: ['min', '0'] + doc: | + Flux incident on beam plane in photons. In other words this is the :ref:`flux ` + integrated over time and area. + + Useful where temporal beam profiles of flux are not known. + + In the case of a beam that varies in total flux shot-to-shot, + this is an array of values, one for each recorded shot. + incident_beam_size(NX_FLOAT): + unit: NX_LENGTH + exists: recommended + doc: | + Two-element array of FWHM (if Gaussian or Airy function) or + diameters (if top hat) or widths (if rectangular) of the beam + in the order x, y + dimensions: + rank: 1 + dim: [[1, 2]] + profile(NX_CHAR): + exists: recommended + doc: | + The beam profile, Gaussian, Airy function, top-hat or + rectangular. The profile is given in the plane of + incidence of the beam on the sample. + enumeration: [Gaussian, Airy, top-hat, rectangular] + incident_polarisation_stokes(NX_NUMBER): + exists: optional + deprecated: | + use incident_polarization_stokes, see https://github.com/nexusformat/definitions/issues/708 + doc: | + Polarization vector on entering beamline + component using Stokes notation + dimensions: + rank: 2 + dim: [[1, nP], [2, 4]] + incident_polarization_stokes(NX_NUMBER): + exists: recommended + doc: | + Polarization vector on entering beamline + component using Stokes notation. See + incident_polarization_stokes in :ref:`NXbeam` + dimensions: + rank: 2 + dim: [[1, nP], [2, 4]] + (NXsource): + doc: | + The neutron or x-ray storage ring/facility. Note, the NXsource base class + has many more fields available, but at present we only require the name. + name: + exists: ['min', '1'] + doc: | + Name of source. Consistency with the naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html + controlled vocabulary is highly recommended. + \@short_name: + exists: optional + doc: | + short name for source, perhaps the acronym + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3fbd4ec8b2d4a32359640fb344fe602982a5bb6a32465e0f51558219b29a3166 +# +# +# +# +# +# +# +# These symbols will be used below to coordinate datasets +# with the same shape. Most MX x-ray detectors will produce +# two-dimensional images. Some will produce three-dimensional +# images, using one of the indices to select a detector module. +# +# +# Rank of the ``data`` field +# +# +# Number of scan points +# +# +# Number of detector pixels in the slowest direction +# +# +# Number of detector pixels in the second slowest direction +# +# +# Number of detector pixels in the third slowest direction +# +# +# Number of channels in the incident beam spectrum, if known +# +# +# +# An array of the hierarchical levels of the parents of detector +# elements or groupings of detector elements. +# A top-level element or grouping has parent level -1. +# +# +# +# +# +# functional application definition for macromolecular crystallography +# +# +# +# +# +# Note, it is recommended that ``file_name`` and ``file_time`` are included +# as attributes at the root of a file that includes :ref:`NXmx`. See +# :ref:`NXroot`. +# +# +# +# +# Describes the version of the NXmx definition used to write this data. +# This must be a text (not numerical) representation. Such as:: +# +# @version="1.0" +# +# +# +# +# +# +# +# +# +# +# ISO 8601 time/date of the first data point collected in UTC, +# using the Z suffix to avoid confusion with local time. +# Note that the time zone of the beamline should be provided in +# NXentry/NXinstrument/time_zone. +# +# +# +# +# +# ISO 8601 time/date of the last data point collected in UTC, +# using the Z suffix to avoid confusion with local time. +# Note that the time zone of the beamline should be provided in +# NXentry/NXinstrument/time_zone. This field should only be +# filled when the value is accurately observed. If the data +# collection aborts or otherwise prevents accurate recording of +# the end_time, this field should be omitted. +# +# +# +# +# +# ISO 8601 time/date of the last data point collected in UTC, +# using the Z suffix to avoid confusion with local time. +# Note that the time zone of the beamline should be provided in +# NXentry/NXinstrument/time_zone. This field may be filled +# with a value estimated before an observed value is available. +# +# +# +# +# NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# For a dimension-2 detector, the rank of the data array will be 3. +# For a dimension-3 detector, the rank of the data array will be 4. +# This allows for the introduction of the frame number as the +# first index. +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# This is a requirement to describe for any scan experiment. +# +# The axis on which the sample position depends may be stored +# anywhere, but is normally stored in the NXtransformations +# group within the NXsample group. +# +# If there is no goniometer, e.g. with a jet, depends_on +# should be set to "." +# +# +# +# +# +# This is the recommended location for sample goniometer +# and other related axes. +# +# This is a requirement to describe for any scan experiment. +# The reason it is optional is mainly to accommodate XFEL +# single shot exposures. +# +# Use of the depends_on field and the NXtransformations group is +# strongly recommended. As noted above this should be an absolute +# requirement to have for any scan experiment. +# +# The reason it is optional is mainly to accommodate XFEL +# single shot exposures. +# +# +# +# +# +# +# +# +# +# +# +# +# Name of instrument. Consistency with the controlled +# vocabulary beamline naming in +# https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html +# and +# https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html +# is highly recommended. +# +# +# Short name for instrument, perhaps the acronym. +# +# +# +# +# +# ISO 8601 time_zone offset from UTC. +# +# +# +# +# +# +# +# +# +# Optional logical grouping of detectors. +# +# Each detector is represented as an NXdetector +# with its own detector data array. Each detector data array +# may be further decomposed into array sections by use of +# NXdetector_module groups. Detectors can be grouped logically +# together using NXdetector_group. Groups can be further grouped +# hierarchically in a single NXdetector_group (for example, if +# there are multiple detectors at an endstation or multiple +# endstations at a facility). Alternatively, multiple +# NXdetector_groups can be provided. +# +# The groups are defined hierarchically, with names given +# in the group_names field, unique identifying indices given +# in the field group_index, and the level in the hierarchy +# given in the group_parent field. For example if an x-ray +# detector group, DET, consists of four detectors in a +# rectangular array:: +# +# DTL DTR +# DLL DLR +# +# We could have:: +# +# group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] +# group_index: [1, 2, 3, 4, 5] +# group_parent: [-1, 1, 1, 1, 1] +# +# +# +# +# +# An array of the names of the detectors or the names of +# hierarchical groupings of detectors. +# +# +# +# +# +# An array of unique identifiers for detectors or groupings +# of detectors. +# +# Each ID is a unique ID for the corresponding detector or group +# named in the field group_names. The IDs are positive integers +# starting with 1. +# +# +# +# +# +# +# An array of the hierarchical levels of the parents of detectors +# or groupings of detectors. +# +# A top-level grouping has parent level -1. +# +# +# +# +# +# +# Normally the detector group will have the name ``detector``. +# However, in the case of multiple detectors, each detector +# needs a uniquely named NXdetector. +# +# +# +# +# NeXus path to the detector positioner axis that most directly +# supports the detector. In the case of a single-module +# detector, the detector axis chain may start here. +# +# +# +# +# +# Location for axes (transformations) to do with the +# detector. In the case of a single-module detector, the +# axes of the detector axis chain may be stored here. +# +# +# +# +# +# Suggested container for detailed non-standard detector +# information like corrections applied automatically or +# performance settings. +# +# +# +# +# +# For a dimension-2 detector, the rank of the data array will be 3. +# For a dimension-3 detector, the rank of the data array will be 4. +# This allows for the introduction of the frame number as the +# first index. +# +# +# +# +# +# +# +# +# +# +# +# name/manufacturer/model/etc. information. +# +# +# +# +# +# For a time-of-flight detector this is the scaling +# factor to convert from the numeric value reported to +# the flight time for a given measurement. +# +# +# +# +# +# Many detectors consist of multiple smaller modules that are +# operated in sync and store their data in a common dataset. +# To allow consistent parsing of the experimental geometry, +# this application definiton requires all detectors to +# define a detector module, even if there is only one. +# +# This group specifies the hyperslab of data in the data +# array associated with the detector that contains the +# data for this module. If the module is associated with +# a full data array, rather than with a hyperslab within +# a larger array, then a single module should be defined, +# spanning the entire array. +# +# Note, the pixel size is given as values in the array +# fast_pixel_direction and slow_pixel_direction. +# +# +# +# A dimension-2 or dimension-3 field which gives the indices +# of the origin of the hyperslab of data for this module in the +# main area detector image in the parent NXdetector module. +# +# The data_origin is 0-based. +# +# The frame number dimension (nP) is omitted. Thus the +# data_origin field for a dimension-2 dataset with indices (nP, i, j) +# will be an array with indices (i, j), and for a dimension-3 +# dataset with indices (nP, i, j, k) will be an array with indices +# (i, j, k). +# +# The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j +# or i, j, k) is slow to fast. +# +# +# +# +# Two or three values for the size of the module in pixels in +# each direction. Dimensionality and order of indices is the +# same as for data_origin. +# +# +# +# +# Two or three values for the stride of the module in pixels in +# each direction. By default the stride is [1,1] or [1,1,1], +# and this is the most likely case. This optional field is +# included for completeness. +# +# +# +# +# +# Offset of the module in regards to the origin of the detector in an +# arbitrary direction. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` +# pixel direction. The direction itself is given through the vector +# attribute. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Values along the direction of :ref:`slowest varying <Design-ArrayStorageOrder>` +# pixel direction. The direction itself is given through the vector +# attribute. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Distance from the sample to the beam center. +# Normally this value is for guidance only, the proper +# geometry can be found following the depends_on axis chain, +# But in appropriate cases where the dectector distance +# to the sample is observable independent of the axis +# chain, that may take precedence over the axis chain +# calculation. +# +# +# +# +# +# Boolean to indicate if the distance is a derived, rather than +# a primary observation. If distance_derived true or is not specified, +# the distance is assumed to be derived from detector axis +# specifications. +# +# +# +# +# +# Detector dead time. +# +# +# +# +# +# Elapsed actual counting time. +# +# +# +# +# +# Boolean to indicate if the distance is a derived, rather than +# a primary observation. If true or not provided, that value of +# beam_center_derived is assumed to be true. +# +# +# +# +# +# +# +# This is the x position where the direct beam would hit the +# detector. This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels as +# documented by the units attribute. Normally, this should +# be derived from the axis chain, but the direct specification +# may take precedence if it is not a derived quantity. +# +# +# +# +# +# This is the y position where the direct beam would hit the +# detector. This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels as +# documented by the units attribute. Normally, this should +# be derived from the axis chain, but the direct specification +# may take precedence if it is not a derived quantity. +# +# +# +# +# +# True when the angular calibration has been applied in the +# electronics, false otherwise. +# +# +# +# +# Angular calibration data. +# +# +# +# +# +# +# +# +# +# True when the flat field correction has been applied in the +# electronics, false otherwise. +# +# +# +# +# +# Flat field correction data. If provided, it is recommended +# that it be compressed. +# +# +# +# +# +# +# +# +# +# +# +# *** Deprecated form. Use plural form *** +# Errors of the flat field correction data. If provided, it is recommended +# that it be compressed. +# +# +# +# +# +# +# +# +# +# +# Errors of the flat field correction data. If provided, it is recommended +# that it be compressed. +# +# +# +# +# +# +# +# +# +# +# True when the pixel mask correction has been applied in the +# electronics, false otherwise. +# +# +# +# +# +# The 32-bit pixel mask for the detector. Can be either one mask +# for the whole dataset (i.e. an array with indices i, j) or +# each frame can have its own mask (in which case it would be +# an array with indices nP, i, j). +# +# Contains a bit field for each pixel to signal dead, +# blind, high or otherwise unwanted or undesirable pixels. +# They have the following meaning: +# +# * bit 0: gap (pixel with no sensor) +# * bit 1: dead +# * bit 2: under-responding +# * bit 3: over-responding +# * bit 4: noisy +# * bit 5: -undefined- +# * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) +# * bit 7: -undefined- +# * bit 8: user defined mask (e.g. around beamstop) +# * bits 9-30: -undefined- +# * bit 31: virtual pixel (corner pixel with interpolated value) +# +# Normal data analysis software would not take pixels into account +# when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper +# two bytes would indicate special pixel properties that normally +# would not be a sole reason to reject the intensity value (unless +# lower bits are set. +# +# If the full bit depths is not required, providing a +# mask with fewer bits is permissible. +# +# If needed, additional pixel masks can be specified by +# including additional entries named pixel_mask_N, where +# N is an integer. For example, a general bad pixel mask +# could be specified in pixel_mask that indicates noisy +# and dead pixels, and an additional pixel mask from +# experiment-specific shadowing could be specified in +# pixel_mask_2. The cumulative mask is the bitwise OR +# of pixel_mask and any pixel_mask_N entries. +# +# If provided, it is recommended that it be compressed. +# +# +# +# +# +# +# +# +# Counting detectors usually are not able to measure all incoming particles, +# especially at higher count-rates. Count-rate correction is applied to +# account for these errors. +# +# True when count-rate correction has been applied, false otherwise. +# +# +# +# +# The countrate_correction_lookup_table defines the LUT used for count-rate +# correction. It maps a measured count :math:`c` to its corrected value +# :math:`countrate\_correction\_lookup\_table[c]`. +# +# :math:`m` denotes the length of the table. +# +# +# +# +# +# +# +# True when virtual pixel interpolation has been applied, false otherwise. +# +# When virtual pixel interpolation is applied, values of some pixels may +# contain interpolated values. For example, to account for space between +# readout chips on a module, physical pixels on edges and corners between +# chips may have larger sensor areas and counts may be distributed between +# their logical pixels. +# +# +# +# +# +# How many bits the electronics record per pixel. +# +# +# +# +# +# Time it takes to read the detector (typically milliseconds). +# This is important to know for time resolved experiments. +# +# +# +# +# +# This is time for each frame. This is exposure_time + readout +# time. +# +# +# +# +# +# The gain setting of the detector. This influences +# background. This is a detector-specific value meant +# to document the gain setting of the detector during +# data collection, for detectors with multiple +# available gain settings. +# +# Examples of gain settings include: +# +# * ``standard`` +# * ``fast`` +# * ``auto`` +# * ``high`` +# * ``medium`` +# * ``low`` +# * ``mixed high to medium`` +# * ``mixed medium to low`` +# +# Developers are encouraged to use one of these terms, or to submit +# additional terms to add to the list. +# +# +# +# +# +# The value at which the detector goes into saturation. +# Data above this value is known to be invalid. +# +# For example, given a saturation_value and an underload_value, +# the valid pixels are those less than or equal to the +# saturation_value and greater than or equal to the underload_value. +# +# +# +# +# +# The lowest value at which pixels for this detector +# would be reasonably be measured. +# +# For example, given a saturation_value and an underload_value, +# the valid pixels are those less than or equal to the +# saturation_value and greater than or equal to the underload_value. +# +# +# +# +# +# At times, radiation is not directly sensed by the detector. +# Rather, the detector might sense the output from some +# converter like a scintillator. +# This is the name of this converter material. +# +# +# +# +# +# At times, radiation is not directly sensed by the detector. +# Rather, the detector might sense the output from some +# converter like a scintillator. This is the thickness of this +# converter material. +# +# +# +# +# +# Single photon counter detectors can be adjusted for a certain +# energy range in which they work optimally. This is the energy +# setting for this. If the detector supports multiple thresholds, +# this is an array. +# +# +# +# +# +# Description of type such as scintillator, +# ccd, pixel, image +# plate, CMOS, ... +# +# +# +# +# +# +# Which field contains the measured flux. One of ``flux``, +# ``total_flux``, ``flux_integrated``, or ``total_flux_integrated``. +# +# Alternatively, the name being indicated could be a link +# to a dataset in an NXmonitor group that records per shot beam data. +# +# +# +# +# In the case of a monchromatic beam this is the scalar +# wavelength. +# +# Several other use cases are permitted, depending on the +# presence or absence of other incident_wavelength_X +# fields. +# +# In the case of a polychromatic beam this is an array of +# length **m** of wavelengths, with the relative weights +# in ``incident_wavelength_weights``. +# +# In the case of a monochromatic beam that varies shot- +# to-shot, this is an array of wavelengths, one for each +# recorded shot. Here, ``incident_wavelength_weights`` and +# incident_wavelength_spread are not set. +# +# In the case of a polychromatic beam that varies shot-to- +# shot, this is an array of length **m** with the relative +# weights in ``incident_wavelength_weights`` as a 2D array. +# +# In the case of a polychromatic beam that varies shot-to- +# shot and where the channels also vary, this is a 2D array +# of dimensions **nP** by **m** (slow to fast) with the +# relative weights in ``incident_wavelength_weights`` as a 2D +# array. +# +# Note, :ref:`variants <Design-Variants>` are a good way +# to represent several of these use cases in a single dataset, +# e.g. if a calibrated, single-value wavelength value is +# available along with the original spectrum from which it +# was calibrated. +# +# +# +# +# +# In the case of a polychromatic beam this is an array of +# length **m** of the relative weights of the corresponding +# wavelengths in incident_wavelength. +# +# In the case of a polychromatic beam that varies shot-to- +# shot, this is a 2D array of dimensions **nP** by **m** +# (slow to fast) of the relative weights of the +# corresponding wavelengths in incident_wavelength. +# +# +# +# +# In the case of a polychromatic beam this is an array of +# length **m** of the relative weights of the corresponding +# wavelengths in ``incident_wavelength``. +# +# In the case of a polychromatic beam that varies shot-to- +# shot, this is a 2D array of dimensions **np** by **m** +# (slow to fast) of the relative weights of the +# corresponding wavelengths in ``incident_wavelength``. +# +# +# +# +# +# The wavelength spread FWHM for the corresponding +# wavelength(s) in incident_wavelength. +# +# In the case of shot-to-shot variation in the wavelength +# spread, this is a 2D array of dimension **nP** by +# **m** (slow to fast) of the spreads of the +# corresponding wavelengths in incident_wavelength. +# +# +# +# +# +# This group is intended for use cases that do not fit the +# :ref:`incident_wavelength </NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength-field>` +# and +# :ref:`incident_wavelength_weights </NXmx/ENTRY/INSTRUMENT/BEAM/incident_wavelength_weights-field>` +# fields above, perhaps for example a 2D spectrometer. +# +# +# +# +# +# Flux density incident on beam plane area in photons +# per second per unit area. +# +# In the case of a beam that varies in flux shot-to-shot, +# this is an array of values, one for each recorded shot. +# +# +# +# +# +# Flux incident on beam plane in photons per second. In other words +# this is the :ref:`flux </NXmx/ENTRY/INSTRUMENT/BEAM/flux-field>` integrated +# over area. +# +# Useful where spatial beam profiles are not known. +# +# In the case of a beam that varies in total flux shot-to-shot, +# this is an array of values, one for each recorded shot. +# +# +# +# +# +# Flux density incident on beam plane area in photons +# per unit area. In other words this is the :ref:`flux </NXmx/ENTRY/INSTRUMENT/BEAM/flux-field>` +# integrated over time. +# +# Useful where temporal beam profiles of flux are not known. +# +# In the case of a beam that varies in flux shot-to-shot, +# this is an array of values, one for each recorded shot. +# +# +# +# +# +# Flux incident on beam plane in photons. In other words this is the :ref:`flux </NXmx/ENTRY/INSTRUMENT/BEAM/flux-field>` +# integrated over time and area. +# +# Useful where temporal beam profiles of flux are not known. +# +# In the case of a beam that varies in total flux shot-to-shot, +# this is an array of values, one for each recorded shot. +# +# +# +# +# +# Two-element array of FWHM (if Gaussian or Airy function) or +# diameters (if top hat) or widths (if rectangular) of the beam +# in the order x, y +# +# +# +# +# +# +# +# +# The beam profile, Gaussian, Airy function, top-hat or +# rectangular. The profile is given in the plane of +# incidence of the beam on the sample. +# +# +# +# +# +# +# +# +# +# +# Polarization vector on entering beamline +# component using Stokes notation +# +# +# +# +# +# +# +# +# Polarization vector on entering beamline +# component using Stokes notation. See +# incident_polarization_stokes in :ref:`NXbeam` +# +# +# +# +# +# +# +# +# +# +# The neutron or x-ray storage ring/facility. Note, the NXsource base class +# has many more fields available, but at present we only require the name. +# +# +# +# Name of source. Consistency with the naming in +# https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html +# controlled vocabulary is highly recommended. +# +# +# short name for source, perhaps the acronym +# +# +# +# +# diff --git a/applications/nyaml/NXrefscan.yaml b/applications/nyaml/NXrefscan.yaml new file mode 100644 index 0000000000..545d01fd6e --- /dev/null +++ b/applications/nyaml/NXrefscan.yaml @@ -0,0 +1,197 @@ +category: application +doc: | + This is an application definition for a monochromatic scanning reflectometer. + + It does not have the information to calculate the resolution + since it does not have any apertures. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXrefscan(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXrefscan] + (NXinstrument)instrument: + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + (NXmonochromator)monochromator: + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + (NXdetector): + data(NX_INT): + signal: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample)sample: + name: + doc: | + Descriptive name of sample + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + (NXmonitor)control: + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_FLOAT): + unit: NX_ANY + doc: | + Monitor counts for each step + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + polar_angle(link): + target: /NXentry/NXinstrument/NXdetector/polar_angle + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2292093a2a73147dd621497414bfff4f52e5a2103a0c4b1e5a119e15e005b78f +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# This is an application definition for a monochromatic scanning reflectometer. +# +# It does not have the information to calculate the resolution +# since it does not have any apertures. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# Monitor counts for each step +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXreftof.yaml b/applications/nyaml/NXreftof.yaml new file mode 100644 index 0000000000..760c7023fe --- /dev/null +++ b/applications/nyaml/NXreftof.yaml @@ -0,0 +1,214 @@ +category: application +doc: | + This is an application definition for raw data from a TOF reflectometer. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + xSize: | + xSize description + ySize: | + ySize description + nTOF: | + nTOF description +type: group +NXreftof(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXreftof] + (NXinstrument)instrument: + name(NX_CHAR): + (NXdisk_chopper)chopper: + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance between chopper and sample + (NXdetector)detector: + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, xSize], [2, ySize], [3, nTOF]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 3 + doc: | + Array of time values for each bin in a time-of-flight + measurement + dimensions: + rank: 1 + dim: [[1, nTOF]] + distance(NX_FLOAT): + unit: NX_LENGTH + polar_angle(NX_FLOAT): + unit: NX_ANGLE + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + (NXsample)sample: + name: + doc: | + Descriptive name of sample + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + (NXmonitor)control: + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + unit: NX_ANY + doc: | + preset value for time or monitor + integral(NX_INT): + doc: | + Total integral monitor counts + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + doc: | + Time channels + data(NX_INT): + signal: 1 + doc: | + Monitor counts in each time channel + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 11c65854a466d2dce2e11e31861b9d33736ed082b3571645b0c3f1feebd16bbd +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# xSize description +# +# +# ySize description +# +# +# nTOF description +# +# +# This is an application definition for raw data from a TOF reflectometer. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# Distance between chopper and sample +# +# +# +# +# +# +# +# +# +# +# +# +# Array of time values for each bin in a time-of-flight +# measurement +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# Total integral monitor counts +# +# +# Time channels +# +# +# Monitor counts in each time channel +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXsas.yaml b/applications/nyaml/NXsas.yaml new file mode 100644 index 0000000000..2e160f0bbc --- /dev/null +++ b/applications/nyaml/NXsas.yaml @@ -0,0 +1,369 @@ +category: application +doc: | + Raw, monochromatic 2-D SAS data with an area detector. + + This is an application definition for raw data (not processed or reduced data) + from a 2-D small angle scattering instrument collected with a monochromatic + beam and an area detector. It is meant to be suitable both for neutron SANS + and X-ray SAXS data. + + It covers all raw data from any monochromatic SAS techniques that + use an area detector: SAS, WSAS, grazing incidence, GISAS + + It covers all raw data from any SAS techniques that use an area detector and + a monochromatic beam. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate fields with the same shape. + nXPixel: | + Number of pixels in x direction. + nYPixel: | + Number of pixels in y direction. +type: group +NXsas(NXobject): + (NXentry): + title: + exists: ['min', '0'] + start_time(NX_DATE_TIME): + exists: ['min', '0'] + end_time(NX_DATE_TIME): + exists: ['min', '0'] + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + enumeration: [NXsas] + (NXinstrument): + (NXsource): + type: + doc: | + Type of radiation source. + name: + exists: ['min', '0'] + doc: | + Name of the radiation source. + probe: + doc: | + Name of radiation probe, necessary to compute the sample contrast. + enumeration: [neutron, x-ray] + (NXmonochromator): + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + The wavelength (:math:`\lambda`) of the radiation. + wavelength_spread(NX_FLOAT): + exists: ['min', '0'] + doc: | + delta_lambda/lambda (:math:`\Delta\lambda/\lambda`): + Important for resolution calculations. + (NXcollimator): + exists: ['min', '0'] + (NXgeometry): + (NXshape): + shape(NX_CHAR): + enumeration: [nxcylinder, nxbox] + size(NX_FLOAT): + unit: NX_LENGTH + doc: | + The collimation length. + (NXdetector): + data(NX_NUMBER): + doc: | + This is area detector data, number of x-pixel versus + number of y-pixels. + + Since the beam center is to be determined as a step of data + reduction, it is not necessary to document or assume the position of + the beam center in acquired data. + + It is necessary to define which are the x and y directions, to coordinate + with the pixel size and compute Q. + dimensions: + rank: 2 + dim: [[1, nXPixel], [2, nYPixel]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + The distance between detector and sample. + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Physical size of a pixel in x-direction. + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Physical size of a pixel in y-direction. + polar_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + aequatorial_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0'] + doc: | + This is the x position where the direct beam would hit the detector. + This is a length, not a pixel position, and can be outside of the + actual detector. + + It is expected that data reduction will determine beam center from + the raw data, thus it is not required here. The instrument can + provide an initial or nominal value to advise data reduction. + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0'] + doc: | + This is the y position where the direct beam would hit the detector. + This is a length, not a pixel position, and can be outside of the + actual detector. + + It is expected that data reduction will determine beam center from + the raw data, thus it is not required here. The instrument can + provide an initial or nominal value to advise data reduction. + name(NX_CHAR): + doc: | + Name of the instrument actually used to perform the experiment. + (NXsample): + exists: ['min', '0'] + name: + doc: | + Descriptive name of sample. + aequatorial_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + (NXmonitor): + exists: ['min', '0'] + mode: + doc: | + Count to a preset value based on either clock time + (timer) or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + Preset value for time or monitor. + integral(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts. + (NXdata): + \@signal: + exists: optional + doc: | + Name the *plottable* field. The link here defines this name as + ``data``. + enumeration: [data] + data(link): + target: /NXentry/NXinstrument/NXdetector/data + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2aa6302899fe37644b84e8ae5fba65adf3e17563e6bf42afe1beee8007b93ff5 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate fields with the same shape. +# +# +# Number of pixels in x direction. +# +# +# Number of pixels in y direction. +# +# +# +# Raw, monochromatic 2-D SAS data with an area detector. +# +# This is an application definition for raw data (not processed or reduced data) +# from a 2-D small angle scattering instrument collected with a monochromatic +# beam and an area detector. It is meant to be suitable both for neutron SANS +# and X-ray SAXS data. +# +# It covers all raw data from any monochromatic SAS techniques that +# use an area detector: SAS, WSAS, grazing incidence, GISAS +# +# It covers all raw data from any SAS techniques that use an area detector and +# a monochromatic beam. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# Type of radiation source. +# +# +# Name of the radiation source. +# +# +# +# Name of radiation probe, necessary to compute the sample contrast. +# +# +# +# +# +# +# +# +# +# The wavelength (:math:`\lambda`) of the radiation. +# +# +# +# delta_lambda/lambda (:math:`\Delta\lambda/\lambda`): +# Important for resolution calculations. +# +# +# +# +# +# +# +# +# +# +# +# +# +# The collimation length. +# +# +# +# +# +# +# +# This is area detector data, number of x-pixel versus +# number of y-pixels. +# +# Since the beam center is to be determined as a step of data +# reduction, it is not necessary to document or assume the position of +# the beam center in acquired data. +# +# It is necessary to define which are the x and y directions, to coordinate +# with the pixel size and compute Q. +# +# +# +# +# +# +# +# The distance between detector and sample. +# +# +# Physical size of a pixel in x-direction. +# +# +# Physical size of a pixel in y-direction. +# +# +# +# +# +# +# +# This is the x position where the direct beam would hit the detector. +# This is a length, not a pixel position, and can be outside of the +# actual detector. +# +# It is expected that data reduction will determine beam center from +# the raw data, thus it is not required here. The instrument can +# provide an initial or nominal value to advise data reduction. +# +# +# +# +# This is the y position where the direct beam would hit the detector. +# This is a length, not a pixel position, and can be outside of the +# actual detector. +# +# It is expected that data reduction will determine beam center from +# the raw data, thus it is not required here. The instrument can +# provide an initial or nominal value to advise data reduction. +# +# +# +# +# Name of the instrument actually used to perform the experiment. +# +# +# +# +# Descriptive name of sample. +# +# +# +# +# +# +# Count to a preset value based on either clock time +# (timer) or received monitor counts (monitor). +# +# +# +# +# +# +# +# Preset value for time or monitor. +# +# +# Total integral monitor counts. +# +# +# +# +# +# Name the *plottable* field. The link here defines this name as +# ``data``. +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXsastof.yaml b/applications/nyaml/NXsastof.yaml new file mode 100644 index 0000000000..4a3530a29a --- /dev/null +++ b/applications/nyaml/NXsastof.yaml @@ -0,0 +1,312 @@ +category: application +doc: | + raw, 2-D SAS data with an area detector with a time-of-flight source + + It covers all raw data from any SAS techniques + that use an area detector + at a time-of-flight source. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nXPixel: | + nXPixel description + nYPixel: | + nYPixel description + nTOF: | + nTOF description +type: group +NXsastof(NXobject): + (NXentry): + \@entry: + doc: | + NeXus convention is to use "entry1", "entry2", ... for analysis software to locate each entry + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXsastof] + (NXinstrument)instrument: + (NXsource)source: + type: + doc: | + type of radiation source + name: + doc: | + Name of the radiation source + probe: + enumeration: [neutron, x-ray] + (NXcollimator)collimator: + (NXgeometry)geometry: + (NXshape)shape: + shape(NX_CHAR): + enumeration: [nxcylinder, nxbox] + size(NX_FLOAT): + unit: NX_LENGTH + doc: | + The collimation length + (NXdetector)detector: + data(NX_NUMBER): + signal: 1 + doc: | + This is area detector data, of number of x-pixel versus + number of y-pixels. Since the beam center is to be + determined as a step of data reduction, it is not necessary + to document or assume the position of the beam center in + acquired data. + dimensions: + rank: 3 + dim: [[1, nXPixel], [2, nYPixel], [3, nTOF]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, nTOF]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + The distance between detector and sample + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Physical size of a pixel in x-direction + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of a pixel in y direction + polar_angle(NX_FLOAT): + unit: NX_ANGLE + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + aequatorial_angle(NX_FLOAT): + unit: NX_ANGLE + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the x position where the direct beam would hit the detector. This is a + length, not a pixel position, and can be outside of the actual detector. + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the y position where the direct beam would hit the detector. This is a + length, not a pixel position, and can be outside of the actual detector. + name(NX_CHAR): + doc: | + Name of the instrument actually used to perform the experiment + (NXsample)sample: + name: + doc: | + Descriptive name of sample + aequatorial_angle(NX_FLOAT): + unit: NX_ANGLE + (NXmonitor)control: + mode: + doc: | + Count to a preset value based on either clock time (timer) or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_INT): + primary: 1 + signal: 1 + dimensions: + rank: 1 + dim: [[1, nTOF]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, nTOF]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 18b43c8a5ad4926ae6e06b953df9d44c87db9e7f47f4f7e99e072f3950620660 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# nXPixel description +# +# +# nYPixel description +# +# +# nTOF description +# +# +# +# raw, 2-D SAS data with an area detector with a time-of-flight source +# +# It covers all raw data from any SAS techniques +# that use an area detector +# at a time-of-flight source. +# +# +# +# NeXus convention is to use "entry1", "entry2", ... for analysis software to locate each entry +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# type of radiation source +# +# +# Name of the radiation source +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The collimation length +# +# +# +# +# +# +# +# This is area detector data, of number of x-pixel versus +# number of y-pixels. Since the beam center is to be +# determined as a step of data reduction, it is not necessary +# to document or assume the position of the beam center in +# acquired data. +# +# +# +# +# +# +# +# +# +# +# +# +# The distance between detector and sample +# +# +# Physical size of a pixel in x-direction +# +# +# Size of a pixel in y direction +# +# +# +# +# +# +# +# +# +# This is the x position where the direct beam would hit the detector. This is a +# length, not a pixel position, and can be outside of the actual detector. +# +# +# +# +# This is the y position where the direct beam would hit the detector. This is a +# length, not a pixel position, and can be outside of the actual detector. +# +# +# +# +# Name of the instrument actually used to perform the experiment +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) or received monitor counts (monitor). +# +# +# +# +# +# +# preset value for time or monitor +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXscan.yaml b/applications/nyaml/NXscan.yaml new file mode 100644 index 0000000000..38f6e0107c --- /dev/null +++ b/applications/nyaml/NXscan.yaml @@ -0,0 +1,181 @@ +category: application +doc: | + Application definition for a generic scan instrument. + + This definition is more an + example then a stringent definition as the content of a given NeXus scan file needs to + differ for different types of scans. This example definition shows a scan like done + on a rotation camera: the sample is rotated and a detector image, the rotation angle + and a monitor value is stored at each step in the scan. In the following, the symbol + ``NP`` is used to represent the number of scan points. These are the rules for + storing scan data in NeXus files which are implemented in this example: + + * Each value varied throughout a scan is stored as an array of + length ``NP`` at its respective location within the NeXus hierarchy. + * For area detectors, ``NP`` is the first dimension, + example for a detector of 256x256: ``data[NP,256,256]`` + * The NXdata group contains links to all variables varied in the scan and the data. + This to give an equivalent to the more familiar classical tabular representation of scans. + + These rules exist for a reason: HDF allows the first dimension of a data set to be + unlimited. This means the data can be appended too. Thus a NeXus file built according + to the rules given above can be used in the following way: + + * At the start of a scan, write all the static information. + * At each scan point, append new data from varied variables + and the detector to the file. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points + xDim: | + xDim description + yDim: | + yDim description +type: group +NXscan(NXobject): + (NXentry): + title: + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + definition(NX_CHAR): + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXscan] + (NXinstrument): + (NXdetector): + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, nP], [2, xDim], [3, yDim]] + (NXsample): + rotation_angle(NX_FLOAT): + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + (NXmonitor): + data(NX_INT): + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata): + data(link): + target: /NXentry/NXinstrument/NXdetector/data + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0a6ad9072ad7a42beaa653d148ef9e0187624de64ae1a25be57d67eebe991360 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# xDim description +# +# +# yDim description +# +# +# +# Application definition for a generic scan instrument. +# +# This definition is more an +# example then a stringent definition as the content of a given NeXus scan file needs to +# differ for different types of scans. This example definition shows a scan like done +# on a rotation camera: the sample is rotated and a detector image, the rotation angle +# and a monitor value is stored at each step in the scan. In the following, the symbol +# ``NP`` is used to represent the number of scan points. These are the rules for +# storing scan data in NeXus files which are implemented in this example: +# +# * Each value varied throughout a scan is stored as an array of +# length ``NP`` at its respective location within the NeXus hierarchy. +# * For area detectors, ``NP`` is the first dimension, +# example for a detector of 256x256: ``data[NP,256,256]`` +# * The NXdata group contains links to all variables varied in the scan and the data. +# This to give an equivalent to the more familiar classical tabular representation of scans. +# +# These rules exist for a reason: HDF allows the first dimension of a data set to be +# unlimited. This means the data can be appended too. Thus a NeXus file built according +# to the rules given above can be used in the following way: +# +# * At the start of a scan, write all the static information. +# * At each scan point, append new data from varied variables +# and the detector to the file. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXspe.yaml b/applications/nyaml/NXspe.yaml new file mode 100644 index 0000000000..7dfb5be0a6 --- /dev/null +++ b/applications/nyaml/NXspe.yaml @@ -0,0 +1,128 @@ +category: application +doc: | + NXSPE Inelastic Format. Application definition for NXSPE file format. +type: group +NXspe(NXobject): + (NXentry): + program_name: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + \@version: + enumeration: [NXspe] + (NXcollection)NXSPE_info: + fixed_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + The fixed energy used for this file. + ki_over_kf_scaling(NX_BOOLEAN): + doc: | + Indicates whether ki/kf scaling has been applied or not. + psi(NX_FLOAT): + unit: NX_ANGLE + doc: | + Orientation angle as expected in DCS-MSlice + (NXdata)data: + azimuthal(NX_FLOAT): + unit: NX_ANGLE + azimuthal_width(NX_FLOAT): + unit: NX_ANGLE + polar(NX_FLOAT): + unit: NX_ANGLE + polar_width(NX_FLOAT): + unit: NX_ANGLE + distance(NX_FLOAT): + unit: NX_LENGTH + data(NX_NUMBER): + error(NX_NUMBER): + energy(NX_FLOAT): + unit: NX_ENERGY + (NXinstrument): + name(NX_CHAR): + (NXfermi_chopper): + energy(NX_NUMBER): + unit: NX_ENERGY + (NXsample): + rotation_angle(NX_NUMBER): + unit: NX_ANGLE + seblock(NX_CHAR): + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# eec08fb3a92ba08c09d8ecb18e13c7703abf71c6e532786d2685d1c7979e52b3 +# +# +# +# +# NXSPE Inelastic Format. Application definition for NXSPE file format. +# +# +# +# Official NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# The fixed energy used for this file. +# +# +# Indicates whether ki/kf scaling has been applied or not. +# +# +# Orientation angle as expected in DCS-MSlice +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXsqom.yaml b/applications/nyaml/NXsqom.yaml new file mode 100644 index 0000000000..c29c5e622c --- /dev/null +++ b/applications/nyaml/NXsqom.yaml @@ -0,0 +1,211 @@ +category: application +doc: | + This is the application definition for S(Q,OM) processed data. + + As this kind of data is in + general not on a rectangular grid after data reduction, it is stored as Q,E positions plus their + intensity, table like. It is the task of a possible visualisation program to regrid this data in + a sensible way. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXsqom(NXobject): + (NXentry): + \@entry: + title: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXsqom] + (NXinstrument)instrument: + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + name(NX_CHAR): + doc: | + Name of the instrument from which this data was reduced. + (NXsample): + name: + doc: | + Descriptive name of sample + (NXprocess)reduction: + program(NX_CHAR): + version(NX_CHAR): + (NXparameters)input: + filenames(NX_CHAR): + doc: | + Raw data files used to generate this I(Q) + doc: | + Input parameters for the reduction program used + (NXparameters)output: + doc: | + Eventual output parameters from the data reduction program used + (NXdata): + data(NX_INT): + signal: 1 + doc: | + This is the intensity for each point in QE + dimensions: + rank: 1 + dim: [[1, nP]] + qx(NX_NUMBER): + axis: 1 + unit: NX_WAVENUMBER + doc: | + Positions for the first dimension of Q + dimensions: + rank: 1 + dim: [[1, nP]] + qy(NX_NUMBER): + axis: 1 + unit: NX_WAVENUMBER + doc: | + Positions for the the second dimension of Q + dimensions: + rank: 1 + dim: [[1, nP]] + qz(NX_NUMBER): + axis: 1 + unit: NX_WAVENUMBER + doc: | + Positions for the the third dimension of Q + dimensions: + rank: 1 + dim: [[1, nP]] + en(NX_FLOAT): + axis: 1 + unit: NX_ENERGY + doc: | + Values for the energy transfer for each point + dimensions: + rank: 1 + dim: [[1, nP]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c4bc88346556a87d052d23ac72e3681fbbc83804dd30c5cf7656e54595f43e97 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# This is the application definition for S(Q,OM) processed data. +# +# As this kind of data is in +# general not on a rectangular grid after data reduction, it is stored as Q,E positions plus their +# intensity, table like. It is the task of a possible visualisation program to regrid this data in +# a sensible way. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Name of the instrument from which this data was reduced. +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# Raw data files used to generate this I(Q) +# +# Input parameters for the reduction program used +# +# +# Eventual output parameters from the data reduction program used +# +# +# +# +# This is the intensity for each point in QE +# +# +# +# +# +# Positions for the first dimension of Q +# +# +# +# +# +# Positions for the the second dimension of Q +# +# +# +# +# +# Positions for the the third dimension of Q +# +# +# +# +# +# Values for the energy transfer for each point +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXstxm.yaml b/applications/nyaml/NXstxm.yaml new file mode 100644 index 0000000000..a2a6c1fc8b --- /dev/null +++ b/applications/nyaml/NXstxm.yaml @@ -0,0 +1,366 @@ +category: application +doc: | + Application definition for a STXM instrument. + + The interferometer + position measurements, monochromator photon energy values and + detector measurements are all treated as NXdetectors and stored + within the NXinstrument group as lists of values stored in + chronological order. The NXdata group then holds another version + of the data in a regular 3D array (NumE by NumY by NumX, for a + total of nP points in a sample image stack type scan). The former + data values should be stored with a minimum loss of precision, while + the latter values can be simplified and/or approximated in order to + fit the constraints of a regular 3D array. 'Line scans' and 'point spectra' + are just sample_image scan types with reduced dimensions in the same way + as single images have reduced E dimensions compared to image 'stacks'. +symbols: + doc: | + These symbols will be used below to coordinate the shapes of the datasets. + nP: | + Total number of scan points + nE: | + Number of photon energies scanned + nX: | + Number of pixels in X direction + nY: | + Number of pixels in Y direction + detectorRank: | + Rank of data array provided by the detector for a single measurement +type: group +NXstxm(NXobject): + (NXentry): + title: + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + definition(NX_CHAR): + exists: ['min', '1', 'max', '1'] + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXstxm] + (NXinstrument): + exists: ['min', '1', 'max', '1'] + (NXsource): + exists: ['min', '1', 'max', '1'] + type: + exists: ['min', '1', 'max', '1'] + name: + exists: ['min', '1', 'max', '1'] + probe: + exists: ['min', '1', 'max', '1'] + (NXmonochromator)monochromator: + exists: ['min', '1', 'max', '1'] + energy(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector): + exists: ['min', '1'] + data(NX_NUMBER): + dimensions: + rank: 1+detectorRank + doc: | + Detector data should be presented with the first dimension corresponding to the + scan point and subsequent dimensions corresponding to the output of the detector. + Detectors that provide more than one value per scan point should have + a data array of rank 1+d, where d is the dimensions of the array provided per + scan point. For example, an area detector should have an NXdetector data array + of 3 dimensions, with the first being the set of scan points and the latter + two being the x- and y- extent of the detector. + NOTE: For each dimension > 1 there must exist a dim section such as: + dim: [[1, nP]] + (NXdetector)sample_x: + exists: ['min', '0', 'max', '1'] + doc: | + Measurements of the sample position from the x-axis interferometer. + data(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector)sample_y: + exists: ['min', '0', 'max', '1'] + doc: | + Measurements of the sample position from the y-axis interferometer. + data(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector)sample_z: + exists: ['min', '0', 'max', '1'] + doc: | + Measurements of the sample position from the z-axis interferometer. + data(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample): + rotation_angle(NX_FLOAT): + (NXdata): + stxm_scan_type: + exists: ['min', '1', 'max', '1'] + doc: | + Label for typical scan types as a convenience for humans. + Each label corresponds to a specific set of axes being scanned + to produce a data array of shape: + + * sample point spectrum: (photon_energy,) + * sample line spectrum: (photon_energy, sample_y/sample_x) + * sample image: (sample_y, sample_x) + * sample image stack: (photon_energy, sample_y, sample_x) + * sample focus: (zoneplate_z, sample_y/sample_x) + * osa image: (osa_y, osa_x) + * osa focus: (zoneplate_z, osa_y/osa_x) + * detector image: (detector_y, detector_x) + + The "generic scan" string is to be used when none of the + other choices are appropriate. + enumeration: [sample point spectrum, sample line spectrum, sample image, sample image stack, sample focus, osa image, osa focus, detector image, generic scan] + data(NX_NUMBER): + signal: 1 + doc: | + Detectors that provide more than one value per scan point should be summarised + to a single value per scan point for this array in order to simplify plotting. + + Note that 'Line scans' and focus type scans measure along one spatial dimension + but are not restricted to being parallel to the X or Y axes. Such scans + should therefore use a single dimension for the positions along the spatial + line. The 'sample_x' and 'sample_y' fields should then contain lists of the + x- and y-positions and should both have the 'axis' attribute pointing to the same dimension. + energy(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + doc: | + List of photon energies of the X-ray beam. If scanned through multiple values, + then an 'axis' attribute will be required to link the field to the appropriate data array dimension. + dimensions: + rank: 1 + dim: [[1, nE]] + sample_y(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + doc: | + List of Y positions on the sample. If scanned through multiple values, + then an 'axis' attribute will be required to link the field to the appropriate data array dimension. + dimensions: + rank: 1 + dim: [[1, nY]] + sample_x(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + doc: | + List of X positions on the sample. If scanned through multiple values, + then an 'axis' attribute will be required to link the field to the appropriate data array dimension. + dimensions: + rank: 1 + dim: [[1, nX]] + (NXmonitor)control: + exists: ['min', '0', 'max', '1'] + data(NX_FLOAT): + doc: | + Values to use to normalise for time-variations in photon flux. Typically, the synchrotron storage ring + electron beam current is used as a proxy for the X-ray beam intensity. Array must have same shape as the + NXdata groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4a65935ad78db0a1652d7fceb67425791cfecf0a6a2f24683a5798f866c9d60c +# +# +# +# +# +# +# These symbols will be used below to coordinate the shapes of the datasets. +# +# +# Total number of scan points +# +# +# Number of photon energies scanned +# +# +# Number of pixels in X direction +# +# +# Number of pixels in Y direction +# +# +# Rank of data array provided by the detector for a single measurement +# +# +# +# Application definition for a STXM instrument. +# +# The interferometer +# position measurements, monochromator photon energy values and +# detector measurements are all treated as NXdetectors and stored +# within the NXinstrument group as lists of values stored in +# chronological order. The NXdata group then holds another version +# of the data in a regular 3D array (NumE by NumY by NumX, for a +# total of nP points in a sample image stack type scan). The former +# data values should be stored with a minimum loss of precision, while +# the latter values can be simplified and/or approximated in order to +# fit the constraints of a regular 3D array. 'Line scans' and 'point spectra' +# are just sample_image scan types with reduced dimensions in the same way +# as single images have reduced E dimensions compared to image 'stacks'. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Detector data should be presented with the first dimension corresponding to the +# scan point and subsequent dimensions corresponding to the output of the detector. +# Detectors that provide more than one value per scan point should have +# a data array of rank 1+d, where d is the dimensions of the array provided per +# scan point. For example, an area detector should have an NXdetector data array +# of 3 dimensions, with the first being the set of scan points and the latter +# two being the x- and y- extent of the detector. +# NOTE: For each dimension > 1 there must exist a dim section such as: +# +# +# +# +# +# +# Measurements of the sample position from the x-axis interferometer. +# +# +# +# +# +# +# +# Measurements of the sample position from the y-axis interferometer. +# +# +# +# +# +# +# +# Measurements of the sample position from the z-axis interferometer. +# +# +# +# +# +# +# +# +# +# +# +# +# Label for typical scan types as a convenience for humans. +# Each label corresponds to a specific set of axes being scanned +# to produce a data array of shape: +# +# * sample point spectrum: (photon_energy,) +# * sample line spectrum: (photon_energy, sample_y/sample_x) +# * sample image: (sample_y, sample_x) +# * sample image stack: (photon_energy, sample_y, sample_x) +# * sample focus: (zoneplate_z, sample_y/sample_x) +# * osa image: (osa_y, osa_x) +# * osa focus: (zoneplate_z, osa_y/osa_x) +# * detector image: (detector_y, detector_x) +# +# The "generic scan" string is to be used when none of the +# other choices are appropriate. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Detectors that provide more than one value per scan point should be summarised +# to a single value per scan point for this array in order to simplify plotting. +# +# Note that 'Line scans' and focus type scans measure along one spatial dimension +# but are not restricted to being parallel to the X or Y axes. Such scans +# should therefore use a single dimension for the positions along the spatial +# line. The 'sample_x' and 'sample_y' fields should then contain lists of the +# x- and y-positions and should both have the 'axis' attribute pointing to the same dimension. +# +# +# List of photon energies of the X-ray beam. If scanned through multiple values, +# then an 'axis' attribute will be required to link the field to the appropriate data array dimension. +# +# +# +# +# +# List of Y positions on the sample. If scanned through multiple values, +# then an 'axis' attribute will be required to link the field to the appropriate data array dimension. +# +# +# +# +# +# List of X positions on the sample. If scanned through multiple values, +# then an 'axis' attribute will be required to link the field to the appropriate data array dimension. +# +# +# +# +# +# +# +# Values to use to normalise for time-variations in photon flux. Typically, the synchrotron storage ring +# electron beam current is used as a proxy for the X-ray beam intensity. Array must have same shape as the +# NXdata groups. +# +# +# +# diff --git a/applications/nyaml/NXtas.yaml b/applications/nyaml/NXtas.yaml new file mode 100644 index 0000000000..8e734d65c4 --- /dev/null +++ b/applications/nyaml/NXtas.yaml @@ -0,0 +1,350 @@ +category: application +doc: | + This is an application definition for a triple axis spectrometer. + + It is for the trademark scan of the TAS, the Q-E scan. + For your alignment scans use the rules in :ref:`NXscan`. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXtas(NXobject): + (NXentry)entry: + title(NX_CHAR): + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtas] + (NXinstrument): + (NXsource): + name: + probe: + enumeration: [neutron, x-ray] + (NXcrystal)monochromator: + ei(NX_FLOAT): + unit: NX_ENERGY + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + (NXcrystal)analyser: + ef(NX_FLOAT): + unit: NX_ENERGY + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector): + data(NX_INT): + signal: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample): + name: + doc: | + Descriptive name of sample + qh(NX_FLOAT): + unit: NX_DIMENSIONLESS + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + qk(NX_FLOAT): + unit: NX_DIMENSIONLESS + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + ql(NX_FLOAT): + unit: NX_DIMENSIONLESS + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + en(NX_FLOAT): + unit: NX_ENERGY + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + sgu(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + sgl(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 1 + dim: [[1, nP]] + unit_cell(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 6]] + orientation_matrix(NX_FLOAT): + unit: NX_DIMENSIONLESS + dimensions: + rank: 1 + dim: [[1, 9]] + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata): + doc: | + One of the ei,ef,qh,qk,ql,en should get a primary=1 attribute to denote the main scan axis + ei(link): + target: /NXentry/NXinstrument/monochromator:NXcrystal/ei + ef(link): + target: /NXentry/NXinstrument/analyser:NXcrystal/ef + en(link): + target: /NXentry/NXsample/en + qh(link): + target: /NXentry/NXsample/qh + qk(link): + target: /NXentry/NXsample/qk + ql(link): + target: /NXentry/NXsample/ql + data(link): + target: /NXentry/NXinstrument/NXdetector/data + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3e1396fcfde956ea2d5e48260644bed60a7bf6a088df0c0b5d9928c3fae99fa0 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# This is an application definition for a triple axis spectrometer. +# +# It is for the trademark scan of the TAS, the Q-E scan. +# For your alignment scans use the rules in :ref:`NXscan`. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# Total integral monitor counts +# +# +# +# +# +# One of the ei,ef,qh,qk,ql,en should get a primary=1 attribute to denote the main scan axis +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtofnpd.yaml b/applications/nyaml/NXtofnpd.yaml new file mode 100644 index 0000000000..29927992f3 --- /dev/null +++ b/applications/nyaml/NXtofnpd.yaml @@ -0,0 +1,233 @@ +category: application +doc: | + This is a application definition for raw data from a TOF neutron powder diffractometer +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nDet: | + Number of detectors + nTimeChan: | + nTimeChan description +type: group +NXtofnpd(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtofnpd] + pre_sample_flightpath(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the flight path before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + (NXuser)user: + name(NX_CHAR): + (NXinstrument): + (NXdetector)detector: + data(NX_INT): + signal: 1 + dimensions: + rank: 2 + dim: [[1, nDet], [2, nTimeChan]] + detector_number(NX_INT): + axis: 2 + dimensions: + rank: 1 + dim: [[1, nDet]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + distance to sample for each detector + dimensions: + rank: 1 + dim: [[1, nDet]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + polar angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + azimuthal angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + (NXsample): + name: + doc: | + Descriptive name of sample + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + distance(NX_FLOAT): + unit: NX_LENGTH + data(NX_INT): + signal: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + detector_number(link): + target: /NXentry/NXinstrument/NXdetector/detector_number + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 76efa47955dd8ce499a361753ff2a4da1b9c9771c4cbfff8d5def96ed4ca69bd +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of detectors +# +# +# nTimeChan description +# +# +# This is a application definition for raw data from a TOF neutron powder diffractometer +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# This is the flight path before the sample position. This can be determined by a chopper, +# by the moderator or the source itself. In other words: it the distance to the component +# which gives the T0 signal to the detector electronics. If another component in the +# NXinstrument hierarchy provides this information, this should be a link. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# distance to sample for each detector +# +# +# +# +# +# +# +# polar angle for each detector element +# +# +# +# +# azimuthal angle for each detector element +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtofraw.yaml b/applications/nyaml/NXtofraw.yaml new file mode 100644 index 0000000000..0f3547c556 --- /dev/null +++ b/applications/nyaml/NXtofraw.yaml @@ -0,0 +1,255 @@ +category: application +doc: | + This is an application definition for raw data from a generic TOF instrument +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nDet: | + Number of detectors + nTimeChan: | + nTimeChan description +type: group +NXtofraw(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtofraw] + duration(NX_FLOAT): + run_number(NX_INT): + pre_sample_flightpath(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the flight path before the sample position. This can be determined by a chopper, + by the moderator, or the source itself. In other words: it is the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + (NXuser)user: + name(NX_CHAR): + (NXinstrument)instrument: + (NXdetector)detector: + data(NX_INT): + signal: 1 + dimensions: + rank: 2 + dim: [[1, nDet], [2, nTimeChan]] + detector_number(NX_INT): + axis: 2 + dimensions: + rank: 1 + dim: [[1, nDet]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + distance to sample for each detector + dimensions: + rank: 1 + dim: [[1, nDet]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + polar angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + azimuthal angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + (NXsample): + name: + doc: | + Descriptive name of sample + nature(NX_CHAR): + enumeration: [powder, liquid, single crystal] + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + distance(NX_FLOAT): + unit: NX_LENGTH + data(NX_INT): + signal: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + integral_counts(NX_INT): + unit: NX_UNITLESS + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + detector_number(link): + target: /NXentry/NXinstrument/NXdetector/detector_number + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cf876130ab5b69d23c8694bdbbcb43d81f4121e37e52467668853246ecdbecf4 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of detectors +# +# +# nTimeChan description +# +# +# This is an application definition for raw data from a generic TOF instrument +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# This is the flight path before the sample position. This can be determined by a chopper, +# by the moderator, or the source itself. In other words: it is the distance to the component +# which gives the T0 signal to the detector electronics. If another component in the +# NXinstrument hierarchy provides this information, this should be a link. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# distance to sample for each detector +# +# +# +# +# +# +# +# +# +# +# polar angle for each detector element +# +# +# +# +# +# azimuthal angle for each detector element +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtofsingle.yaml b/applications/nyaml/NXtofsingle.yaml new file mode 100644 index 0000000000..31eacdc3d2 --- /dev/null +++ b/applications/nyaml/NXtofsingle.yaml @@ -0,0 +1,244 @@ +category: application +doc: | + This is a application definition for raw data from a generic TOF instrument +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + xSize: | + xSize description + ySize: | + ySize description + nDet: | + Number of detectors + nTimeChan: | + nTimeChan description +type: group +NXtofsingle(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtofsingle] + duration(NX_FLOAT): + pre_sample_flightpath(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the flight path before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + (NXuser)user: + name(NX_CHAR): + (NXinstrument): + (NXdetector)detector: + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, xSize], [2, ySize], [3, nTimeChan]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance to sample for the center of the detector + dimensions: + rank: 1 + dim: [[1, 1]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + polar angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + azimuthal angle for each detector element + dimensions: + rank: 1 + dim: [[1, nDet]] + (NXsample): + name: + doc: | + Descriptive name of sample + nature(NX_CHAR): + enumeration: [powder, liquid, single crystal] + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + distance(NX_FLOAT): + unit: NX_LENGTH + data(NX_INT): + signal: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + axis: 1 + dimensions: + rank: 1 + dim: [[1, nTimeChan]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/NXdetector/data + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 68f4d548d9d5116bbd6e38aa5ed5230e7ac8f1f0dcb70edc3aceb398ea4983d0 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# xSize description +# +# +# ySize description +# +# +# Number of detectors +# +# +# nTimeChan description +# +# +# This is a application definition for raw data from a generic TOF instrument +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# This is the flight path before the sample position. This can be determined by a chopper, +# by the moderator or the source itself. In other words: it the distance to the component +# which gives the T0 signal to the detector electronics. If another component in the +# NXinstrument hierarchy provides this information, this should be a link. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Distance to sample for the center of the detector +# +# +# +# +# +# +# +# polar angle for each detector element +# +# +# +# +# azimuthal angle for each detector element +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtomo.yaml b/applications/nyaml/NXtomo.yaml new file mode 100644 index 0000000000..8ec340419e --- /dev/null +++ b/applications/nyaml/NXtomo.yaml @@ -0,0 +1,279 @@ +category: application +doc: | + This is the application definition for x-ray or neutron tomography raw data. + + In tomography + a number of dark field images are measured, some bright field images and, of course the sample. + In order to distinguish between them images carry a image_key. +symbols: + doc: | + These symbols will be used below to coordinate datasets with the same shape. + nFrames: | + Number of frames + xSize: | + Number of pixels in X direction + ySize: | + Number of pixels in Y direction +type: group +NXtomo(NXobject): + (NXentry)entry: + title: + exists: ['min', '0', 'max', '1'] + start_time(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + end_time(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtomo] + (NXinstrument)instrument: + (NXsource): + exists: ['min', '0', 'max', '1'] + type: + exists: ['min', '0', 'max', '1'] + name: + exists: ['min', '0', 'max', '1'] + probe: + exists: ['min', '0', 'max', '1'] + enumeration: [neutron, x-ray, electron] + (NXdetector)detector: + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, nFrames], [2, xSize], [3, ySize]] + image_key(NX_INT): + doc: | + In order + to distinguish between sample projections, dark and flat + images, a magic number is recorded per frame. + The key is as follows: + + * projection = 0 + * flat field = 1 + * dark field = 2 + * invalid = 3 + dimensions: + rank: 1 + dim: [[1, nFrames]] + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Distance between detector and sample + x_rotation_axis_pixel_position(NX_FLOAT): + exists: ['min', '0', 'max', '1'] + y_rotation_axis_pixel_position(NX_FLOAT): + exists: ['min', '0', 'max', '1'] + (NXsample)sample: + name: + doc: | + Descriptive name of sample + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + In practice this axis is always aligned along one pixel direction on the detector and usually vertical. + There are experiments with horizontal rotation axes, so this would need to be indicated somehow. + For now the best way for that is an open question. + dimensions: + rank: 1 + dim: [[1, nFrames]] + x_translation(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + dimensions: + rank: 1 + dim: [[1, nFrames]] + y_translation(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + dimensions: + rank: 1 + dim: [[1, nFrames]] + z_translation(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + dimensions: + rank: 1 + dim: [[1, nFrames]] + (NXmonitor)control: + exists: ['min', '0', 'max', '1'] + data(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts for each measured frame. Allows a to correction for + fluctuations in the beam between frames. + dimensions: + rank: 1 + dim: [[1, nFrames]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/detector:NXdetector/data + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + image_key(link): + target: /NXentry/NXinstrument/detector:NXdetector/image_key + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2ddef81db80e94c71e2fd772d74cfdae6cf00b895087e66b9e346d23a86fbc72 +# +# +# +# +# +# +# These symbols will be used below to coordinate datasets with the same shape. +# +# +# Number of frames +# +# +# Number of pixels in X direction +# +# +# Number of pixels in Y direction +# +# +# +# This is the application definition for x-ray or neutron tomography raw data. +# +# In tomography +# a number of dark field images are measured, some bright field images and, of course the sample. +# In order to distinguish between them images carry a image_key. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# In order +# to distinguish between sample projections, dark and flat +# images, a magic number is recorded per frame. +# The key is as follows: +# +# * projection = 0 +# * flat field = 1 +# * dark field = 2 +# * invalid = 3 +# +# +# +# +# +# +# +# +# Distance between detector and sample +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# In practice this axis is always aligned along one pixel direction on the detector and usually vertical. +# There are experiments with horizontal rotation axes, so this would need to be indicated somehow. +# For now the best way for that is an open question. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total integral monitor counts for each measured frame. Allows a to correction for +# fluctuations in the beam between frames. +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtomophase.yaml b/applications/nyaml/NXtomophase.yaml new file mode 100644 index 0000000000..7ef44c6a21 --- /dev/null +++ b/applications/nyaml/NXtomophase.yaml @@ -0,0 +1,292 @@ +category: application +doc: | + This is the application definition for x-ray or neutron tomography raw data with phase contrast variation at each point. + + In tomography first + some dark field images are measured, some bright field images and, of course the sample. In order + to properly sort the order of the images taken, a sequence number is stored with each image. +symbols: + doc: | + These symbols will be used below to coordinate datasets with the same shape. + nBrightFrames: | + Number of bright frames + nDarkFrames: | + Number of dark frames + nSampleFrames: | + Number of image (sample) frames + nPhase: | + Number of phase settings + xSize: | + Number of pixels in X direction + ySize: | + Number of pixels in Y direction +type: group +NXtomophase(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtomophase] + (NXinstrument)instrument: + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + (NXdetector)bright_field: + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, nBrightFrames], [2, xSize], [3, ySize]] + sequence_number(NX_INT): + dimensions: + rank: 1 + dim: [[1, nBrightFrames]] + (NXdetector)dark_field: + data(NX_INT): + signal: 1 + dimensions: + rank: 3 + dim: [[1, nDarkFrames], [2, xSize], [3, ySize]] + sequence_number(NX_INT): + dimensions: + rank: 1 + dim: [[1, nDarkFrames]] + (NXdetector)sample: + data(NX_INT): + signal: 1 + dimensions: + rank: 4 + dim: [[1, nSampleFrames], [2, nPhase], [3, xSize], [4, ySize]] + sequence_number(NX_INT): + dimensions: + rank: 2 + dim: [[1, nSampleFrames], [2, nPhase]] + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance between detector and sample + (NXsample)sample: + name: + doc: | + Descriptive name of sample + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + dimensions: + rank: 1 + dim: [[1, nSampleFrames]] + x_translation(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, nSampleFrames]] + y_translation(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, nSampleFrames]] + z_translation(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, nSampleFrames]] + (NXmonitor)control: + integral(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts for each measured frame. Allows a correction for + fluctuations in the beam between frames. + dimensions: + rank: 1 + + # TODO: nPhase? + dim: [[1, nDarkFrames + nBrightFrames + nSampleFrame]] + (NXdata)data: + data(link): + target: /NXentry/NXinstrument/sample:NXdetector/data + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 61792a668d325a2c70187730d3457c9ee8aba24ca55e9405ee1dd4d29f7d2296 +# +# +# +# +# +# These symbols will be used below to coordinate datasets with the same shape. +# +# Number of bright frames +# +# +# Number of dark frames +# +# +# Number of image (sample) frames +# +# +# Number of phase settings +# +# +# Number of pixels in X direction +# +# +# Number of pixels in Y direction +# +# +# +# This is the application definition for x-ray or neutron tomography raw data with phase contrast variation at each point. +# +# In tomography first +# some dark field images are measured, some bright field images and, of course the sample. In order +# to properly sort the order of the images taken, a sequence number is stored with each image. +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Distance between detector and sample +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total integral monitor counts for each measured frame. Allows a correction for +# fluctuations in the beam between frames. +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXtomoproc.yaml b/applications/nyaml/NXtomoproc.yaml new file mode 100644 index 0000000000..48ba4c9e04 --- /dev/null +++ b/applications/nyaml/NXtomoproc.yaml @@ -0,0 +1,217 @@ +category: application +doc: | + This is an application definition for the final result of a tomography experiment: a 3D construction of some volume of physical properties. +symbols: + doc: | + These symbols will be used below to coordinate datasets with the same shape. + nX: | + Number of voxels in X direction + nY: | + Number of voxels in Y direction + nZ: | + Number of voxels in Z direction +type: group +NXtomoproc(NXobject): + (NXentry)entry: + title: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXtomoproc] + (NXinstrument): + (NXsource): + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + (NXsample): + name: + doc: | + Descriptive name of sample + (NXprocess)reconstruction: + program(NX_CHAR): + doc: | + Name of the program used for reconstruction + version(NX_CHAR): + doc: | + Version of the program used + date(NX_DATE_TIME): + doc: | + Date and time of reconstruction processing. + (NXparameters)parameters: + raw_file(NX_CHAR): + doc: | + Original raw data file this data was derived from + (NXdata)data: + data(NX_INT): + signal: 1 + doc: | + This is the reconstructed volume. This can be different + things. Please indicate in the unit attribute what physical + quantity this really is. + dimensions: + rank: 3 + dim: [[1, nX], [2, nX], [3, nZ]] + \@transform: + \@offset: + \@scaling: + x(NX_FLOAT): + unit: NX_ANY + axis: 1 + doc: | + This is an array holding the values to use for the x-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, nX]] + y(NX_FLOAT): + unit: NX_ANY + axis: 2 + doc: | + This is an array holding the values to use for the y-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, nY]] + z(NX_FLOAT): + unit: NX_ANY + axis: 3 + doc: | + This is an array holding the values to use for the z-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, nZ]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# f0f55737027dae413b76cbb267a0d0021482dfdf9d398c0886e5d5b4e8c8bca1 +# +# +# +# +# +# These symbols will be used below to coordinate datasets with the same shape. +# +# Number of voxels in X direction +# +# +# Number of voxels in Y direction +# +# +# Number of voxels in Z direction +# +# +# This is an application definition for the final result of a tomography experiment: a 3D construction of some volume of physical properties. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# Name of the program used for reconstruction +# +# +# Version of the program used +# +# +# Date and time of reconstruction processing. +# +# +# +# Original raw data file this data was derived from +# +# +# +# +# +# +# This is the reconstructed volume. This can be different +# things. Please indicate in the unit attribute what physical +# quantity this really is. +# +# +# +# +# +# +# +# +# +# +# +# +# This is an array holding the values to use for the x-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# +# +# This is an array holding the values to use for the y-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# +# +# This is an array holding the values to use for the z-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxas.yaml b/applications/nyaml/NXxas.yaml new file mode 100644 index 0000000000..865c953dce --- /dev/null +++ b/applications/nyaml/NXxas.yaml @@ -0,0 +1,212 @@ +category: application +doc: | + This is an application definition for raw data from an X-ray absorption spectroscopy experiment. + + This is essentially a scan on energy versus incoming/ + absorbed beam. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxas(NXobject): + (NXentry): + \@entry: + doc: | + NeXus convention is to use "entry1", "entry2", ... + for analysis software to locate each entry. + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxas] + (NXinstrument): + (NXsource): + type: + name: + probe: + enumeration: [x-ray] + (NXmonochromator)monochromator: + energy(NX_FLOAT): + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector)incoming_beam: + data(NX_NUMBER): + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdetector)absorbed_beam: + data(NX_NUMBER): + doc: | + This data corresponds to the sample signal. + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample): + name: + doc: | + Descriptive name of sample + (NXmonitor): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + data(NX_NUMBER): + doc: | + This field could be a link to ``/NXentry/NXinstrument/incoming_beam:NXdetector/data`` + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata): + energy(link): + target: /NXentry/NXinstrument/monochromator:NXmonochromator/energy + absorbed_beam(link): + target: /NXentry/NXinstrument/absorbed_beam:NXdetector/data + mode: + doc: | + Detection method used for observing the sample absorption (pick one from the enumerated list and spell exactly) + enumeration: [Total Electron Yield, Partial Electron Yield, Auger Electron Yield, Fluorescence Yield, Transmission] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2d5aaca6043db70d6315aaf4b2fbd9cc9e75ce43f1f2103fd79fdb9c11e36f4d +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# This is an application definition for raw data from an X-ray absorption spectroscopy experiment. +# +# This is essentially a scan on energy versus incoming/ +# absorbed beam. +# +# +# +# +# NeXus convention is to use "entry1", "entry2", ... +# for analysis software to locate each entry. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# This data corresponds to the sample signal. +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# This field could be a link to ``/NXentry/NXinstrument/incoming_beam:NXdetector/data`` +# +# +# +# +# +# +# +# +# +# Detection method used for observing the sample absorption (pick one from the enumerated list and spell exactly) +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxasproc.yaml b/applications/nyaml/NXxasproc.yaml new file mode 100644 index 0000000000..111d6699bc --- /dev/null +++ b/applications/nyaml/NXxasproc.yaml @@ -0,0 +1,147 @@ +category: application +doc: | + Processed data from XAS. This is energy versus I(incoming)/I(absorbed). +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxasproc(NXobject): + (NXentry): + \@entry: + doc: | + NeXus convention is to use "entry1", "entry2", ... + for analysis software to locate each entry. + title: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxasproc] + (NXsample): + name: + doc: | + Descriptive name of sample + (NXprocess)XAS_data_reduction: + program(NX_CHAR): + doc: | + Name of the program used for reconstruction + version(NX_CHAR): + doc: | + Version of the program used + date(NX_DATE_TIME): + doc: | + Date and time of reconstruction processing. + (NXparameters)parameters: + raw_file(NX_CHAR): + doc: | + Original raw data file this data was derived from + (NXdata): + energy: + axis: 1 + dimensions: + rank: 1 + dim: [[1, nP]] + data(NX_FLOAT): + doc: | + This is corrected and calibrated I(incoming)/I(absorbed). So it is the absorption. + Expect attribute ``signal=1`` + dimensions: + rank: 1 + dim: [[1, nP]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 07a20126249a01bd8a1d5b7cf0796baf16f8dd148bcddc87d976c77baa89e00c +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# Processed data from XAS. This is energy versus I(incoming)/I(absorbed). +# +# +# +# +# NeXus convention is to use "entry1", "entry2", ... +# for analysis software to locate each entry. +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# Name of the program used for reconstruction +# +# +# Version of the program used +# +# +# Date and time of reconstruction processing. +# +# +# +# Original raw data file this data was derived from +# +# +# +# +# +# +# +# +# +# +# +# This is corrected and calibrated I(incoming)/I(absorbed). So it is the absorption. +# Expect attribute ``signal=1`` +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxbase.yaml b/applications/nyaml/NXxbase.yaml new file mode 100644 index 0000000000..46db086841 --- /dev/null +++ b/applications/nyaml/NXxbase.yaml @@ -0,0 +1,308 @@ +category: application +doc: | + This definition covers the common parts of all monochromatic single crystal raw data application definitions. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points + nXPixels: | + Number of X pixels + nYPixels: | + Number of Y pixels +type: group +NXxbase(NXobject): + (NXentry)entry: + title: + start_time(NX_DATE_TIME): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxbase] + (NXinstrument)instrument: + (NXsource)source: + type: + name: + probe: + enumeration: [neutron, x-ray, electron] + (NXmonochromator)monochromator: + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + (NXdetector)detector: + exists: ['max', 'unbounded'] + data(NX_INT): + signal: 1 + doc: | + The area detector data, the first dimension is always the + number of scan points, the second and third are the number + of pixels in x and y. The origin is always assumed to be + in the center of the detector. maxOccurs is limited to the + the number of detectors on your instrument. + dimensions: + rank: 3 + dim: [[1, nP], [2, nXPixels], [3, nYPixels]] + \@signal: + type: NX_POSINT + enumeration: [1] + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + The name of the group is detector if there is only one detector, + if there are several, names have to be detector1, + detector2, ...detectorn. + distance(NX_FLOAT): + unit: NX_LENGTH + frame_start_number(NX_INT): + doc: | + This is the start number of the first frame of a scan. In PX one often scans a couple + of frames on a give sample, then does something else, then returns to the same sample + and scans some more frames. Each time with a new data file. + This number helps concatenating such measurements. + (NXsample)sample: + name(NX_CHAR): + doc: | + Descriptive name of sample + orientation_matrix(NX_FLOAT): + doc: | + The orientation matrix according to Busing and + Levy conventions. This is not strictly necessary as + the UB can always be derived from the data. But + let us bow to common usage which includes the + UB nearly always. + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + unit_cell(NX_FLOAT): + doc: | + The unit cell, a, b, c, alpha, beta, gamma. + Again, not strictly necessary, but normally written. + dimensions: + rank: 1 + dim: [[1, 6]] + temperature(NX_FLOAT): + doc: | + The sample temperature or whatever sensor represents this value best + dimensions: + rank: 1 + dim: [[1, nP]] + x_translation(NX_FLOAT): + unit: NX_LENGTH + doc: | + Translation of the sample along the X-direction of the laboratory coordinate system + y_translation(NX_FLOAT): + unit: NX_LENGTH + doc: | + Translation of the sample along the Y-direction of the laboratory coordinate system + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Translation of the sample along the Z-direction of the laboratory coordinate system + (NXmonitor)control: + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + preset(NX_FLOAT): + doc: | + preset value for time or monitor + integral(NX_FLOAT): + unit: NX_ANY + doc: | + Total integral monitor counts + (NXdata): + doc: | + The name of this group id data if there is only + one detector; if there are several the names will + be data1, data2, data3 and will point + to the corresponding detector groups in the + instrument hierarchy. + data(link): + target: /NXentry/NXinstrument/NXdetector/data + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 97c93a3c48735ce7430e1e80498bae3276fa68441c19151174bc943af9503be3 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# Number of X pixels +# +# +# Number of Y pixels +# +# +# +# This definition covers the common parts of all monochromatic single crystal raw data application definitions. +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The area detector data, the first dimension is always the +# number of scan points, the second and third are the number +# of pixels in x and y. The origin is always assumed to be +# in the center of the detector. maxOccurs is limited to the +# the number of detectors on your instrument. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The name of the group is detector if there is only one detector, +# if there are several, names have to be detector1, +# detector2, ...detectorn. +# +# +# +# This is the start number of the first frame of a scan. In PX one often scans a couple +# of frames on a give sample, then does something else, then returns to the same sample +# and scans some more frames. Each time with a new data file. +# This number helps concatenating such measurements. +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# The orientation matrix according to Busing and +# Levy conventions. This is not strictly necessary as +# the UB can always be derived from the data. But +# let us bow to common usage which includes the +# UB nearly always. +# +# +# +# +# +# +# +# +# The unit cell, a, b, c, alpha, beta, gamma. +# Again, not strictly necessary, but normally written. +# +# +# +# +# +# +# +# The sample temperature or whatever sensor represents this value best +# +# +# +# +# +# +# Translation of the sample along the X-direction of the laboratory coordinate system +# +# +# Translation of the sample along the Y-direction of the laboratory coordinate system +# +# +# Translation of the sample along the Z-direction of the laboratory coordinate system +# +# +# +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# preset value for time or monitor +# +# +# Total integral monitor counts +# +# +# +# +# The name of this group id data if there is only +# one detector; if there are several the names will +# be data1, data2, data3 and will point +# to the corresponding detector groups in the +# instrument hierarchy. +# +# +# +# +# diff --git a/applications/nyaml/NXxeuler.yaml b/applications/nyaml/NXxeuler.yaml new file mode 100644 index 0000000000..103128c2dc --- /dev/null +++ b/applications/nyaml/NXxeuler.yaml @@ -0,0 +1,173 @@ +category: application +doc: | + raw data from a :index:`four-circle diffractometer` with an :index:`eulerian cradle`, extends :ref:`NXxbase` + + It extends :ref:`NXxbase`, so the full definition is the content + of :ref:`NXxbase` plus the data defined here. All four angles are + logged in order to support arbitrary scans in reciprocal space. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxeuler(NXxbase): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxeuler] + (NXinstrument)instrument: + (NXdetector)detector: + polar_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + The polar_angle (two theta) where the detector is placed + at each scan point. + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample)sample: + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the sample rotation angle at each + scan point + dimensions: + rank: 1 + dim: [[1, nP]] + chi(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the chi angle of the eulerian + cradle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + phi(NX_FLOAT): + unit: NX_ANGLE + signal: 1 + doc: | + This is an array holding the phi rotation of the eulerian + cradle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata)name: + polar_angle(link): + target: /NXentry/NXinstrument/NXdetector/polar_angle + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + chi(link): + target: /NXentry/NXsample/chi + phi(link): + target: /NXentry/NXsample/phi + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 418ca04c5cb718b73b9fb0a9ba4d7834a39720336466afd0292a376c2e6db6f0 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# raw data from a :index:`four-circle diffractometer` with an :index:`eulerian cradle`, extends :ref:`NXxbase` +# +# It extends :ref:`NXxbase`, so the full definition is the content +# of :ref:`NXxbase` plus the data defined here. All four angles are +# logged in order to support arbitrary scans in reciprocal space. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# The polar_angle (two theta) where the detector is placed +# at each scan point. +# +# +# +# +# +# +# +# +# +# +# This is an array holding the sample rotation angle at each +# scan point +# +# +# +# +# +# +# +# This is an array holding the chi angle of the eulerian +# cradle at each scan point +# +# +# +# +# +# +# +# This is an array holding the phi rotation of the eulerian +# cradle at each scan point +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxkappa.yaml b/applications/nyaml/NXxkappa.yaml new file mode 100644 index 0000000000..11ee96ea7a --- /dev/null +++ b/applications/nyaml/NXxkappa.yaml @@ -0,0 +1,174 @@ +category: application +doc: | + raw data from a kappa geometry (CAD4) single crystal diffractometer, extends :ref:`NXxbase` + + This is the application definition for raw data from a kappa geometry + (CAD4) single crystal + diffractometer. It extends :ref:`NXxbase`, so the full definition is + the content of :ref:`NXxbase` plus the + data defined here. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxkappa(NXxbase): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxkappa] + (NXinstrument)instrument: + (NXdetector)detector: + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + The polar_angle (two theta) at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample)sample: + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the sample rotation angle at each + scan point + dimensions: + rank: 1 + dim: [[1, nP]] + kappa(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the kappa angle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + phi(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the phi angle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + alpha(NX_FLOAT): + unit: NX_ANGLE + doc: | + This holds the inclination angle of the kappa arm. + (NXdata)name: + polar_angle(link): + target: /NXentry/NXinstrument/NXdetector/polar_angle + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + kappa(link): + target: /NXentry/NXsample/kappa + phi(link): + target: /NXentry/NXsample/phi + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ab0a0187da4ac644dd64a38cf2120fa6519200d0c8097d2e33373b66c4e3fab5 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# raw data from a kappa geometry (CAD4) single crystal diffractometer, extends :ref:`NXxbase` +# +# This is the application definition for raw data from a kappa geometry +# (CAD4) single crystal +# diffractometer. It extends :ref:`NXxbase`, so the full definition is +# the content of :ref:`NXxbase` plus the +# data defined here. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# The polar_angle (two theta) at each scan point +# +# +# +# +# +# +# +# +# +# This is an array holding the sample rotation angle at each +# scan point +# +# +# +# +# +# +# +# This is an array holding the kappa angle at each scan point +# +# +# +# +# +# +# +# This is an array holding the phi angle at each scan point +# +# +# +# +# +# +# This holds the inclination angle of the kappa arm. +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxlaue.yaml b/applications/nyaml/NXxlaue.yaml new file mode 100644 index 0000000000..82e1d406ba --- /dev/null +++ b/applications/nyaml/NXxlaue.yaml @@ -0,0 +1,109 @@ +category: application +doc: | + raw data from a single crystal laue camera, extends :ref:`NXxrot` + + This is the application definition for raw data from a single crystal laue + camera. It extends :ref:`NXxrot`. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nE: | + Number of energies +type: group +NXxlaue(NXxrot): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxlaue] + (NXinstrument)instrument: + (NXsource)source: + (NXdata)distribution: + data: + doc: | + expect ``signal=1 axes="energy"`` + dimensions: + rank: 1 + dim: [[1, nE]] + wavelength: + unit: NX_WAVELENGTH + dimensions: + rank: 1 + dim: [[1, nE]] + doc: | + This is the wavelength distribution of the beam + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6bd59c0bb31baf46bbacaad01e38b03336b75f5d94468e0689b72386f201e77b +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of energies +# +# +# +# raw data from a single crystal laue camera, extends :ref:`NXxrot` +# +# This is the application definition for raw data from a single crystal laue +# camera. It extends :ref:`NXxrot`. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# expect ``signal=1 axes="energy"`` +# +# +# +# +# +# +# +# +# +# +# This is the wavelength distribution of the beam +# +# +# +# +# +# diff --git a/applications/nyaml/NXxlaueplate.yaml b/applications/nyaml/NXxlaueplate.yaml new file mode 100644 index 0000000000..bb23a1d29f --- /dev/null +++ b/applications/nyaml/NXxlaueplate.yaml @@ -0,0 +1,73 @@ +category: application +doc: | + raw data from a single crystal Laue camera, extends :ref:`NXxlaue` + + This is the application definition for raw data from a single crystal Laue + camera with an image plate as a detector. It extends :ref:`NXxlaue`. +type: group +NXxlaueplate(NXxlaue): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxlaueplate] + (NXinstrument)instrument: + (NXdetector)detector: + diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + The diameter of a cylindrical detector + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7ad47196c57fedde1c91245a9edd7ff63d278eb1e2fbac3d8059e8f2744c3a80 +# +# +# +# +# +# raw data from a single crystal Laue camera, extends :ref:`NXxlaue` +# +# This is the application definition for raw data from a single crystal Laue +# camera with an image plate as a detector. It extends :ref:`NXxlaue`. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# The diameter of a cylindrical detector +# +# +# +# +# diff --git a/applications/nyaml/NXxnb.yaml b/applications/nyaml/NXxnb.yaml new file mode 100644 index 0000000000..c5f052d79a --- /dev/null +++ b/applications/nyaml/NXxnb.yaml @@ -0,0 +1,160 @@ +category: application +doc: | + raw data from a single crystal diffractometer, extends :ref:`NXxbase` + + This is the application definition for raw data from + a single crystal diffractometer + measuring in normal beam mode. It extends :ref:`NXxbase`, + so the full definition is the content of + :ref:`NXxbase` plus the data defined here. All angles are + logged in order to support arbitrary scans in + reciprocal space. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxnb(NXxbase): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxnb] + (NXinstrument)instrument: + (NXdetector)detector: + polar_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + The polar_angle (gamma) of the detector for each scan point. + dimensions: + rank: 1 + dim: [[1, nP]] + tilt_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + The angle by which the detector has been tilted out of the + scattering plane. + dimensions: + rank: 1 + dim: [[1, nP]] + (NXsample)sample: + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + primary: 1 + doc: | + This is an array holding the sample rotation angle at each + scan point + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata)name: + polar_angle(link): + target: /NXentry/NXinstrument/NXdetector/polar_angle + tilt(link): + target: /NXentry/NXinstrument/NXdetector/tilt + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 08abdab5fcf7054861bd5927b569a05e6d69a55b7ed9b80344a60ede01cc3516 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# raw data from a single crystal diffractometer, extends :ref:`NXxbase` +# +# This is the application definition for raw data from +# a single crystal diffractometer +# measuring in normal beam mode. It extends :ref:`NXxbase`, +# so the full definition is the content of +# :ref:`NXxbase` plus the data defined here. All angles are +# logged in order to support arbitrary scans in +# reciprocal space. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# The polar_angle (gamma) of the detector for each scan point. +# +# +# +# +# +# +# +# The angle by which the detector has been tilted out of the +# scattering plane. +# +# +# +# +# +# +# +# +# +# +# This is an array holding the sample rotation angle at each +# scan point +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/applications/nyaml/NXxrot.yaml b/applications/nyaml/NXxrot.yaml new file mode 100644 index 0000000000..5aa4e35558 --- /dev/null +++ b/applications/nyaml/NXxrot.yaml @@ -0,0 +1,155 @@ +category: application +doc: | + raw data from a rotation camera, extends :ref:`NXxbase` + + This is the application definition for raw data from a rotation camera. + It extends :ref:`NXxbase`, so the full definition is the content of :ref:`NXxbase` + plus the data defined here. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxrot(NXxbase): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + enumeration: [NXxrot] + (NXinstrument)instrument: + (NXdetector)detector: + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + The polar_angle (two theta) where the detector is placed. + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the x position where the direct beam would hit the detector. This is a + length, not a pixel position, and can be outside of the actual detector. + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the y position where the direct beam would hit the detector. This is a + length, not a pixel position, and can be outside of the actual detector. + (NXattenuator)attenuator: + attenuator_transmission(NX_FLOAT): + unit: NX_ANY + (NXsample)sample: + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the sample rotation start angle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + rotation_angle_step(NX_FLOAT): + unit: NX_ANGLE + axis: 1 + doc: | + This is an array holding the step made for sample rotation angle at each scan point + dimensions: + rank: 1 + dim: [[1, nP]] + (NXdata)name: + rotation_angle(link): + target: /NXentry/NXsample/rotation_angle + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 996ce47ecffe4c4b4e0ffe4014ce8d5db9abb70f109b8508e5124256777ae344 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# raw data from a rotation camera, extends :ref:`NXxbase` +# +# This is the application definition for raw data from a rotation camera. +# It extends :ref:`NXxbase`, so the full definition is the content of :ref:`NXxbase` +# plus the data defined here. +# +# +# +# Official NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# The polar_angle (two theta) where the detector is placed. +# +# +# +# This is the x position where the direct beam would hit the detector. This is a +# length, not a pixel position, and can be outside of the actual detector. +# +# +# +# This is the y position where the direct beam would hit the detector. This is a +# length, not a pixel position, and can be outside of the actual detector. +# +# +# +# +# +# +# +# +# +# This is an array holding the sample rotation start angle at each scan point +# +# +# +# +# +# This is an array holding the step made for sample rotation angle at each scan point +# +# +# +# +# +# +# +# +# +# diff --git a/base_classes/NXaperture.nxdl.xml b/base_classes/NXaperture.nxdl.xml index e18b2a5f0e..0fe4ec6d76 100644 --- a/base_classes/NXaperture.nxdl.xml +++ b/base_classes/NXaperture.nxdl.xml @@ -1,9 +1,9 @@ - + - - - A beamline aperture. This group is deprecated, use NXslit instead. - - + + + A beamline aperture. This group is deprecated, use NXslit instead. + + - - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the - surface of the aperture pointing towards the source. - - In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference. - - .. image:: aperture/aperture.png - :width: 40% - + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the + surface of the aperture pointing towards the source. + + In complex (asymmetric) geometries an NXoff_geometry group can be used to provide an unambiguous reference. + + .. image:: aperture/aperture.png + :width: 40% + - - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. - + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + + + + Stores the raw positions of aperture motors. + - location and shape of aperture - - .. TODO: documentation needs improvement, contributions welcome - - * description of terms is poor and leaves much to interpretation - * Describe what is meant by translation _here_ and ... - * Similar throughout base classes - * Some base classes do this much better - * Such as where is the gap written? - + location and shape of aperture + + .. TODO: documentation needs improvement, contributions welcome + + * description of terms is poor and leaves much to interpretation + * Describe what is meant by translation _here_ and ... + * Similar throughout base classes + * Some base classes do this much better + * Such as where is the gap written? - location and shape of each blade + + location and shape of each blade + - - Absorbing material of the aperture + + + + Absorbing material of the aperture + - Description of aperture + + Description of aperture + + + + + Shape of the aperture. + + + + + + + + + + + + + - describe any additional information in a note* + + + The relevant dimension for the aperture, i.e. slit width, pinhole and iris + diameter + + + + + describe any additional information in a note* + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. diff --git a/base_classes/NXbeam.nxdl.xml b/base_classes/NXbeam.nxdl.xml index 232a75e46d..9bf36c06be 100644 --- a/base_classes/NXbeam.nxdl.xml +++ b/base_classes/NXbeam.nxdl.xml @@ -1,9 +1,9 @@ - + - + - These symbols coordinate datasets with the same shape. + These symbols coordinate datasets with the same shape. - Number of scan points. + + Number of scan points. + - Number of channels in the incident beam spectrum, if known + + Number of channels in the incident beam spectrum, if known + - Number of moments representing beam divergence (x, y, xy, etc.) + + Number of moments representing beam divergence (x, y, xy, etc.) + - Properties of the neutron or X-ray beam at a given location. - - This group is intended to be referenced - by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is - especially valuable in storing the results of instrument simulations in which it is useful - to specify the beam profile, time distribution etc. at each beamline component. Otherwise, - its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron - scattering by the sample, e.g., energy transfer, polarizations. - - Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. - To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred - by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. - + Properties of the neutron or X-ray beam at a given location. + + This group is intended to be referenced + by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is + especially valuable in storing the results of instrument simulations in which it is useful + to specify the beam profile, time distribution etc. at each beamline component. Otherwise, + its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron + scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is + considered as a beamline component and this group may be defined as a subgroup directly inside + :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an + :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). + + Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. + To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred + by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. + - Distance from sample. Note, it is recommended to use NXtransformations instead. + + Distance from sample. Note, it is recommended to use NXtransformations instead. + - Energy carried by each particle of the beam on entering the beamline component + + Energy carried by each particle of the beam on entering the beamline component. + + In the case of a monochromatic beam this is the scalar energy. + Several other use cases are permitted, depending on the + presence of other incident_energy_X fields. + + * In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights. + * In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot. + Here, incident_energy_weights and incident_energy_spread are not set. + * In the case of a polychromatic beam that varies shot-to-shot, + this is an array of length m with the relative weights in incident_energy_weights as a 2D array. + * In the case of a polychromatic beam that varies shot-to-shot and where the channels also vary, + this is a 2D array of dimensions nP by m (slow to fast) with the relative weights in incident_energy_weights as a 2D array. + + Note, variants are a good way to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value energy value is available along with the original spectrum from which it was calibrated. + + + + The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in + the energy spread, this is a 2D array of dimension nP by m + (slow to fast) of the spreads of the corresponding + wavelength in incident_wavelength. + + + + + In the case of a polychromatic beam this is an array of length m of the relative + weights of the corresponding energies in incident_energy. In the case of a + polychromatic beam that varies shot-to-shot, this is a 2D array of dimensions np + by m (slow to fast) of the relative weights of the corresponding energies in + incident_energy. + + - Energy carried by each particle of the beam on leaving the beamline component + + Energy carried by each particle of the beam on leaving the beamline component + - Change in particle energy caused by the beamline component + + Change in particle energy caused by the beamline component + - In the case of a monochromatic beam this is the scalar - wavelength. - - Several other use cases are permitted, depending on the - presence or absence of other incident_wavelength_X - fields. - - In the case of a polychromatic beam this is an array of - length **m** of wavelengths, with the relative weights - in ``incident_wavelength_weights``. - - In the case of a monochromatic beam that varies shot- - to-shot, this is an array of wavelengths, one for each - recorded shot. Here, ``incident_wavelength_weights`` and - incident_wavelength_spread are not set. - - In the case of a polychromatic beam that varies shot-to- - shot, this is an array of length **m** with the relative - weights in ``incident_wavelength_weights`` as a 2D array. - - In the case of a polychromatic beam that varies shot-to- - shot and where the channels also vary, this is a 2D array - of dimensions **nP** by **m** (slow to fast) with the - relative weights in ``incident_wavelength_weights`` as a 2D - array. - - Note, :ref:`variants <Design-Variants>` are a good way - to represent several of these use cases in a single dataset, - e.g. if a calibrated, single-value wavelength value is - available along with the original spectrum from which it - was calibrated. - Wavelength on entering beamline component + In the case of a monochromatic beam this is the scalar + wavelength. + + Several other use cases are permitted, depending on the + presence or absence of other incident_wavelength_X + fields. + + In the case of a polychromatic beam this is an array of + length **m** of wavelengths, with the relative weights + in ``incident_wavelength_weights``. + + In the case of a monochromatic beam that varies shot- + to-shot, this is an array of wavelengths, one for each + recorded shot. Here, ``incident_wavelength_weights`` and + incident_wavelength_spread are not set. + + In the case of a polychromatic beam that varies shot-to- + shot, this is an array of length **m** with the relative + weights in ``incident_wavelength_weights`` as a 2D array. + + In the case of a polychromatic beam that varies shot-to- + shot and where the channels also vary, this is a 2D array + of dimensions **nP** by **m** (slow to fast) with the + relative weights in ``incident_wavelength_weights`` as a 2D + array. + + Note, :ref:`variants <Design-Variants>` are a good way + to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value wavelength value is + available along with the original spectrum from which it + was calibrated. + Wavelength on entering beamline component - In the case of a polychromatic beam this is an array of - length **m** of the relative weights of the corresponding - wavelengths in ``incident_wavelength``. - - In the case of a polychromatic beam that varies shot-to- - shot, this is a 2D array of dimensions **nP** by **m** - (slow to fast) of the relative weights of the - corresponding wavelengths in ``incident_wavelength``. + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``incident_wavelength``. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **nP** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in ``incident_wavelength``. - The wavelength spread FWHM for the corresponding - wavelength(s) in incident_wavelength. - - In the case of shot-to-shot variation in the wavelength - spread, this is a 2D array of dimension **nP** by - **m** (slow to fast) of the spreads of the - corresponding wavelengths in incident_wavelength. + The wavelength spread FWHM for the corresponding + wavelength(s) in incident_wavelength. + + In the case of shot-to-shot variation in the wavelength + spread, this is a 2D array of dimension **nP** by + **m** (slow to fast) of the spreads of the + corresponding wavelengths in incident_wavelength. @@ -139,15 +184,15 @@ - Beam crossfire in degrees parallel to the laboratory X axis - - The dimension **c** is a series of moments of that represent - the standard uncertainty (e.s.d.) of the directions of - of the beam. The first and second moments are in the XZ and YZ - planes around the mean source beam direction, respectively. - - Further moments in **c** characterize co-variance terms, so - the next moment is the product of the first two, and so on. + Beam crossfire in degrees parallel to the laboratory X axis + + The dimension **c** is a series of moments of that represent + the standard uncertainty (e.s.d.) of the directions of + of the beam. The first and second moments are in the XZ and YZ + planes around the mean source beam direction, respectively. + + Further moments in **c** characterize co-variance terms, so + the next moment is the product of the first two, and so on. @@ -156,8 +201,8 @@ - Size of the beam entering this component. Note this represents - a rectangular beam aperture, and values represent FWHM + Size of the beam entering this component. Note this represents + a rectangular beam aperture, and values represent FWHM @@ -165,47 +210,90 @@ - Wavelength on leaving beamline component + + Wavelength on leaving beamline component + - Polarization vector on entering beamline component + + Incident polarization as a Stokes vector + on entering beamline component + + + + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + + - Polarization vector on leaving beamline component + + Polarization as Stokes vector on leaving beamline component + + + + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + + Polarization vector on entering beamline component using Stokes notation - + The Stokes parameters are four components labelled I,Q,U,V or S_0,S_1,S_2,S_3. These are defined with the standard Nexus coordinate frame unless it is overridden by an NXtransformations field pointed to by a depends_on attribute. The last component, describing the circular polarization state, is positive for a right-hand circular state - that is the electric field vector rotates clockwise at the sample and over time when observed from the source. - - I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale + + I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale linearly with the total degree of polarization, and indicate the relative magnitudes of the pure linear and circular orientation contributions. Q (S_1) is linearly polarized along the x axis (Q > 0) or y axis (Q < 0). U (S_2) is linearly polarized along the x==y axis (U > 0) or the - -x==y axis (U < 0). - + -x==y axis (U < 0). + V (S_3) is circularly polarized. V > 0 when the electric field vector rotates - clockwise at the sample with respect to time when observed from the source; + clockwise at the sample with respect to time when observed from the source; V < 0 indicates the opposite rotation. @@ -224,112 +312,177 @@ - Wavelength spread FWHM of beam leaving this component + + Wavelength spread FWHM of beam leaving this component + - Divergence FWHM of beam leaving this component + + Divergence FWHM of beam leaving this component + - flux incident on beam plane area + + flux incident on beam plane area + + + + Energy of a single pulse at the diagnostic point + + + + + Average power at the diagnostic point + + + + + Incident fluence at the diagnostic point + + + + Here: SI units are 'J/m2', customary 'mJ/cm2'. + + + + + + FWHM duration of the pulses at the diagnostic point + + + + + FROG trace of the pulse. + + + + + + + + + Horizontal axis of a FROG trace, i.e. delay. + + + + + + + + Vertical axis of a FROG trace, i.e. frequency. + + + + + + + + The type of chirp implemented + + + + + Group delay dispersion of the pulse for linear chirp + + - Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly - useful for simulations which need to store plottable information at each beamline - component. + Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly + useful for simulations which need to store plottable information at each beamline + component. + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - - + - The NeXus coordinate system defines the Z axis to be along the nominal beam - direction. This is the same as the McStas coordinate system (see :ref:Design-CoordinateSystem). - However, the additional transformations needed to represent an altered beam - direction can be provided using this depends_on field that contains the path - to a NXtransformations group. This could represent redirection of the beam, - or a refined beam direction. + The NeXus coordinate system defines the Z axis to be along the nominal beam + direction. This is the same as the McStas coordinate system (see :ref:`Design-CoordinateSystem`). + However, the additional transformations needed to represent an altered beam + direction can be provided using this depends_on field that contains the path + to a NXtransformations group. This could represent redirection of the beam, + or a refined beam direction. - - Direction (and location) for the beam. The location of the beam can be given by - any point which it passes through as its offset attribute. + Direction (and location) for the beam. The location of the beam can be given by + any point which it passes through as its offset attribute. - + - Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] - and passes through the origin + Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] + and passes through the origin - + - Three values that define the direction of beam vector + Three values that define the direction of beam vector - Three values that define the location of a point through which the beam passes + Three values that define the location of a point through which the beam passes - Points to the path to a field defining the location on which this - depends or the string "." for origin. + Points to the path to a field defining the location on which this + depends or the string "." for origin. - + - Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. - This also defines the parallel and perpendicular components of the beam's polarization. - If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin + Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. + This also defines the parallel and perpendicular components of the beam's polarization. + If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin - + - Three values that define the direction of reference plane normal + Three values that define the direction of reference plane normal - Not required as beam direction offset locates the plane + Not required as beam direction offset locates the plane - Points to the path to a field defining the location on which this - depends or the string "." for origin. + Points to the path to a field defining the location on which this + depends or the string "." for origin. diff --git a/base_classes/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index 774c653253..408eb3a2e5 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - - - - - These symbols will be used below to coordinate fields with the same shape. - rank of the ``DATA`` field - length of the ``AXISNAME`` field - length of the ``x`` field - length of the ``y`` field - length of the ``z`` field - - - - - .. index:: plotting - - Array of strings holding the :ref:`names <validItemName>` of additional - signals to be plotted with the default :ref:`signal </NXdata@signal-attribute>`. - These fields or links *must* exist and be direct children of this NXdata group. - - Each auxiliary signal needs to be of the same shape as the default signal. - - .. NIAC2018: - https://www.nexusformat.org/NIAC2018Minutes.html - - - - - .. index:: find the default plottable data - .. index:: plotting - .. index:: signal attribute value - - Declares which NeXus field is the default. - The value is the :ref:`name <validItemName>` of the data field to be plotted. - This field or link *must* exist and be a direct child of this NXdata group. - - It is recommended (as of NIAC2014) to use this attribute - rather than adding a signal attribute to the field. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. - - - - - .. index:: plotting - - Array of strings holding the :ref:`names <validItemName>` of - the independent data fields used in the default plot for all of - the dimensions of the :ref:`signal </NXdata@signal-attribute>` - as well as any :ref:`auxiliary signals </NXdata@auxiliary_signals-attribute>`. - - One name is provided for every dimension in the *signal* or *auxiliary signal* fields. - - The *axes* values are the names of fields or links that *must* exist and be direct - children of this NXdata group. - - An axis slice is specified using a field named ``AXISNAME_indices`` - as described below (where the text shown here as ``AXISNAME`` is to be - replaced by the actual field name). - - When no default axis is available for a particular dimension - of the plottable data, use a "." in that position. - Such as:: - - @axes=["time", ".", "."] - - Since there are three items in the list, the *signal* field - must be a three-dimensional array (rank=3). The first dimension - is described by the values of a one-dimensional array named ``time`` - while the other two dimensions have no fields to be used as dimension scales. - - See examples provided on the NeXus wiki: - https://www.nexusformat.org/2014_axes_and_uncertainties.html - - If there are no axes at all (such as with a stack of images), - the axes attribute can be omitted. - - - - - - - Each ``AXISNAME_indices`` attribute indicates the dependency - relationship of the ``AXISNAME`` field (where ``AXISNAME`` - is the name of a field that exists in this ``NXdata`` group) - with one or more dimensions of the plottable data. - - Integer array that defines the indices of the *signal* field - (that field will be a multidimensional array) - which need to be used in the *AXISNAME* field in - order to reference the corresponding axis value. - - The first index of an array is ``0`` (zero). - - Here, *AXISNAME* is to be replaced by the name of each - field described in the ``axes`` attribute. - An example with 2-D data, :math:`d(t,P)`, will illustrate:: - - data_2d:NXdata - @signal="data" - @axes=["time", "pressure"] - @time_indices=0 - @pressure_indices=1 - data: float[1000,20] - time: float[1000] - pressure: float[20] - - This attribute is to be provided in all situations. - However, if the indices attributes are missing - (such as for data files written before this specification), - file readers are encouraged to make their best efforts - to plot the data. - Thus the implementation of the - ``AXISNAME_indices`` attribute is based on the model of - "strict writer, liberal reader". - - .. note:: Attributes potentially containing multiple values - (axes and _indices) are to be written as string or integer arrays, - to avoid string parsing in reading applications. - - - - - :ref:`NXdata` describes the plottable data and related dimension scales. - - .. index:: plotting - - It is strongly recommended that there is at least one :ref:`NXdata` - group in each :ref:`NXentry` group. - Note that the fields named ``AXISNAME`` and ``DATA`` - can be defined with different names. - (Upper case is used to indicate that the actual name is left to the user.) - The ``signal`` and ``axes`` attributes of the - ``data`` group define which items - are plottable data and which are *dimension scales*, respectively. - - :ref:`NXdata` is used to implement one of the basic motivations in NeXus, - to provide a default plot for the data of this :ref:`NXentry`. The actual data - might be stored in another group and (hard) linked to the :ref:`NXdata` group. - - * Each :ref:`NXdata` group will define one field as the default - plottable data. The value of the ``signal`` attribute names this field. - Additional fields may be used to describe the dimension scales and - uncertainities. - The ``auxiliary_signals`` attribute is a list of the other fields - to be plotted with the ``signal`` data. - * The plottable data may be of arbitrary rank up to a maximum - of ``NX_MAXRANK=32`` (for compatibility with backend file formats). - * The plottable data will be named as the value of - the group ``signal`` attribute, such as:: - - data:NXdata - @signal = "counts" - @axes = "mr" - @mr_indices = 0 - counts: float[100] --> the default dependent data - mr: float[100] --> the default independent data - - The field named in the ``signal`` attribute **must** exist, either - directly as a NeXus field or defined through a link. - - * The group ``axes`` attribute will name the - *dimension scale* associated with the plottable data. - - If available, the standard deviations of the data are to be - stored in a data set of the same rank and dimensions, with the name ``errors``. - - * For each data dimension, there should be a one-dimensional array - of the same length. - * These one-dimensional arrays are the *dimension scales* of the - data, *i.e*. the values of the independent variables at which the data - is measured, such as scattering angle or energy transfer. - - .. index:: link - .. index:: axes (attribute) - - The preferred method to associate each data dimension with - its respective dimension scale is to specify the field name - of each dimension scale in the group ``axes`` attribute as a string list. - Here is an example for a 2-D data set *data* plotted - against *time*, and *pressure*. (An additional *temperature* data set - is provided and could be selected as an alternate for the *pressure* axis.):: - - data_2d:NXdata - @signal="data" - @axes=["time", "pressure"] - @pressure_indices=1 - @temperature_indices=1 - @time_indices=0 - data: float[1000,20] - pressure: float[20] - temperature: float[20] - time: float[1000] - - .. rubric:: Old methods to identify the plottable data - - There are two older methods of associating - each data dimension to its respective dimension scale. - Both are now out of date and - should not be used when writing new data files. - However, client software should expect to see data files - written with any of these methods. - - * One method uses the ``axes`` - attribute to specify the names of each *dimension scale*. - - * The oldest method uses the ``axis`` attribute on each - *dimension scale* to identify - with an integer the axis whose value is the number of the dimension. - - .. index: !plot; axis label - plot, axis units - units - dimension scale - - Each axis of the plot may be labeled with information from the - dimension scale for that axis. The optional ``@long_name`` attribute - is provided as the axis label default. If ``@long_name`` is not - defined, then use the name of the dimension scale. A ``@units`` attribute, - if available, may be added to the axis label for further description. - See the section :ref:`Design-Units` for more information. - - .. index: !plot; axis title - - The optional ``title`` field, if available, provides a suggested - title for the plot. If no ``title`` field is found in the :ref:`NXdata` - group, look for a ``title`` field in the parent :ref:`NXentry` group, - with a fallback to displaying the path to the :ref:`NXdata` group. - - NeXus is about how to find and annotate the data to be plotted - but not to describe how the data is to be plotted. - (https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute) - - - - Dimension scale defining an axis of the data. - Client is responsible for defining the dimensions of the data. - The name of this field may be changed to fit the circumstances. - Standard NeXus client tools will use the attributes to determine - how to use this field. - - - - A *dimension scale* must have a rank of 1 and has length ``n``. - - - - Axis label - - - ``0|false``: single value, - ``1|true``: multiple values - - - Index of first good value - Index of last good value - - - Index (positive integer) identifying this specific set of numbers. - - N.B. The ``axis`` attribute is the old way of designating a link. - Do not use the ``axes`` attribute with the ``axis`` attribute. - The ``axes`` *group* attribute is now preferred. - - - - - - "Errors" (meaning *uncertainties* or *standard deviations*) - associated with any field named ``FIELDNAME`` in this ``NXdata`` - group (e.g. an axis, signal or auxiliary signal). - - The dimensions of the ``FIELDNAME_errors`` field must match - the dimensions of the ``FIELDNAME`` field. - - - - - .. index:: plotting - - This field contains the data values to be used as the - NeXus *plottable data*. - Client is responsible for defining the dimensions of the data. - The name of this field may be changed to fit the circumstances. - Standard NeXus client tools will use the attributes to determine - how to use this field. - - - - The rank (``dataRank``) of the ``data`` must satisfy - ``1 <= dataRank <= NX_MAXRANK=32``. - At least one ``dim`` must have length ``n``. - - - - - .. index:: plotting - - Plottable (independent) axis, indicate index number. - Only one field in a :ref:`NXdata` group may have the - ``signal=1`` attribute. - Do not use the ``signal`` attribute with the ``axis`` attribute. - - - - - Defines the names of the dimension scales - (independent axes) for this data set - as a colon-delimited array. - NOTE: The ``axes`` attribute is the preferred - method of designating a link. - Do not use the ``axes`` attribute with the ``axis`` attribute. - - - - data label - - - - - Standard deviations of data values - - the data array is identified by the group attribute ``signal``. - The ``errors`` array must have the same dimensions as ``DATA``. - Client is responsible for defining the dimensions of the data. - - - - The ``errors`` must have - the same rank (``dataRank``) - as the ``data``. - At least one ``dim`` must have length "n". - - - - - - The elements in data are usually float values really. For - efficiency reasons these are usually stored as integers - after scaling with a scale factor. This value is the scale - factor. It is required to get the actual physical value, - when necessary. - - - - - An optional offset to apply to the values in data. - - - - - Title for the plot. - - - - - This is an array holding the values to use for the x-axis of - data. The units must be appropriate for the measurement. - - - - - - - - This is an array holding the values to use for the y-axis of - data. The units must be appropriate for the measurement. - - - - - - - - This is an array holding the values to use for the z-axis of - data. The units must be appropriate for the measurement. - - - - - + + + + + These symbols will be used below to coordinate fields with the same + shape. + + + + rank of the ``DATA`` field + + + + + length of the ``AXISNAME`` field + + + + + length of the ``x`` field + + + + + length of the ``y`` field + + + + + length of the ``z`` field + + + + + :ref:`NXdata` describes the plottable data and related dimension scales. + + .. index:: plotting + + It is strongly recommended that there is at least one :ref:`NXdata` + group in each :ref:`NXentry` group. + Note that the fields named ``AXISNAME`` and ``DATA`` + can be defined with different names. + (Upper case is used to indicate that the actual name is left to the user.) + The ``signal`` and ``axes`` attributes of the + ``data`` group define which items + are plottable data and which are *dimension scales*, respectively. + + :ref:`NXdata` is used to implement one of the basic motivations in NeXus, + to provide a default plot for the data of this :ref:`NXentry`. The actual data + might be stored in another group and (hard) linked to the :ref:`NXdata` group. + + * Each :ref:`NXdata` group will define one field as the default + plottable data. The value of the ``signal`` attribute names this field. + Additional fields may be used to describe the dimension scales and + uncertainities. + The ``auxiliary_signals`` attribute is a list of the other fields + to be plotted with the ``signal`` data. + * The plottable data may be of arbitrary rank up to a maximum + of ``NX_MAXRANK=32`` (for compatibility with backend file formats). + * The plottable data will be named as the value of + the group ``signal`` attribute, such as:: + + data:NXdata + @signal = "counts" + @axes = "mr" + @mr_indices = 0 + counts: float[100] --> the default dependent data + mr: float[100] --> the default independent data + + The field named in the ``signal`` attribute **must** exist, either + directly as a NeXus field or defined through a link. + + * The group ``axes`` attribute will name the + *dimension scale* associated with the plottable data. + + If available, the standard deviations of the data are to be + stored in a data set of the same rank and dimensions, with the name ``errors``. + + * For each data dimension, there should be a one-dimensional array + of the same length. + * These one-dimensional arrays are the *dimension scales* of the + data, *i.e*. the values of the independent variables at which the data + is measured, such as scattering angle or energy transfer. + + .. index:: link + .. index:: axes (attribute) + + The preferred method to associate each data dimension with + its respective dimension scale is to specify the field name + of each dimension scale in the group ``axes`` attribute as a string list. + Here is an example for a 2-D data set *data* plotted + against *time*, and *pressure*. (An additional *temperature* data set + is provided and could be selected as an alternate for the *pressure* axis.):: + + data_2d:NXdata + @signal="data" + @axes=["time", "pressure"] + @pressure_indices=1 + @temperature_indices=1 + @time_indices=0 + data: float[1000,20] + pressure: float[20] + temperature: float[20] + time: float[1000] + + .. rubric:: Old methods to identify the plottable data + + There are two older methods of associating + each data dimension to its respective dimension scale. + Both are now out of date and + should not be used when writing new data files. + However, client software should expect to see data files + written with any of these methods. + + * One method uses the ``axes`` + attribute to specify the names of each *dimension scale*. + + * The oldest method uses the ``axis`` attribute on each + *dimension scale* to identify + with an integer the axis whose value is the number of the dimension. + + .. index: !plot; axis label + plot, axis units + units + dimension scale + + Each axis of the plot may be labeled with information from the + dimension scale for that axis. The optional ``@long_name`` attribute + is provided as the axis label default. If ``@long_name`` is not + defined, then use the name of the dimension scale. A ``@units`` attribute, + if available, may be added to the axis label for further description. + See the section :ref:`Design-Units` for more information. + + .. index: !plot; axis title + + The optional ``title`` field, if available, provides a suggested + title for the plot. If no ``title`` field is found in the :ref:`NXdata` + group, look for a ``title`` field in the parent :ref:`NXentry` group, + with a fallback to displaying the path to the :ref:`NXdata` group. + + NeXus is about how to find and annotate the data to be plotted + but not to describe how the data is to be plotted. + (https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute) + + + + .. index:: plotting + + Array of strings holding the :ref:`names <validItemName>` of additional + signals to be plotted with the default :ref:`signal </NXdata@signal-attribute>`. + These fields or links *must* exist and be direct children of this NXdata group. + + Each auxiliary signal needs to be of the same shape as the default signal. + + .. NIAC2018: + https://www.nexusformat.org/NIAC2018Minutes.html + + + + + .. index:: find the default plottable data + .. index:: plotting + .. index:: signal attribute value + + Declares which NeXus field is the default. + The value is the :ref:`name <validItemName>` of the data field to be plotted. + This field or link *must* exist and be a direct child of this NXdata group. + + It is recommended (as of NIAC2014) to use this attribute + rather than adding a signal attribute to the field. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + + + .. index:: plotting + + Array of strings holding the :ref:`names <validItemName>` of + the independent data fields used in the default plot for all of + the dimensions of the :ref:`signal </NXdata@signal-attribute>` + as well as any :ref:`auxiliary signals </NXdata@auxiliary_signals-attribute>`. + + One name is provided for every dimension in the *signal* or *auxiliary signal* fields. + + The *axes* values are the names of fields or links that *must* exist and be direct + children of this NXdata group. + + An axis slice is specified using a field named ``AXISNAME_indices`` + as described below (where the text shown here as ``AXISNAME`` is to be + replaced by the actual field name). + + When no default axis is available for a particular dimension + of the plottable data, use a "." in that position. + Such as:: + + @axes=["time", ".", "."] + + Since there are three items in the list, the *signal* field + must be a three-dimensional array (rank=3). The first dimension + is described by the values of a one-dimensional array named ``time`` + while the other two dimensions have no fields to be used as dimension scales. + + See examples provided on the NeXus wiki: + https://www.nexusformat.org/2014_axes_and_uncertainties.html + + If there are no axes at all (such as with a stack of images), + the axes attribute can be omitted. + + + + + + + Each ``AXISNAME_indices`` attribute indicates the dependency + relationship of the ``AXISNAME`` field (where ``AXISNAME`` + is the name of a field that exists in this ``NXdata`` group) + with one or more dimensions of the plottable data. + + Integer array that defines the indices of the *signal* field + (that field will be a multidimensional array) + which need to be used in the *AXISNAME* field in + order to reference the corresponding axis value. + + The first index of an array is ``0`` (zero). + + Here, *AXISNAME* is to be replaced by the name of each + field described in the ``axes`` attribute. + An example with 2-D data, :math:`d(t,P)`, will illustrate:: + + data_2d:NXdata + @signal="data" + @axes=["time", "pressure"] + @time_indices=0 + @pressure_indices=1 + data: float[1000,20] + time: float[1000] + pressure: float[20] + + This attribute is to be provided in all situations. + However, if the indices attributes are missing + (such as for data files written before this specification), + file readers are encouraged to make their best efforts + to plot the data. + Thus the implementation of the + ``AXISNAME_indices`` attribute is based on the model of + "strict writer, liberal reader". + + .. note:: Attributes potentially containing multiple values + (axes and _indices) are to be written as string or integer arrays, + to avoid string parsing in reading applications. + + + + + Points to the path of a field defining the axis on which the ``AXISNAME`` axis depends. + + This concept allows to link an axis to a respective field in the NeXus hierarchy, thereby + defining the physical quantity it represents. + + Here, *AXISNAME* is to be replaced by the name of each + field described in the ``axes`` attribute. + + Examples: + If a calibration has been performed, ``@AXISNAME_depends`` links to the result of + that calibration: + + @AXISNAME_depends: '/entry/process/calibration/calibrated_axis' + + If the axis corresponds to a coordinate of a detector, ``@AXISNAME_depends`` links + to that detector axis: + + @AXISNAME_depends: '/entry/instrument/detector/axis/some_axis' for a 2D detector + + If the axis is a scanned motor, ``@AXISNAME_depends`` links to the transformation + describing the respective motion, e.g.: + + @AXISNAME_depends: '/entry/instrument/detector/transformations/some_transformation' for a motion of the detector + + + + + Dimension scale defining an axis of the data. + Client is responsible for defining the dimensions of the data. + The name of this field may be changed to fit the circumstances. + Standard NeXus client tools will use the attributes to determine + how to use this field. + + + + A *dimension scale* must have a rank of 1 and has length ``n``. + + + + + + Axis label + + + + + ``0|false``: single value, + ``1|true``: multiple values + + + + + Index of first good value + + + + + Index of last good value + + + + + Index (positive integer) identifying this specific set of numbers. + + N.B. The ``axis`` attribute is the old way of designating a link. + Do not use the ``axes`` attribute with the ``axis`` attribute. + The ``axes`` *group* attribute is now preferred. + + + + + + "Errors" (meaning *uncertainties* or *standard deviations*) + associated with any field named ``FIELDNAME`` in this ``NXdata`` + group (e.g. an axis, signal or auxiliary signal). + + The dimensions of the ``FIELDNAME_errors`` field must match + the dimensions of the ``FIELDNAME`` field. + + + + + .. index:: plotting + + This field contains the data values to be used as the + NeXus *plottable data*. + Client is responsible for defining the dimensions of the data. + The name of this field may be changed to fit the circumstances. + Standard NeXus client tools will use the attributes to determine + how to use this field. + + + + The rank (``dataRank``) of the ``data`` must satisfy + ``1 <= dataRank <= NX_MAXRANK=32``. + At least one ``dim`` must have length ``n``. + + + + + .. index:: plotting + + Plottable (independent) axis, indicate index number. + Only one field in a :ref:`NXdata` group may have the + ``signal=1`` attribute. + Do not use the ``signal`` attribute with the ``axis`` attribute. + + + + + Defines the names of the dimension scales + (independent axes) for this data set + as a colon-delimited array. + NOTE: The ``axes`` attribute is the preferred + method of designating a link. + Do not use the ``axes`` attribute with the ``axis`` attribute. + + + + + data label + + + + + + Standard deviations of data values - + the data array is identified by the group attribute ``signal``. + The ``errors`` array must have the same dimensions as ``DATA``. + Client is responsible for defining the dimensions of the data. + + + + The ``errors`` must have + the same rank (``dataRank``) + as the ``data``. + At least one ``dim`` must have length "n". + + + + + + The elements in data are usually float values really. For + efficiency reasons these are usually stored as integers + after scaling with a scale factor. This value is the scale + factor. It is required to get the actual physical value, + when necessary. + + + + + An optional offset to apply to the values in data. + + + + + Title for the plot. + + + + + This is an array holding the values to use for the x-axis of + data. The units must be appropriate for the measurement. + + + + + + + + This is an array holding the values to use for the y-axis of + data. The units must be appropriate for the measurement. + + + + + + + + This is an array holding the values to use for the z-axis of + data. The units must be appropriate for the measurement. + + + + + diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index a6bb0b8c68..d43803c732 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -1,10 +1,10 @@ - + - - - - - These symbols will be used below to illustrate the coordination of the rank and sizes of datasets and the - preferred ordering of the dimensions. Each of these are optional (so the rank of the datasets - will vary according to the situation) and the general ordering principle is slowest to fastest. - The type of each dimension should follow the order of scan points, detector output (e.g. pixels), - then time-of-flight (i.e. spectroscopy, spectrometry). Note that the output of a detector is not limited - to single values (0D), lists (1D) and images (2), but three or higher dimensional arrays can be produced - by a detector at each trigger. - - - number of scan points (only present in scanning measurements) - number of detector pixels in the first (slowest) direction - number of detector pixels in the second (faster) direction - number of bins in the time-of-flight histogram - - - - A detector, detector bank, or multidetector. - - - - Total time of flight - - - - - - - - - - - - - - - - - - - Total time of flight - - - - - In DAQ clock pulses - - - - - - - Clock frequency in Hz - - - - - - Identifier for detector (pixels) - Can be multidimensional, if needed - - - - - - Data values from the detector. The rank and dimension ordering should follow a principle of - slowest to fastest measurement axes and may be explicitly specified in application definitions. - - Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be - the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions - of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single - scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. - Repetition of an experiment in a time series tends to be used similar to a slow scan axis - and so will often be in the first dimension of the data array. - - The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions - (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an - imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data - will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to - be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. - - Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift - detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. - - The type of each dimension should should follow the order of scan points, detector pixels, - then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) - shown here are merely illustrative of coordination between related datasets. - - - - - - - - - - - Title of measurement - - - - Integral of data as check of data integrity - - - - - - - The best estimate of the uncertainty in the data value (array size should match the data field). Where - possible, this should be the standard deviation, which has the same units - as the data. The form data_error is deprecated. - - - - - - - - - - - - - - Offset from the detector center in x-direction. - Can be multidimensional when needed. - - - - - - - - - - - - - - - - - - - - - x-axis offset from detector center - - - - - - Offset from the detector center in the y-direction. - Can be multidimensional when different values are required for each pixel. - - - - - - - - - - - - - - - - - - - - - y-axis offset from detector center - - - - - - - Offset from the detector center in the z-direction. - Can be multidimensional when different values are required for each pixel. - - - - - - - - - - - - - - - - - - - - - y-axis offset from detector center - - - - - - This is the distance to the previous component in the - instrument; most often the sample. The usage depends on the - nature of the detector: Most often it is the distance of the - detector assembly. But there are irregular detectors. In this - case the distance must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - - This is the polar angle of the detector towards the previous - component in the instrument; most often the sample. - The usage depends on the - nature of the detector. - Most often it is the polar_angle of the detector assembly. - But there are irregular detectors. - In this - case, the polar_angle must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - - This is the azimuthal angle angle of the detector towards - the previous component in the instrument; most often the sample. - The usage depends on the - nature of the detector. - Most often it is the azimuthal_angle of the detector assembly. - But there are irregular detectors. - In this - case, the azimuthal_angle must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - name/manufacturer/model/etc. information - - - - Serial number for the detector - - - - Local name for the detector - - - - Position and orientation of detector - - - - Solid angle subtended by the detector at the sample - - - - - - - - - - Size of each detector pixel. If it is scalar all pixels are the same size. - - - - - - - - - - Size of each detector pixel. If it is scalar all pixels are the same size - - - - - - - - - Detector dead time - - - - - - - - - - Detector gas pressure - - - - - - - - - maximum drift space dimension - - - - Crate number of detector - - - - - - - - Equivalent local term - - - - - Slot number of detector - - - - - - - - Equivalent local term - - - - - Input number of detector - - - - - - - - Equivalent local term - - - - - - Description of type such as He3 gas cylinder, He3 PSD, scintillator, - fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, - CMOS, ... - - - - - Spectral efficiency of detector with respect to e.g. wavelength - - - - - - - - - - - - - - - - - - - - - - - - efficiency of the detector - - - - - - - - - - This field can be two things: - - #. For a pixel detector it provides the nominal wavelength - for which the detector has been calibrated. - - #. For other detectors this field has to be seen together with - the efficiency field above. - For some detectors, the efficiency is wavelength dependent. - Thus this field provides the wavelength axis for the efficiency field. - In this use case, the efficiency and wavelength arrays must - have the same dimensionality. - - - - - - - - - - - - Real-time of the exposure (use this if exposure time varies for - each array element, otherwise use ``count_time`` field). - - Most often there is a single real time value that is constant across - an entire image frame. In such cases, only a 1-D array is needed. - But there are detectors in which the real time - changes per pixel. In that case, more than one dimension is needed. Therefore - the rank of this field should be less than or equal to (detector rank + 1). - - - - - - - - - - start time for each frame, with the ``start`` attribute as absolute reference - - - - - - - stop time for each frame, with the ``start`` attribute as absolute reference - - - - - - - - - date of last calibration (geometry and/or efficiency) measurements - - - - - - summary of conversion of array data to pixels (e.g. polynomial - approximations) and location of details of the calibrations - - - - - How the detector is represented - - - - - - - - - - Elapsed actual counting time - - - - - - - - - - - Use this group to provide other data related to this NXdetector group. - - - - - - In order to properly sort the order of the images taken in (for - example) a tomography experiment, a sequence number is stored with each - image. - - - - - - - - - - This is the x position where the direct beam would hit the detector. - This is a length and can be outside of the actual - detector. The length can be in physical units or pixels - as documented by the units attribute. - - - - - - This is the y position where the direct beam would hit the detector. - This is a length and can be outside of the actual - detector. The length can be in physical units or pixels - as documented by the units attribute. - - - - - - This is the start number of the first frame of a scan. In protein crystallography measurements one - often scans a couple of frames on a give sample, then does something else, - then returns to the same sample and scans some more frames. Each time with - a new data file. This number helps concatenating such measurements. - - - - - The diameter of a cylindrical detector - - - - The acquisition mode of the detector. - - - - - - - - - - - - True when the angular calibration has been applied in the - electronics, false otherwise. - - - - Angular calibration data. - - - - - - - - True when the flat field correction has been applied in the - electronics, false otherwise. - - - - Flat field correction data. - - - - - - - - Errors of the flat field correction data. - The form flatfield_error is deprecated. - - - - - - - - - True when the pixel mask correction has been applied in the - electronics, false otherwise. - - - - - The 32-bit pixel mask for the detector. Can be either one mask - for the whole dataset (i.e. an array with indices i, j) or - each frame can have its own mask (in which case it would be - an array with indices np, i, j). - - Contains a bit field for each pixel to signal dead, - blind or high or otherwise unwanted or undesirable pixels. - They have the following meaning: - - .. can't make a table here, a bullet list will have to do for now - - * bit 0: gap (pixel with no sensor) - * bit 1: dead - * bit 2: under responding - * bit 3: over responding - * bit 4: noisy - * bit 5: -undefined- - * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) - * bit 7: -undefined- - * bit 8: user defined mask (e.g. around beamstop) - * bits 9-30: -undefined- - * bit 31: virtual pixel (corner pixel with interpolated value) - - Normal data analysis software would - not take pixels into account - when a bit in (mask & 0x0000FFFF) is - set. Tag bit in the upper - two bytes would indicate special pixel - properties that normally - would not be a sole reason to reject the - intensity value (unless - lower bits are set. - - If the full bit depths is not required, providing a - mask with fewer bits is permissible. - - If needed, additional pixel masks can be specified by - including additional entries named pixel_mask_N, where - N is an integer. For example, a general bad pixel mask - could be specified in pixel_mask that indicates noisy - and dead pixels, and an additional pixel mask from - experiment-specific shadowing could be specified in - pixel_mask_2. The cumulative mask is the bitwise OR - of pixel_mask and any pixel_mask_N entries. - - - - - - - - - - This field allow to distinguish different types of exposure to the same detector "data" field. - Some techniques require frequent (re-)calibration inbetween measuremnts and this way of - recording the different measurements preserves the chronological order with is important for - correct processing. - - This is used for example in tomography (`:ref:`NXtomo`) sample projections, - dark and flat images, a magic number is recorded per frame. - - The key is as follows: - - * projection (sample) = 0 - * flat field = 1 - * dark field = 2 - * invalid = 3 - * background (no sample, but buffer where applicable) = 4 - - In cases where the data is of type :ref:`NXlog` this can also be an NXlog. - - - - - - - - - Counting detectors usually are not able to measure all incoming particles, - especially at higher count-rates. Count-rate correction is applied to - account for these errors. - - True when count-rate correction has been applied, false otherwise. - - - - - The countrate_correction_lookup_table defines the LUT used for count-rate - correction. It maps a measured count :math:`c` to its corrected value - :math:`countrate\_correction\_lookup\_table[c]`. - - :math:`m` denotes the length of the table. - - - - - - - - True when virtual pixel interpolation has been applied, false otherwise. - - When virtual pixel interpolation is applied, values of some pixels may - contain interpolated values. For example, to account for space between - readout chips on a module, physical pixels on edges and corners between - chips may have larger sensor areas and counts may be distributed between - their logical pixels. - - - - - How many bits the electronics reads per pixel. - With CCD's and single photon counting detectors, - this must not align with traditional integer sizes. - This can be 4, 8, 12, 14, 16, ... - - - - - Time it takes to read the detector (typically milliseconds). - This is important to know for time resolved experiments. - - - - - Time it takes to start exposure after a trigger signal has been received. - This is the reaction time of the detector firmware after receiving the trigger signal - to when the detector starts to acquire the exposure, including any user set delay.. - This is important to know for time resolved experiments. - - - - - User-specified trigger delay. - - - - - Time it takes to start exposure after a trigger signal has been received. - This is the reaction time of the detector hardware after receiving the - trigger signal to when the detector starts to acquire the exposure. - It forms the lower boundary of the trigger_delay_time when the user - does not request an additional delay. - - - - - Time during which no new trigger signal can be accepted. - Typically this is the - trigger_delay_time + exposure_time + readout_time. - This is important to know for time resolved experiments. - - - - - This is time for each frame. This is exposure_time + readout time. - - - - - - - - The gain setting of the detector. This is a detector-specific value - meant to document the gain setting of the detector during data - collection, for detectors with multiple available gain settings. - - Examples of gain settings include: - - * ``standard`` - * ``fast`` - * ``auto`` - * ``high`` - * ``medium`` - * ``low`` - * ``mixed high to medium`` - * ``mixed medium to low`` - - Developers are encouraged to use one of these terms, or to submit - additional terms to add to the list. - - - - - The value at which the detector goes into saturation. - Especially common to CCD detectors, the data - is known to be invalid above this value. - - For example, given a saturation_value and an underload_value, the valid - pixels are those less than or equal to the saturation_value and greater - than or equal to the underload_value. - - The precise type should match the type of the data. - - - - - The lowest value at which pixels for this detector would be reasonably - measured. The data is known to be invalid below this value. - - For example, given a saturation_value and an underload_value, the valid - pixels are those less than or equal to the saturation_value and greater - than or equal to the underload_value. - - The precise type should match the type of the data. - - - - - CCD images are sometimes constructed by summing - together multiple short exposures in the - electronics. This reduces background etc. - This is the number of short exposures used to sum - images for an image. - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. - This is the name of this converter material. - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. - This is the thickness of this converter material. - - - - - Single photon counter detectors can be adjusted - for a certain energy range in which they - work optimally. This is the energy setting for this. - - - - - For use in special cases where the data in NXdetector - is represented in several parts, each with a separate geometry. - - - - - - Shape description of each pixel. Use only if all pixels in the detector - are of uniform shape. - + + + + These symbols will be used below to illustrate the coordination of the + rank and sizes of datasets and the preferred ordering of the + dimensions. Each of these are optional (so the rank of the datasets + will vary according to the situation) and the general ordering + principle is slowest to fastest. The type of each dimension should + follow the order of scan points, detector output (e.g. pixels), then + time-of-flight (i.e. spectroscopy, spectrometry). Note that the output + of a detector is not limited to single values (0D), lists (1D) and + images (2), but three or higher dimensional arrays can be produced by + a detector at each trigger. + + + + number of scan points (only present in scanning measurements) + + + + + number of detector pixels in the first (slowest) direction + + + + + number of detector pixels in the second (faster) direction + + + + + number of detector pixels in the third (if necessary, fastest) + direction + + + + + number of bins in the time-of-flight histogram + + + + + A detector, detector bank, or multidetector. + + + + Total time of flight + + + + + + + + + + + + + + + + + Total time of flight + + + + + + In DAQ clock pulses + + + + + + + Clock frequency in Hz + + + + + + Identifier for detector (pixels) + Can be multidimensional, if needed + + + + + Data values from the detector. The rank and dimension ordering should follow a principle of + slowest to fastest measurement axes and may be explicitly specified in application definitions. + + Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be + the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions + of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single + scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. + Repetition of an experiment in a time series tends to be used similar to a slow scan axis + and so will often be in the first dimension of the data array. + + The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions + (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an + imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data + will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to + be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. + + Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift + detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. + + The type of each dimension should should follow the order of scan points, detector pixels, + then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) + shown here are merely illustrative of coordination between related datasets. + + + + + + + + + + Title of measurement + + + + + Integral of data as check of data integrity + + + + + + The best estimate of the uncertainty in the data value (array size should match the data field). Where + possible, this should be the standard deviation, which has the same units + as the data. The form data_error is deprecated. + + + + + + + + + + + Offset from the detector center in x-direction. + Can be multidimensional when needed. + + + + + + + + + + + + + + + + + + x-axis offset from detector center + + + + + + Offset from the detector center in the y-direction. + Can be multidimensional when different values are required for each pixel. + + + + + + + + + + + + + + + + + + y-axis offset from detector center + + + + + + Offset from the detector center in the z-direction. + Can be multidimensional when different values are required for each pixel. + + + + + + + + + + + + + + + + + + y-axis offset from detector center + + + + + + This is the distance to the previous component in the + instrument; most often the sample. The usage depends on the + nature of the detector: Most often it is the distance of the + detector assembly. But there are irregular detectors. In this + case the distance must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + This is the polar angle of the detector towards the previous + component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the polar_angle of the detector assembly. + But there are irregular detectors. + In this + case, the polar_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + This is the azimuthal angle angle of the detector towards + the previous component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the azimuthal_angle of the detector assembly. + But there are irregular detectors. + In this + case, the azimuthal_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + name/manufacturer/model/etc. information + + + + + Serial number for the detector + + + + + Local name for the detector + + + + + Position and orientation of detector + + + + + Solid angle subtended by the detector at the sample + + + + + + + + + Size of each detector pixel. If it is scalar all pixels are the same size. + + + + + + + + + Size of each detector pixel. If it is scalar all pixels are the same size + + + + + + + + + Detector dead time + + + + + + + + + + Detector gas pressure + + + + + + + + + maximum drift space dimension + + + + + Crate number of detector + + + + + + + + Equivalent local term + + + + + + Slot number of detector + + + + + + + + Equivalent local term + + + + + + Input number of detector + + + + + + + + Equivalent local term + + + + + + Description of type such as He3 gas cylinder, He3 PSD, scintillator, + fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, + CMOS, ... + + + + + Spectral efficiency of detector with respect to e.g. wavelength + + + + + + + + + + + + + + + + + + + + + + + + + efficiency of the detector + + + + + + + + + + This field can be two things: + + 1. For a pixel detector it provides the nominal wavelength + for which the detector has been calibrated. + + 2. For other detectors this field has to be seen together with + the efficiency field above. + For some detectors, the efficiency is wavelength dependent. + Thus this field provides the wavelength axis for the efficiency field. + In this use case, the efficiency and wavelength arrays must + have the same dimensionality. + + + + + + + + + + + Real-time of the exposure (use this if exposure time varies for + each array element, otherwise use ``count_time`` field). + + Most often there is a single real time value that is constant across + an entire image frame. In such cases, only a 1-D array is needed. + But there are detectors in which the real time + changes per pixel. In that case, more than one dimension is needed. Therefore + the rank of this field should be less than or equal to (detector rank + 1). + + + + + + + + + + start time for each frame, with the ``start`` attribute as absolute reference + + + + + + + + + stop time for each frame, with the ``start`` attribute as absolute reference + + + + + + + + + date of last calibration (geometry and/or efficiency) measurements + + + + + summary of conversion of array data to pixels (e.g. polynomial + approximations) and location of details of the calibrations + - - - Shape description of each pixel. Use only if all pixels in the detector - are of uniform shape and require being described by cylinders. - + + + How the detector is represented + + + + + + + + + + Elapsed actual counting time + + + + + + + + + Use this group to provide other data related to this NXdetector group. + - - - - - Shape description of the whole detector. Use only if pixels in the - detector are not of uniform shape. - + + + In order to properly sort the order of the images taken in (for + example) a tomography experiment, a sequence number is stored with each + image. + + + + + + + + This is the x position where the direct beam would hit the detector. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. + + + + + This is the y position where the direct beam would hit the detector. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. + + + + + This is the start number of the first frame of a scan. In protein crystallography measurements one + often scans a couple of frames on a give sample, then does something else, + then returns to the same sample and scans some more frames. Each time with + a new data file. This number helps concatenating such measurements. + + + + + The diameter of a cylindrical detector + + + + + The acquisition mode of the detector. + + + + + + + + + + + + + True when the angular calibration has been applied in the + electronics, false otherwise. + + + + + Angular calibration data. + + + + + + + + + True when the flat field correction has been applied in the + electronics, false otherwise. + + + + + Flat field correction data. + + + + + + + + + Errors of the flat field correction data. + The form flatfield_error is deprecated. + + + + + + + + + True when the pixel mask correction has been applied in the + electronics, false otherwise. + + + + + The 32-bit pixel mask for the detector. Can be either one mask + for the whole dataset (i.e. an array with indices i, j) or + each frame can have its own mask (in which case it would be + an array with indices np, i, j). + + Contains a bit field for each pixel to signal dead, + blind or high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + .. can't make a table here, a bullet list will have to do for now + + * bit 0: gap (pixel with no sensor) + * bit 1: dead + * bit 2: under responding + * bit 3: over responding + * bit 4: noisy + * bit 5: -undefined- + * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) + * bit 7: -undefined- + * bit 8: user defined mask (e.g. around beamstop) + * bits 9-30: -undefined- + * bit 31: virtual pixel (corner pixel with interpolated value) + + Normal data analysis software would + not take pixels into account + when a bit in (mask & 0x0000FFFF) is + set. Tag bit in the upper + two bytes would indicate special pixel + properties that normally + would not be a sole reason to reject the + intensity value (unless + lower bits are set. + + If the full bit depths is not required, providing a + mask with fewer bits is permissible. + + If needed, additional pixel masks can be specified by + including additional entries named pixel_mask_N, where + N is an integer. For example, a general bad pixel mask + could be specified in pixel_mask that indicates noisy + and dead pixels, and an additional pixel mask from + experiment-specific shadowing could be specified in + pixel_mask_2. The cumulative mask is the bitwise OR + of pixel_mask and any pixel_mask_N entries. + + + + + + + + + This field allow to distinguish different types of exposure to the same detector "data" field. + Some techniques require frequent (re-)calibration inbetween measuremnts and this way of + recording the different measurements preserves the chronological order with is important for + correct processing. + + This is used for example in tomography (`:ref:`NXtomo`) sample projections, + dark and flat images, a magic number is recorded per frame. + + The key is as follows: + + * projection (sample) = 0 + * flat field = 1 + * dark field = 2 + * invalid = 3 + * background (no sample, but buffer where applicable) = 4 + + In cases where the data is of type :ref:`NXlog` this can also be an NXlog. + + + + + + + + Counting detectors usually are not able to measure all incoming particles, + especially at higher count-rates. Count-rate correction is applied to + account for these errors. + + True when count-rate correction has been applied, false otherwise. + + + + + The countrate_correction_lookup_table defines the LUT used for count-rate + correction. It maps a measured count :math:`c` to its corrected value + :math:`countrate\_correction\_lookup\_table[c]`. + + :math:`m` denotes the length of the table. + + + + + + + + True when virtual pixel interpolation has been applied, false otherwise. + + When virtual pixel interpolation is applied, values of some pixels may + contain interpolated values. For example, to account for space between + readout chips on a module, physical pixels on edges and corners between + chips may have larger sensor areas and counts may be distributed between + their logical pixels. + + + + + How many bits the electronics reads per pixel. + With CCD's and single photon counting detectors, + this must not align with traditional integer sizes. + This can be 4, 8, 12, 14, 16, ... + + + + + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + + + + + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector firmware after receiving the trigger signal + to when the detector starts to acquire the exposure, including any user set delay.. + This is important to know for time resolved experiments. + + + + + User-specified trigger delay. + + + + + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector hardware after receiving the + trigger signal to when the detector starts to acquire the exposure. + It forms the lower boundary of the trigger_delay_time when the user + does not request an additional delay. + + + + + Time during which no new trigger signal can be accepted. + Typically this is the + trigger_delay_time + exposure_time + readout_time. + This is important to know for time resolved experiments. + + + + + This is time for each frame. This is exposure_time + readout time. + + + + + + + + The gain setting of the detector. This is a detector-specific value + meant to document the gain setting of the detector during data + collection, for detectors with multiple available gain settings. + + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low`` + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. + + + + + The value at which the detector goes into saturation. + Especially common to CCD detectors, the data + is known to be invalid above this value. + + For example, given a saturation_value and an underload_value, the valid + pixels are those less than or equal to the saturation_value and greater + than or equal to the underload_value. + + The precise type should match the type of the data. + + + + + The lowest value at which pixels for this detector would be reasonably + measured. The data is known to be invalid below this value. + + For example, given a saturation_value and an underload_value, the valid + pixels are those less than or equal to the saturation_value and greater + than or equal to the underload_value. + + The precise type should match the type of the data. + + + + + CCD images are sometimes constructed by summing + together multiple short exposures in the + electronics. This reduces background etc. + This is the number of short exposures used to sum + images for an image. + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the name of this converter material. + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the thickness of this converter material. + + + + + Single photon counter detectors can be adjusted + for a certain energy range in which they + work optimally. This is the energy setting for this. + + + + + For use in special cases where the data in NXdetector + is represented in several parts, each with a separate geometry. + + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape. + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape and require being described by cylinders. + + + + + + + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape. + + + + + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape and require being described by cylinders. + + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + + + Type of electron amplifier, MCP, channeltron, etc. + + + + + Description of the detector type, DLD, Phosphor+CCD, CMOS. + + + + + Voltage applied to detector. + + + + + Voltage applied to the amplifier. + + + + + The low voltage of the amplifier migh not be the ground. + + + + + Size of each imaging sensor chip on the detector. + + + + + Number of imaging sensor chips on the detector. + + + + + Physical size of the pixels of the imaging chip on the detector. + + + + + Number of raw active elements in each dimension. Important for swept scans. + + + + + + raw data output from the detector + - - - Shape description of the whole detector. Use only if pixels in the - detector are not of uniform shape and require being described by cylinders. - + + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the detector is the center of the first pixel. + In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. + + + + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + - - - - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. - - - - - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the detector is the center of the first pixel. - In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. - - - - - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. - - diff --git a/base_classes/NXentry.nxdl.xml b/base_classes/NXentry.nxdl.xml old mode 100755 new mode 100644 index 2bb4ca533e..e5865bd60c --- a/base_classes/NXentry.nxdl.xml +++ b/base_classes/NXentry.nxdl.xml @@ -1,10 +1,10 @@ - + - - - - - .. index:: find the default plottable data - .. index:: plotting - .. index:: default attribute value - - Declares which :ref:`NXdata` group contains the data - to be shown by default. - It is used to resolve ambiguity when - one :ref:`NXdata` group exists. - The value :ref:`names <validItemName>` a child group. If that group - itself has a ``default`` attribute, continue this chain until an - :ref:`NXdata` group is reached. - - For more information about how NeXus identifies the default - plottable data, see the - :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` - section. - - - - - (**required**) :ref:`NXentry` describes the measurement. - - The top-level NeXus group which contains all the data and associated - information that comprise a single measurement. - It is mandatory that there is at least one - group of this type in the NeXus file. - - - - The data group - - .. note:: Before the NIAC2016 meeting [#]_, at least one - :ref:`NXdata` group was required in each :ref:`NXentry` group. - At the NIAC2016 meeting, it was decided to make :ref:`NXdata` - an optional group in :ref:`NXentry` groups for data files that - do not use an application definition. - It is recommended strongly that all NeXus data files provide - a NXdata group. - It is permissable to omit the NXdata group only when - defining the default plot is not practical or possible - from the available data. - - For example, neutron event data may not have anything that - makes a useful plot without extensive processing. - - Certain application definitions override this decision and - require an :ref:`NXdata` group - in the :ref:`NXentry` group. The ``minOccurs=0`` attribute - in the application definition will indicate the - :ref:`NXdata` group - is optional, otherwise, it is required. - - .. [#] NIAC2016: - https://www.nexusformat.org/NIAC2016.html, - https://github.com/nexusformat/NIAC/issues/16 - - - - - - - ISIS Muon IDF_Version - - - Extended title for entry - - - - Unique identifier for the experiment, - defined by the facility, - possibly linked to the proposals - - - - Brief summary of the experiment, including key objectives. - - - Description of the full experiment (document in pdf, latex, ...) - - - User or Data Acquisition defined group of NeXus files or NXentry - - - Brief summary of the collection, including grouping criteria. - - - unique identifier for the measurement, defined by the facility. - - - UUID identifier for the measurement. - Version of UUID used - - - - Reserved for future use by NIAC. - - See https://github.com/nexusformat/definitions/issues/382 - - - - - (alternate use: see same field in :ref:`NXsubentry` for preferred) - - Official NeXus NXDL schema to which this entry conforms which must be - the name of the NXDL file (case sensitive without the file extension) - that the NXDL schema is defined in. - - For example the ``definition`` field for a file that conformed to the - *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. - - This field is provided so that :ref:`NXentry` can be the overlay position - in a NeXus data file for an application definition and its - set of groups, fields, and attributes. - - *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. - - NXDL version number - URL of NXDL file - - - - Local NXDL schema extended from the entry - specified in the ``definition`` field. - This contains any locally-defined, - additional fields in the entry. - - NXDL version number - URL of NXDL file - - - Starting time of measurement - - - Ending time of measurement - - - Duration of measurement - - - - Time transpired actually collecting data i.e. taking out time when collection was - suspended due to e.g. temperature out of range - - - - Such as "2007-3". Some user facilities organize their beam time into run cycles. - - - Name of program used to generate this file - Program version number - configuration of the program - - - - Revision id of the file due to re-calibration, reprocessing, new analysis, new - instrument definition format, ... - - - - - - This is the flightpath before the sample position. This can be determined by a chopper, - by the moderator or the source itself. In other words: it the distance to the component - which gives the T0 signal to the detector electronics. If another component in the - NXinstrument hierarchy provides this information, this should be a link. - - - - Notes describing entry - - - - A small image that is representative of the entry. An example of this is a 640x480 - jpeg image automatically produced by a low resolution plot of the NXdata. - - - The mime type should be an ``image/*`` - - - - - - - - - - - - - - + + + (**required**) :ref:`NXentry` describes the measurement. + + The top-level NeXus group which contains all the data and associated + information that comprise a single measurement. + It is mandatory that there is at least one + group of this type in the NeXus file. + + + + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXdata` group contains the data + to be shown by default. + It is used to resolve ambiguity when + one :ref:`NXdata` group exists. + The value :ref:`names <validItemName>` a child group. If that group + itself has a ``default`` attribute, continue this chain until an + :ref:`NXdata` group is reached. + + For more information about how NeXus identifies the default + plottable data, see the + :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` + section. + + + + + The data group + + .. note:: Before the NIAC2016 meeting [#]_, at least one + :ref:`NXdata` group was required in each :ref:`NXentry` group. + At the NIAC2016 meeting, it was decided to make :ref:`NXdata` + an optional group in :ref:`NXentry` groups for data files that + do not use an application definition. + It is recommended strongly that all NeXus data files provide + a NXdata group. + It is permissable to omit the NXdata group only when + defining the default plot is not practical or possible + from the available data. + + For example, neutron event data may not have anything that + makes a useful plot without extensive processing. + + Certain application definitions override this decision and + require an :ref:`NXdata` group + in the :ref:`NXentry` group. The ``minOccurs=0`` attribute + in the application definition will indicate the + :ref:`NXdata` group + is optional, otherwise, it is required. + + .. [#] NIAC2016: + https://www.nexusformat.org/NIAC2016.html, + https://github.com/nexusformat/NIAC/issues/16 + + + + + + ISIS Muon IDF_Version + + + + + Extended title for entry + + + + + Unique identifier for the experiment, + defined by the facility, + possibly linked to the proposals + + + + + Brief summary of the experiment, including key objectives. + + + + + Description of the full experiment (document in pdf, latex, ...) + + + + + User or Data Acquisition defined group of NeXus files or NXentry + + + + + Brief summary of the collection, including grouping criteria. + + + + + unique identifier for the measurement, defined by the facility. + + + + + UUID identifier for the measurement. + + + + Version of UUID used + + + + + + Reserved for future use by NIAC. + + See https://github.com/nexusformat/definitions/issues/382 + + + + + (alternate use: see same field in :ref:`NXsubentry` for preferred) + + Official NeXus NXDL schema to which this entry conforms which must be + the name of the NXDL file (case sensitive without the file extension) + that the NXDL schema is defined in. + + For example the ``definition`` field for a file that conformed to the + *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. + + This field is provided so that :ref:`NXentry` can be the overlay position + in a NeXus data file for an application definition and its + set of groups, fields, and attributes. + + *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. + + + + NXDL version number + + + + + URL of NXDL file + + + + + + Local NXDL schema extended from the entry + specified in the ``definition`` field. + This contains any locally-defined, + additional fields in the entry. + + + + NXDL version number + + + + + URL of NXDL file + + + + + + Starting time of measurement + + + + + Ending time of measurement + + + + + Duration of measurement + + + + + Time transpired actually collecting data i.e. taking out time when collection was + suspended due to e.g. temperature out of range + + + + + Such as "2007-3". Some user facilities organize their beam time into run cycles. + + + + + Name of program used to generate this file + + + + Program version number + + + + + configuration of the program + + + + + + Revision id of the file due to re-calibration, reprocessing, new analysis, new + instrument definition format, ... + + + + + + This is the flightpath before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + + + + + Notes describing entry + + + + + A small image that is representative of the entry. An example of this is a 640x480 + jpeg image automatically produced by a low resolution plot of the NXdata. + + + + The mime type should be an ``image/*`` + + + + + + + + + + City and country where the experiment took place + + + + + Start time of experimental run that includes the current + measurement, for example a beam time. + + + + + End time of experimental run that includes the current + measurement, for example a beam time. + + + + + Name of the institution hosting the facility + + + + + Name of the experimental facility + + + + + Name of the laboratory or beamline + + + + + + + + + + diff --git a/base_classes/NXenvironment.nxdl.xml b/base_classes/NXenvironment.nxdl.xml index 1b494e345e..1dd95974a8 100644 --- a/base_classes/NXenvironment.nxdl.xml +++ b/base_classes/NXenvironment.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - Parameters for controlling external conditions + + + Parameters for controlling external conditions + - Apparatus identification code/model number; e.g. OC100 011 + + Apparatus identification code/model number; e.g. OC100 011 + - Alternative short name, perhaps for dashboard display like a present Seblock name + + Alternative short name, perhaps for dashboard display like a present Seblock + name + - Type of apparatus. This could be the SE codes in scheduling database; e.g. OC/100 + + Type of apparatus. This could be the SE codes in scheduling database; e.g. + OC/100 + - Description of the apparatus; e.g. 100mm bore orange cryostat with Roots pump + + Description of the apparatus; e.g. 100mm bore orange cryostat with Roots pump + - Program controlling the apparatus; e.g. LabView VI name + + Program controlling the apparatus; e.g. LabView VI name + @@ -50,25 +60,37 @@ - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. - Additional information, LabView logs, digital photographs, etc + + Additional information, LabView logs, digital photographs, etc + + + + + Any actuator used to control the environment. This can be linked to an actuator + defined in an NXinstrument instance. + + + + + Any sensor used to monitor the environment. This can be linked to a sensor + defined in an NXinstrument instance. + - - diff --git a/base_classes/NXinstrument.nxdl.xml b/base_classes/NXinstrument.nxdl.xml index e385f3671d..2e6c8b5f73 100644 --- a/base_classes/NXinstrument.nxdl.xml +++ b/base_classes/NXinstrument.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - - Collection of the components of the instrument or beamline. - - Template of instrument descriptions comprising various beamline components. - Each component will also be a NeXus group defined by its distance from the - sample. Negative distances represent beamline components that are before the - sample while positive distances represent components that are after the sample. - This device allows the unique identification of beamline components in a way - that is valid for both reactor and pulsed instrumentation. - - - Name of instrument - - short name for instrument, perhaps the acronym - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + Collection of the components of the instrument or beamline. + + Template of instrument descriptions comprising various beamline components. + Each component will also be a NeXus group defined by its distance from the + sample. Negative distances represent beamline components that are before the + sample while positive distances represent components that are after the sample. + This device allows the unique identification of beamline components in a way + that is valid for both reactor and pulsed instrumentation. + + + + Name of instrument + + + + short name for instrument, perhaps the acronym + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. diff --git a/base_classes/NXprocess.nxdl.xml b/base_classes/NXprocess.nxdl.xml index d6a3346af1..ac5a8b81de 100644 --- a/base_classes/NXprocess.nxdl.xml +++ b/base_classes/NXprocess.nxdl.xml @@ -1,9 +1,9 @@ - + - - Document an event of data processing, reconstruction, or analysis for this data. + + + Document an event of data processing, reconstruction, or analysis for this data. + - Name of the program used + + Name of the program used + - Sequence index of processing, - for determining the order of multiple **NXprocess** steps. - Starts with 1. + Sequence index of processing, + for determining the order of multiple **NXprocess** steps. + Starts with 1. - Version of the program used + + Version of the program used + - Date and time of processing. + + Date and time of processing. + + + + Describes the operations of image registration + + + + + Describes the operations of image distortion correction + + + + + Describes the operations of calibration procedures, e.g. axis calibrations. + + - The note will contain information about how the data was processed - or anything about the data provenance. - The contents of the note can be anything that the processing code - can understand, or simple text. - - The name will be numbered to allow for ordering of steps. + The note will contain information about how the data was processed + or anything about the data provenance. + The contents of the note can be anything that the processing code + can understand, or simple text. + + The name will be numbered to allow for ordering of steps. - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - diff --git a/base_classes/NXroot.nxdl.xml b/base_classes/NXroot.nxdl.xml index 54c432c794..68c179c8c4 100644 --- a/base_classes/NXroot.nxdl.xml +++ b/base_classes/NXroot.nxdl.xml @@ -1,9 +1,9 @@ - - + + - - Definition of the root NeXus group. + + + Definition of the root NeXus group. + - The root of any NeXus data file is an ``NXroot`` class - (no other choice is allowed for a valid NeXus data file). - This attribute cements that definition. + The root of any NeXus data file is an ``NXroot`` class + (no other choice is allowed for a valid NeXus data file). + This attribute cements that definition. - + - Date and time file was originally created + + Date and time file was originally created + - File name of original NeXus file + + File name of original NeXus file + - Date and time of last file change at close + + Date and time of last file change at close + + + + + A repository containing the application definitions + used for creating this file. + If the NeXus_version attribute contains a commit distance and hash + this should refer to this repository. + - Version of NeXus API used in writing the file. - - Only used when the NAPI has written the file. - Note that this is different from the version of the - base class or application definition version number. + Version of NeXus definitions used in writing the file. + This may either be a date based version tag of the form `vYYYY.MM` + or a version tag with a commit distance and source control (e.g., git) hash of + the form `vYYYY.MM.post1.dev<commit-distance>.g<git-hash>`. + It may contain an additional `.dYYYYMMDD` timestamp appendix + for dirty repositories. + If the version contains a commit distance and hash the + NeXus_repository attribute should be written with the + repository url containing this version. + + Only used when the NAPI or pynxtools has written the file. + Note that this is different from the version of the + base class or application definition version number. + + + + + A list of concepts in an application definition this file describes. + This is for partially filling an application definition. + If this attribute is not present the application definition is assumed + to be valid, if not only the specified concepts/paths are assumed to be valid. - Version of HDF (version 4) library used in writing the file + + Version of HDF (version 4) library used in writing the file + - Version of HDF5 library used in writing the file. - - Note this attribute is spelled with uppercase "V", - different than other version attributes. + Version of HDF5 library used in writing the file. + + Note this attribute is spelled with uppercase "V", + different than other version attributes. - Version of XML support library used in writing the XML file + + Version of XML support library used in writing the XML file + - Version of h5py Python package used in writing the file + + Version of h5py Python package used in writing the file + - facility or program where file originated + + facility or program where file originated + - Version of facility or program used in writing the file + + Version of facility or program used in writing the file + - - entries + + + entries + - .. index:: find the default plottable data - .. index:: plotting - .. index:: default attribute value - - Declares which :ref:`NXentry` group contains - the data to be shown by default. - It is used to resolve ambiguity when - more than one :ref:`NXentry` group exists. - The value :ref:`names <validItemName>` the default :ref:`NXentry` group. The - value must be the name of a child of the current group. The child must be a - NeXus group or a link to a NeXus group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXentry` group contains + the data to be shown by default. + It is used to resolve ambiguity when + more than one :ref:`NXentry` group exists. + The value :ref:`names <validItemName>` the default :ref:`NXentry` group. The + value must be the name of a child of the current group. The child must be a + NeXus group or a link to a NeXus group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - diff --git a/base_classes/NXsample.nxdl.xml b/base_classes/NXsample.nxdl.xml old mode 100755 new mode 100644 index 43bb316334..65bd90b83d --- a/base_classes/NXsample.nxdl.xml +++ b/base_classes/NXsample.nxdl.xml @@ -1,9 +1,9 @@ - + - - - - symbolic array lengths to be coordinated between various fields - number of compositions - number of temperatures - number of values in applied electric field - number of values in applied magnetic field - number of values in applied pressure field - number of values in applied stress field - - - - Any information on 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. - - - Descriptive name of sample - - - - 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. - - - - Sample temperature. This could be a scanned variable - - - - - - Applied electric field - - - + + + + symbolic array lengths to be coordinated between various fields + + + + number of compositions + + + + + number of temperatures + + + + + number of values in applied electric field + + + + + number of values in applied magnetic field + + + + + number of values in applied pressure field + + + + + number of values in applied stress field + + + + + Any information on 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. + + + + Descriptive name of sample + + + + + Identification number or signatures of the sample used. + + + + + 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. + + + + + Sample temperature. This could be a scanned variable + + + + + + + + + Applied electric field + + + + + - - - - - + + + + + - - - Applied magnetic field - - - + + + + Applied magnetic field + + + + + - - - - - + + + + + - - - Applied external stress field - - - + + + + Applied external stress field + + + + + - - - - - + + + + + - - - Applied pressure - - - - - - Sample changer position - - - Crystallography unit cell parameters a, b, and c - - - - - - Crystallography unit cell parameters alpha, beta, and gamma - - - - - - Unit cell parameters (lengths and angles) - - - - - - - Volume of the unit cell - - - - - - - This will follow the Busing-Levy convention: - W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 - - - - - - - - Orientation matrix of single crystal sample using Busing-Levy convention: - W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 - - - - - - - - - - UB matrix of single crystal sample using Busing-Levy convention: - W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is - the multiplication of the orientation_matrix, given above, - with the :math:`B` matrix which - can be derived from the lattice constants. - - - - - - - - - Mass of sample - - - - - - Density of sample - - - - - - Relative Molecular Mass of sample - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - - - - - - - - - Description of the sample - - - - Date of preparation of the sample - - - The position and orientation of the center of mass of the sample - - - Details of beam incident on sample - used to calculate sample/beam interaction point - - - - One group per sample component - This is the perferred way of recording per component information over the n_comp arrays - - - - Details of the component of the sample and/or can - - - - - - Type of component - - - - - - - - - - - - Concentration of each component - - - - - - Volume fraction of each component - - - - - - Scattering length density of each component - - - - - - - In case it is all we know and we want to record/document it - - - - - - - - - - - - - Crystallographic space group - - - - - - Crystallographic point group, deprecated if space_group present - - + + + + Applied pressure + + + + + + + + + Sample changer position + + + + + Crystallography unit cell parameters a, b, and c + + + + + + + + Crystallography unit cell parameters alpha, beta, and gamma + + + + + + + + Unit cell parameters (lengths and angles) + + + + + + + + + Volume of the unit cell + + + + + + + + This will follow the Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + + + + + + + + Orientation matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + + + + + - - - - Path length through sample/can for simple case when - it does not vary with scattering direction - - - - - Thickness of a beam entry/exit window on the can (mm) - - assumed same for entry and exit - - - - sample thickness - - - As a function of Wavelength - - - temperature_log.value is a link to e.g. temperature_env.sensor1.value_log.value - - - Additional sample temperature environment information - - - magnetic_field.value is a link to e.g. magnetic_field_env.sensor1.value - - - magnetic_field_log.value is a link to e.g. magnetic_field_env.sensor1.value_log.value - - - Additional sample magnetic environment information - - - value sent to user's sample setup - - - logged value (or logic state) read from user's setup - - - 20 character fixed length sample description for legends - - - - - 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. - Note, it is recommended to use NXtransformations instead. - - - - - Translation of the sample along the X-direction of the laboratory coordinate system - Note, it is recommended to use NXtransformations instead. - - - - - Translation of the sample along the Z-direction of the laboratory coordinate system. - Note, it is recommended to use NXtransformations instead. - - - - Any positioner (motor, PZT, ...) used to locate the sample - - - - This group describes the shape of the sample - - + + + + UB matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is + the multiplication of the orientation_matrix, given above, + with the :math:`B` matrix which + can be derived from the lattice constants. + + + + + + + + + + Mass of sample + + + + + + + + Density of sample + + + + + + + + Relative Molecular Mass of sample + + + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + + + + + + Description of the sample + + + + + Date of preparation of the sample + + + + + The position and orientation of the center of mass of the sample + + + + + Details of beam incident on sample - used to calculate sample/beam interaction + point + + + + + One group per sample component + This is the perferred way of recording per component information over the n_comp arrays + + + + + Details of the component of the sample and/or can + + + + + + + + Type of component + + + + + + + + + + + + + + Concentration of each component + + + + + + + + Volume fraction of each component + + + + + + + + Scattering length density of each component + + + + + + + + In case it is all we know and we want to record/document it + + + + + + + + + + + + + + Crystallographic space group + + + + + + + + Crystallographic point group, deprecated if space_group present + + + + + + + + Path length through sample/can for simple case when + it does not vary with scattering direction + + + + + Thickness of a beam entry/exit window on the can (mm) + - assumed same for entry and exit + + + + + sample thickness + + + + + As a function of Wavelength + + + + + temperature_log.value is a link to e.g. temperature_env.sensor1.value_log.value + + + + + Additional sample temperature environment information + + + + + magnetic_field.value is a link to e.g. magnetic_field_env.sensor1.value + + + + + magnetic_field_log.value is a link to e.g. + magnetic_field_env.sensor1.value_log.value + + + + + Additional sample magnetic environment information + + + + + value sent to user's sample setup + + + + + logged value (or logic state) read from user's setup + + + + + 20 character fixed length sample description for legends + + + + + + 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. + Note, it is recommended to use NXtransformations instead. + + + + + Translation of the sample along the X-direction of the laboratory coordinate system + Note, it is recommended to use NXtransformations instead. + + + + + Translation of the sample along the Z-direction of the laboratory coordinate system. + Note, it is recommended to use NXtransformations instead. + + + + + Any positioner (motor, PZT, ...) used to locate the sample + + + + + + This group describes the shape of the sample + + + + + Physical form of the sample material. + Examples include single crystal, foil, pellet, powder, thin film, disc, foam, gas, liquid, amorphous. + + + + + If the sample is a single crystal, add description of single crystal and unit + cell. + + + + + Set of sample components and their configuration. + There can only be one NXsample_component_set in one component. + + + + + + If the sample is made from a pure substance and cannot be further divided using + NXsample_component. + + + + + + Details about the sample vendor (company or research group) + + + + + + Any environmental or external stimuli/measurements. + These can include, among others: + applied pressure, surrounding gas phase and gas pressure, + external electric/magnetic/mechanical fields, temperature, ... + + + + + A set of physical processes that occurred to the sample prior/during experiment. + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - + - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. - diff --git a/base_classes/NXsample_component.nxdl.xml b/base_classes/NXsample_component.nxdl.xml index 624c09557d..b64bc25594 100644 --- a/base_classes/NXsample_component.nxdl.xml +++ b/base_classes/NXsample_component.nxdl.xml @@ -1,9 +1,9 @@ - + - - - - symbolic array lengths to be coordinated between various fields - number of temperatures - number of values in applied electric field - number of values in applied magnetic field - number of values in applied pressure field - number of values in applied stress field - - - - One group like this per component can be recorded For a sample consisting of multiple components. - - - Descriptive name of sample component - - - - 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. - - - - Crystallography unit cell parameters a, b, and c - - - - - - Crystallography unit cell parameters alpha, beta, and gamma - - - - - - Volume of the unit cell - - - This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967) - - - - - - - Orientation matrix of single crystal sample component. - This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967) - - - - - - - - Mass of sample component - - - Density of sample component - - - Relative Molecular Mass of sample component - - - - Description of the sample component - - - - Volume fraction of component - - - Scattering length density of component - - - - In case it is all we know and we want to record/document it - - - - - - - - - - - - - Crystallographic space group - - - Crystallographic point group, deprecated if space_group present - - - As a function of Wavelength - + + + + symbolic array lengths to be coordinated between various fields + + + + number of temperatures + + + + + number of values in applied electric field + + + + + number of values in applied magnetic field + + + + + number of values in applied pressure field + + + + + number of values in applied stress field + + + + + One group like this per component can be recorded For a sample consisting of + multiple components. + + + + Descriptive name of sample component + + + + + Identification number or signatures of the sample component used. + + + + + 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. + + + + + Crystallography unit cell parameters a, b, and c + + + + + + + + Crystallography unit cell parameters alpha, beta, and gamma + + + + + + + + Volume of the unit cell + + + + + This will follow the Busing and Levy convention from Acta.Crysta v22, p457 + (1967) + + + + + + + + Orientation matrix of single crystal sample component. + This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967) + + + + + + + + + Mass of sample component + + + + + Density of sample component + + + + + Relative Molecular Mass of sample component + + + + + Description of the sample component + + + + + Volume fraction of component + + + + + Scattering length density of component + + + + + In case it is all we know and we want to record/document it + + + + + + + + + + + + + + Crystallographic space group + + + + + Crystallographic point group, deprecated if space_group present + + + + + As a function of Wavelength + + + + + If the component is a single crystal, add description of single crystal and unit + cell. + + + + + Set of sub-components and their configuration. + There can only be one NXsample_component_set in one component. + + + + + + If the component is made from a pure substance and cannot be further divided + using NXsample_component. + + + + + + Details about the sample component vendor (company or research group) + + + + + A set of physical processes that occurred to the sample component prior/during + experiment. + + + + + Any NXsample_component depends on the instance of NXsample_component_set, at the same level of + description granularity where the component is located. + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. diff --git a/base_classes/NXsensor.nxdl.xml b/base_classes/NXsensor.nxdl.xml index cdfc11ab04..3e01482037 100644 --- a/base_classes/NXsensor.nxdl.xml +++ b/base_classes/NXsensor.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - - A sensor used to monitor an external condition - - The condition itself is described in :ref:`NXenvironment`. - - - Sensor identification code/model number - - - Name for the sensor - - - Short name of sensor used e.g. on monitor display program - - - where sensor is attached to ("sample" | "can") - - - - Defines the axes for logged vector quantities if they are not the global instrument axes. - - - - name for measured signal - - - - - - - - - - - - - - - - - - - The type of hardware used for the measurement. - Examples (suggestions but not restrictions): - - :Temperature: - J | K | T | E | R | S | Pt100 | Rh/Fe - :pH: - Hg/Hg2Cl2 | Ag/AgCl | ISFET - :Ion selective electrode: - specify species; e.g. Ca2+ - :Magnetic field: - Hall - :Surface pressure: - wilhelmy plate - - - - - Is data collection controlled or synchronised to this quantity: - 1=no, 0=to "value", 1=to "value_deriv1", etc. - - - - - Upper control bound of sensor reading if using run_control - - - - - Lower control bound of sensor reading if using run_control - - - - - nominal setpoint or average value - - need [n] as may be a vector - - - - - - - - Nominal/average first derivative of value - e.g. strain rate - - same dimensions as "value" (may be a vector) - - - - - - - - Nominal/average second derivative of value - - same dimensions as "value" (may be a vector) - - - - - - - Time history of sensor readings - - - Time history of first derivative of sensor readings - - - Time history of second derivative of sensor readings - - - - - - - - - - - - - For complex external fields not satisfied by External_field_brief - - - - This group describes the shape of the sensor when necessary. - - + + + A sensor used to monitor an external condition + + The condition itself is described in :ref:`NXenvironment`. + + + + Sensor identification code/model number + + + + + Name for the sensor + + + + + Short name of sensor used e.g. on monitor display program + + + + + where sensor is attached to ("sample" | "can") + + + + + Defines the axes for logged vector quantities if they are not the global + instrument axes. + + + + + name for measured signal + + + + + + + + + + + + + + + + + + + + + The type of hardware used for the measurement. + Examples (suggestions but not restrictions): + + :Temperature: + J | K | T | E | R | S | Pt100 | Rh/Fe + :pH: + Hg/Hg2Cl2 | Ag/AgCl | ISFET + :Ion selective electrode: + specify species; e.g. Ca2+ + :Magnetic field: + Hall + :Surface pressure: + wilhelmy plate + + + + + Is data collection controlled or synchronised to this quantity: + 1=no, 0=to "value", 1=to "value_deriv1", etc. + + + + + Upper control bound of sensor reading if using run_control + + + + + Lower control bound of sensor reading if using run_control + + + + + nominal setpoint or average value + - need [n] as may be a vector + + + + + + + + Nominal/average first derivative of value + e.g. strain rate + - same dimensions as "value" (may be a vector) + + + + + + + + Nominal/average second derivative of value + - same dimensions as "value" (may be a vector) + + + + + + + + Time history of sensor readings + + + + + Time history of first derivative of sensor readings + + + + + Time history of second derivative of sensor readings + + + + + + + + + + + + + + + For complex external fields not satisfied by External_field_brief + + + + + This group describes the shape of the sensor when necessary. + + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - .. todo:: - Add a definition for the reference point of a sensor. - + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a sensor. - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. - diff --git a/base_classes/NXsource.nxdl.xml b/base_classes/NXsource.nxdl.xml index 85900d3f03..1bf03d55d4 100644 --- a/base_classes/NXsource.nxdl.xml +++ b/base_classes/NXsource.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - The neutron or x-ray storage ring/facility. - - - Effective distance from sample - Distance as seen by radiation from sample. This number should be negative - to signify that it is upstream of the sample. - - - - Name of source - - short name for source, perhaps the acronym - - - - type of radiation source (pick one from the enumerated list and spell exactly) - - - - - - - - - - - - - - - - - - type of radiation probe (pick one from the enumerated list and spell exactly) - - - - - - - - - - - - - Source power - - - Source emittance (nm-rad) in X (horizontal) direction. - - - Source emittance (nm-rad) in Y (horizontal) direction. - - - particle beam size in x - - - particle beam size in y - - - Source intensity/area (example: s-1 cm-2) - - - - Source energy. - For storage rings, this would be the particle beam energy. - For X-ray tubes, this would be the excitation voltage. - - - - Accelerator, X-ray tube, or storage ring current - - - Accelerator voltage - - - Frequency of pulsed source - - - Period of pulsed source - - - Pulsed source target material - - - - - - - - - - - - - any source/facility related messages/events that - occurred during the experiment - - - - - For storage rings, description of the bunch pattern. - This is useful to describe irregular bunch patterns. - - name of the bunch pattern - - - For storage rings, the number of bunches in use. - - - For storage rings, temporal length of the bunch - - - For storage rings, time between bunches - - - temporal width of source pulse - - - source pulse shape - - - source operating mode - - for storage rings - for storage rings - - - - - Is the synchrotron operating in top_up mode? - - - For storage rings, the current at the end of the most recent injection. - date and time of the most recent injection. - - - - "Engineering" location of source. - - - - - This group describes the shape of the beam line component + + + Radiation source emitting a beam. + + Examples include particle sources (electrons, neutrons, protons) or sources for electromagnetic radiation (photons). + This base class can also be used to describe neutron or x-ray storage ring/facilities. + + + + Effective distance from sample + Distance as seen by radiation from sample. This number should be negative + to signify that it is upstream of the sample. + + + + + Name of source + + + + short name for source, perhaps the acronym - - - The wavelength or energy distribution of the source - + + + + + type of radiation source (pick one from the enumerated list and spell exactly) + + + + + + + + + + + + + + + + + + + + type of radiation probe (pick one from the enumerated list and spell exactly) + + + + + + + + + + + + + + + + Source power + + + + + Source emittance (nm-rad) in X (horizontal) direction. + + + + + Source emittance (nm-rad) in Y (horizontal) direction. + + + + + particle beam size in x + + + + + particle beam size in y + + + + + Source intensity/area (example: s-1 cm-2) + + + + + Source energy. + For storage rings, this would be the particle beam energy. + For X-ray tubes, this would be the excitation voltage. + + + + + Accelerator, X-ray tube, or storage ring current + + + + + Accelerator voltage + + + + + Frequency of pulsed source + + + + + Period of pulsed source + + + + + Pulsed source target material + + + + + + + + + + + + + + any source/facility related messages/events that + occurred during the experiment + + + + + For storage rings, description of the bunch pattern. + This is useful to describe irregular bunch patterns. + + + + name of the bunch pattern + + + + + + For storage rings, the number of bunches in use. + + + + + For storage rings, temporal length of the bunch + + + + + For storage rings, time between bunches + + + + + temporal width of source pulse + + + + + + source pulse shape + + + + + + source operating mode + + + + + for storage rings + + + + + for storage rings + + + + + + + + + Is the synchrotron operating in top_up mode? + + + + + For storage rings, the current at the end of the most recent injection. + + + + date and time of the most recent injection. + + + + + + The center photon energy of the source, before it is + monochromatized or converted + + + + + The center wavelength of the source, before it is + monochromatized or converted + + + + + For pulsed sources, the energy of a single pulse + + + + + For pulsed sources, the pulse energy divided + by the pulse duration + + + + + Some facilities tag each bunch. + First bunch of the measurement + + + + + Last bunch of the measurement + + + + + "Engineering" location of source. + + + + + + This group describes the shape of the beam line component + + + + + The wavelength or energy distribution of the source + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the - z axis. - - .. image:: source/source.png - :width: 40% - + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the + z axis. + + .. image:: source/source.png + :width: 40% - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 9be3577f26..f0b0580d8c 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -55,23 +55,42 @@ * ``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. + a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` + 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. + **Transformation chain** + + The entry point of a chain of transformations is a field called ``depends_on`` + will be outside of this class and points 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 + which in turn depends on :math:`T_3`, the final *active* transformation + matrix :math:`T_f` is + + .. math:: T_f = T_3 . T_2 . T_1 + + For example when positioning a flat detector, its pixel positions in the laboratory + reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) + can be calculated by + + .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} - .. math:: T_f = T_3 T_2 T_1 + Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first + to the pixel coordinates. - 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`. + When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that + the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. + So the activate coordinate transformation :math:`A` needs to be applied to a coordinate + before applying :math:`B`. In other words :math:`X' = B . A . X`. + + **Transformation matrix** + + In explicit terms, the transformations are a subset of affine transformations expressed as + 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. For rotation and translation, @@ -85,8 +104,8 @@ 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. - NOTE - + **Usage** + One possible use of ``NXtransformations`` is to define the motors and transformations for a diffractometer (goniometer). Such use is mentioned in the ``NXinstrument`` base class. Use one ``NXtransformations`` group @@ -94,8 +113,7 @@ Collecting the motors of a sample table or xyz-stage in an NXtransformations group is equally possible. - - Following the section on the general dscription of axis in NXtransformations is a section which + Following the section on the general description of axis in NXtransformations is a section which documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever there is a need for positioning a beam line component please use the existing names. Use as many fields as needed in order to position the component. Feel free to add more axis if required. In the description @@ -108,6 +126,143 @@ * depends_on as needed. + + **Example 1: goniometer** + + Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. + + The sample is oriented as follows + + .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . + T(\vec{v}_z, \text{sam}_z) . + T(\vec{v}_y, \text{sam}_y) . + T(\vec{v}_x, \text{sam}_x) . + R(\vec{v}_\chi, \chi) . + R(\vec{v}_\varphi, \varphi) . X_s + + where + + * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` + * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` + * :math:`X_s` a coordinate in the sample reference frame. + + .. code-block:: + + entry:NXentry + sample:NXsample + depends_on=transformations/phi + transformations:NXtransformations + phi=0 + @depends_on=chi + @transformation_type=rotation + @vector=[-1 -0.0037 -0.002] + @units=degrees + chi=0 + @depends_on=sam_x + @transformation_type=rotation + @vector=[0.0046 0.0372 0.9993] + @units=degrees + sam_x=0 + @depends_on=sam_y + @transformation_type=translation + @vector=[1 0 0] + @units=mm + sam_y=0 + @depends_on=sam_z + @transformation_type=translation + @vector=[0 1 0] + @units=mm + sam_z=0 + @depends_on=omega + @transformation_type=translation + @vector=[0 0 1] + @units=mm + omega=174 + @depends_on=. + @transformation_type=rotation + @vector=[-1 0 0] + @units=degrees + + **Example 2: different coordinate system** + + Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. + Three point detectors are positioned in this reference: + + * *transmission*: + * point detector in the beam + * 20 cm downstream from the sample (the origin of the reference frame) + * *vertical*: + * point detector 10 cm downstream from the sample + * making an angle of 5 degrees with the beam w.r.t. the sample + * positioned in the XZ-plane above the XY-plane + * *horizontal*: + * point detector 11 cm downstream from the sample + * making an angle of 6 degrees with the beam w.r.t. the sample + * positioned in the XY-plane above the XZ-plane + + The coordinates of the point detectors in the laboratory reference frame are + + * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` + * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` + * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` + + where + + * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes + * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes + * :math:`X_d` is a coordinate in the detector reference frame. + + Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. + + .. code-block:: + + entry:NXentry + instrument:NXinstrument + vertical:NXdetector + depends_on=position/distance + position:NXtransformations + distance=10 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=5 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=0 # stay in the vertical plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + horizontal:NXdetector + depends_on=position/distance + position:NXtransformations + distance=11 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=6 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=90 # rotate to the horizontal plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + transmission:NXdetector + depends_on=position/distance + position:NXtransformations + distance=20 # move downstream from the sample + @depends_on=/entry/coordinate_system/beam + @units=cm + @vector=[1 0 0] + coordinate_system:NXtransformations + beam=NaN # value is never used + @depends_on=gravity + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up + @@ -170,7 +325,7 @@ Points to the path to a field defining the axis on which this - depends or the string ".". + depends or the string "." when at the end of the chain. @@ -217,4 +372,4 @@ for a summary of the discussion. - + \ No newline at end of file diff --git a/base_classes/nyaml/NXaperture.yaml b/base_classes/nyaml/NXaperture.yaml new file mode 100644 index 0000000000..7b123ba21b --- /dev/null +++ b/base_classes/nyaml/NXaperture.yaml @@ -0,0 +1,214 @@ +category: base +doc: | + A beamline aperture. This group is deprecated, use NXslit instead. +type: group +NXaperture(NXobject): + + # TODO compare with "screens" in SHADOW + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the + surface of the aperture pointing towards the source. + + In complex (asymmetric) geometries an NXoff_geometry group can be used to provide an unambiguous reference. + + .. image:: aperture/aperture.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + (NXpositioner): + doc: | + Stores the raw positions of aperture motors. + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the aperture and :ref:`NXoff_geometry` to describe its shape + doc: | + location and shape of aperture + + .. TODO: documentation needs improvement, contributions welcome + + * description of terms is poor and leaves much to interpretation + * Describe what is meant by translation _here_ and ... + * Similar throughout base classes + * Some base classes do this much better + * Such as where is the gap written? + BLADE_GEOMETRY(NXgeometry): + deprecated: | + Use :ref:`NXoff_geometry` instead to describe the shape of the aperture + doc: | + location and shape of each blade + material: + + # TODO Uniformity problem, "type" is used elsewhere for same context + doc: | + Absorbing material of the aperture + description: + doc: | + Description of aperture + shape: + doc: | + Shape of the aperture. + enumeration: [straight slit, curved slit, pinhole, circle, square, hexagon, octagon, bladed, open, grid] + size(NX_NUMBER): + unit: NX_LENGTH + doc: | + The relevant dimension for the aperture, i.e. slit width, pinhole and iris + diameter + (NXnote): + doc: | + describe any additional information in a note* + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 958de5809c55ea9bb7eda83a612cf4e2770cbce001cc16a5944e072279415895 +# +# +# +# +# +# A beamline aperture. This group is deprecated, use NXslit instead. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the +# surface of the aperture pointing towards the source. +# +# In complex (asymmetric) geometries an NXoff_geometry group can be used to provide an unambiguous reference. +# +# .. image:: aperture/aperture.png +# :width: 40% +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# Stores the raw positions of aperture motors. +# +# +# +# +# location and shape of aperture +# +# .. TODO: documentation needs improvement, contributions welcome +# +# * description of terms is poor and leaves much to interpretation +# * Describe what is meant by translation _here_ and ... +# * Similar throughout base classes +# * Some base classes do this much better +# * Such as where is the gap written? +# +# +# +# +# location and shape of each blade +# +# +# +# +# +# Absorbing material of the aperture +# +# +# +# +# Description of aperture +# +# +# +# +# Shape of the aperture. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The relevant dimension for the aperture, i.e. slit width, pinhole and iris +# diameter +# +# +# +# +# describe any additional information in a note* +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXattenuator.yaml b/base_classes/nyaml/NXattenuator.yaml new file mode 100644 index 0000000000..21fc404d16 --- /dev/null +++ b/base_classes/nyaml/NXattenuator.yaml @@ -0,0 +1,206 @@ +category: base +doc: | + A device that reduces the intensity of a beam by attenuation. + + If uncertain whether to use :ref:`NXfilter` (band-pass filter) + or :ref:`NXattenuator` (reduces beam intensity), then choose + :ref:`NXattenuator`. +type: group +NXattenuator(NXobject): + + # TODO compare with SHADOW definition "screen" + # TODO SHADOW: https://github.com/oasys-kit/shadow3 + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance from sample. Note, it is recommended to use NXtransformations instead. + type: + doc: | + Type or composition of attenuator, e.g. polythene + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of attenuator along beam direction + scattering_cross_section(NX_FLOAT): + unit: NX_CROSS_SECTION + doc: | + Scattering cross section (coherent+incoherent) + absorption_cross_section(NX_FLOAT): + unit: NX_CROSS_SECTION + doc: | + Absorption cross section + attenuator_transmission(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + The nominal amount of the beam that gets through + (transmitted intensity)/(incident intensity) + status: + doc: | + In or out or moving of the beam + \@time: + type: NX_DATE_TIME + doc: | + time stamp for this observation + enumeration: [in, out, moving] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the attenuator is its center in the x and y axis. The reference point on the z axis is the + surface of the attenuator pointing towards the source. + + In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference. + + .. image:: attenuator/attenuator.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + shape(NXoff_geometry): + doc: | + Shape of this component. Particulary useful to define the origin for position and orientation in non-standard cases. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5cb6333d87df9b8f1b009346d2bf55434c7d4ef72f1ce1b62db27caf873c4f7f +# +# +# +# +# +# +# A device that reduces the intensity of a beam by attenuation. +# +# If uncertain whether to use :ref:`NXfilter` (band-pass filter) +# or :ref:`NXattenuator` (reduces beam intensity), then choose +# :ref:`NXattenuator`. +# +# +# +# +# Distance from sample. Note, it is recommended to use NXtransformations instead. +# +# +# Type or composition of attenuator, e.g. polythene +# +# +# Thickness of attenuator along beam direction +# +# +# Scattering cross section (coherent+incoherent) +# +# +# Absorption cross section +# +# +# +# The nominal amount of the beam that gets through +# (transmitted intensity)/(incident intensity) +# +# +# +# In or out or moving of the beam +# +# time stamp for this observation +# +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the attenuator is its center in the x and y axis. The reference point on the z axis is the +# surface of the attenuator pointing towards the source. +# +# In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference. +# +# .. image:: attenuator/attenuator.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# Shape of this component. Particulary useful to define the origin for position and orientation in non-standard cases. +# +# +# diff --git a/base_classes/nyaml/NXbeam.yaml b/base_classes/nyaml/NXbeam.yaml new file mode 100644 index 0000000000..bc5e640d12 --- /dev/null +++ b/base_classes/nyaml/NXbeam.yaml @@ -0,0 +1,889 @@ +category: base +doc: | + Properties of the neutron or X-ray beam at a given location. + + This group is intended to be referenced + by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is + especially valuable in storing the results of instrument simulations in which it is useful + to specify the beam profile, time distribution etc. at each beamline component. Otherwise, + its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron + scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is + considered as a beamline component and this group may be defined as a subgroup directly inside + :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an + :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). + + Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. + To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred + by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. +symbols: + doc: | + These symbols coordinate datasets with the same shape. + nP: | + Number of scan points. + m: | + Number of channels in the incident beam spectrum, if known + c: | + Number of moments representing beam divergence (x, y, xy, etc.) +type: group +NXbeam(NXobject): + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance from sample. Note, it is recommended to use NXtransformations instead. + incident_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy carried by each particle of the beam on entering the beamline component. + + In the case of a monochromatic beam this is the scalar energy. + Several other use cases are permitted, depending on the + presence of other incident_energy_X fields. + + * In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights. + * In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot. + Here, incident_energy_weights and incident_energy_spread are not set. + * In the case of a polychromatic beam that varies shot-to-shot, + this is an array of length m with the relative weights in incident_energy_weights as a 2D array. + * In the case of a polychromatic beam that varies shot-to-shot and where the channels also vary, + this is a 2D array of dimensions nP by m (slow to fast) with the relative weights in incident_energy_weights as a 2D array. + + Note, variants are a good way to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value energy value is available along with the original spectrum from which it was calibrated. + dimensions: + rank: 1 + dim: [[1, m]] + incident_energy_spread(NX_NUMBER): + unit: NX_ENERGY + doc: | + The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in + the energy spread, this is a 2D array of dimension nP by m + (slow to fast) of the spreads of the corresponding + wavelength in incident_wavelength. + incident_energy_weights(NX_NUMBER): + unit: NX_ENERGY + doc: | + In the case of a polychromatic beam this is an array of length m of the relative + weights of the corresponding energies in incident_energy. In the case of a + polychromatic beam that varies shot-to-shot, this is a 2D array of dimensions np + by m (slow to fast) of the relative weights of the corresponding energies in + incident_energy. + final_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy carried by each particle of the beam on leaving the beamline component + dimensions: + rank: 1 + dim: [[1, m]] + energy_transfer(NX_FLOAT): + unit: NX_ENERGY + doc: | + Change in particle energy caused by the beamline component + dimensions: + rank: 1 + dim: [[1, m]] + incident_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + In the case of a monochromatic beam this is the scalar + wavelength. + + Several other use cases are permitted, depending on the + presence or absence of other incident_wavelength_X + fields. + + In the case of a polychromatic beam this is an array of + length **m** of wavelengths, with the relative weights + in ``incident_wavelength_weights``. + + In the case of a monochromatic beam that varies shot- + to-shot, this is an array of wavelengths, one for each + recorded shot. Here, ``incident_wavelength_weights`` and + incident_wavelength_spread are not set. + + In the case of a polychromatic beam that varies shot-to- + shot, this is an array of length **m** with the relative + weights in ``incident_wavelength_weights`` as a 2D array. + + In the case of a polychromatic beam that varies shot-to- + shot and where the channels also vary, this is a 2D array + of dimensions **nP** by **m** (slow to fast) with the + relative weights in ``incident_wavelength_weights`` as a 2D + array. + + Note, :ref:`variants ` are a good way + to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value wavelength value is + available along with the original spectrum from which it + was calibrated. + Wavelength on entering beamline component + incident_wavelength_weights(NX_FLOAT): + doc: | + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``incident_wavelength``. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **nP** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in ``incident_wavelength``. + incident_wavelength_spread(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + The wavelength spread FWHM for the corresponding + wavelength(s) in incident_wavelength. + + In the case of shot-to-shot variation in the wavelength + spread, this is a 2D array of dimension **nP** by + **m** (slow to fast) of the spreads of the + corresponding wavelengths in incident_wavelength. + dimensions: + rank: 1 + dim: [[1, nP]] + incident_beam_divergence(NX_FLOAT): + unit: NX_ANGLE + doc: | + Beam crossfire in degrees parallel to the laboratory X axis + + The dimension **c** is a series of moments of that represent + the standard uncertainty (e.s.d.) of the directions of + of the beam. The first and second moments are in the XZ and YZ + planes around the mean source beam direction, respectively. + + Further moments in **c** characterize co-variance terms, so + the next moment is the product of the first two, and so on. + dimensions: + rank: 2 + dim: [[1, nP], [2, c]] + extent(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of the beam entering this component. Note this represents + a rectangular beam aperture, and values represent FWHM + dimensions: + rank: 2 + dim: [[1, nP], [2, 2]] + final_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Wavelength on leaving beamline component + dimensions: + rank: 1 + dim: [[1, m]] + incident_polarization(NX_NUMBER): + unit: NX_ANY + doc: | + Incident polarization as a Stokes vector + on entering beamline component + dimensions: + rank: 2 + dim: [[1, nP], [2, 2]] + \@units: + type: NX_CHAR + doc: | + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + final_polarization(NX_NUMBER): + unit: NX_ANY + doc: | + Polarization as Stokes vector on leaving beamline component + dimensions: + rank: 2 + dim: [[1, nP], [2, 2]] + \@units: + type: NX_CHAR + doc: | + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + incident_polarization_stokes(NX_NUMBER): + unit: NX_ANY + doc: | + Polarization vector on entering beamline component using Stokes notation + + The Stokes parameters are four components labelled I,Q,U,V or S_0,S_1,S_2,S_3. + These are defined with the standard Nexus coordinate frame unless it is + overridden by an NXtransformations field pointed to by a depends_on attribute. + The last component, describing the circular polarization state, is positive + for a right-hand circular state - that is the electric field vector rotates + clockwise at the sample and over time when observed from the source. + + I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale + linearly with the total degree of polarization, and indicate the relative + magnitudes of the pure linear and circular orientation contributions. + + Q (S_1) is linearly polarized along the x axis (Q > 0) or y axis (Q < 0). + + U (S_2) is linearly polarized along the x==y axis (U > 0) or the + -x==y axis (U < 0). + + V (S_3) is circularly polarized. V > 0 when the electric field vector rotates + clockwise at the sample with respect to time when observed from the source; + V < 0 indicates the opposite rotation. + dimensions: + rank: 2 + dim: [[1, nP], [2, 4]] + final_polarization_stokes(NX_NUMBER): + unit: NX_ANY + doc: | + Polarization vector on leaving beamline component using Stokes notation + (see incident_polarization_stokes). + dimensions: + rank: 2 + dim: [[1, nP], [2, 4]] + final_wavelength_spread(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Wavelength spread FWHM of beam leaving this component + dimensions: + rank: 1 + dim: [[1, m]] + final_beam_divergence(NX_FLOAT): + unit: NX_ANGLE + doc: | + Divergence FWHM of beam leaving this component + dimensions: + rank: 2 + dim: [[1, nP], [2, 2]] + flux(NX_FLOAT): + unit: NX_FLUX + doc: | + flux incident on beam plane area + dimensions: + rank: 1 + dim: [[1, nP]] + pulse_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy of a single pulse at the diagnostic point + average_power(NX_FLOAT): + unit: NX_POWER + doc: | + Average power at the diagnostic point + fluence(NX_FLOAT): + unit: NX_ANY + doc: | + Incident fluence at the diagnostic point + \@units: + type: NX_CHAR + doc: | + Here: SI units are 'J/m2', customary 'mJ/cm2'. + pulse_duration(NX_FLOAT): + unit: NX_TIME + doc: | + FWHM duration of the pulses at the diagnostic point + frog_trace(NX_FLOAT): + doc: | + FROG trace of the pulse. + dimensions: + rank: 2 + dim: [[1, nx], [2, ny]] + frog_delays(NX_FLOAT): + unit: NX_TIME + doc: | + Horizontal axis of a FROG trace, i.e. delay. + dimensions: + rank: 1 + dim: [[1, nx]] + frog_frequencies(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Vertical axis of a FROG trace, i.e. frequency. + dimensions: + rank: 1 + dim: [[1, ny]] + chirp_type(NX_CHAR): + doc: | + The type of chirp implemented + chirp_GDD(NX_FLOAT): + unit: NX_TIME + doc: | + Group delay dispersion of the pulse for linear chirp + (NXdata): + doc: | + Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly + useful for simulations which need to store plottable information at each beamline + component. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + exists: ['min', '0'] + doc: | + The NeXus coordinate system defines the Z axis to be along the nominal beam + direction. This is the same as the McStas coordinate system (see :ref:`Design-CoordinateSystem`). + However, the additional transformations needed to represent an altered beam + direction can be provided using this depends_on field that contains the path + to a NXtransformations group. This could represent redirection of the beam, + or a refined beam direction. + (NXtransformations): + exists: ['min', '0'] + doc: | + Direction (and location) for the beam. The location of the beam can be given by + any point which it passes through as its offset attribute. + DIRECTION(NX_NUMBER): + nameType: any + unit: NX_TRANSFORMATION + doc: | + Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] + and passes through the origin + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + doc: | + Three values that define the direction of beam vector + \@offset: + type: NX_NUMBER + doc: | + Three values that define the location of a point through which the beam passes + \@depends_on: + type: NX_CHAR + doc: | + Points to the path to a field defining the location on which this + depends or the string "." for origin. + reference_plane(NX_NUMBER): + nameType: any + unit: NX_TRANSFORMATION + doc: | + Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. + This also defines the parallel and perpendicular components of the beam's polarization. + If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + doc: | + Three values that define the direction of reference plane normal + \@offset: + type: NX_NUMBER + doc: | + Not required as beam direction offset locates the plane + \@depends_on: + type: NX_CHAR + doc: | + Points to the path to a field defining the location on which this + depends or the string "." for origin. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# dbe7fba854b6a29c068ef96a3c8fbe28c8217579d5d8a990ffa730ecd269bf21 +# +# +# +# +# +# +# These symbols coordinate datasets with the same shape. +# +# +# +# Number of scan points. +# +# +# +# +# Number of channels in the incident beam spectrum, if known +# +# +# +# +# Number of moments representing beam divergence (x, y, xy, etc.) +# +# +# +# +# Properties of the neutron or X-ray beam at a given location. +# +# This group is intended to be referenced +# by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is +# especially valuable in storing the results of instrument simulations in which it is useful +# to specify the beam profile, time distribution etc. at each beamline component. Otherwise, +# its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron +# scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is +# considered as a beamline component and this group may be defined as a subgroup directly inside +# :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an +# :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). +# +# Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. +# To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred +# by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. +# +# +# +# Distance from sample. Note, it is recommended to use NXtransformations instead. +# +# +# +# +# Energy carried by each particle of the beam on entering the beamline component. +# +# In the case of a monochromatic beam this is the scalar energy. +# Several other use cases are permitted, depending on the +# presence of other incident_energy_X fields. +# +# * In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights. +# * In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot. +# Here, incident_energy_weights and incident_energy_spread are not set. +# * In the case of a polychromatic beam that varies shot-to-shot, +# this is an array of length m with the relative weights in incident_energy_weights as a 2D array. +# * In the case of a polychromatic beam that varies shot-to-shot and where the channels also vary, +# this is a 2D array of dimensions nP by m (slow to fast) with the relative weights in incident_energy_weights as a 2D array. +# +# Note, variants are a good way to represent several of these use cases in a single dataset, +# e.g. if a calibrated, single-value energy value is available along with the original spectrum from which it was calibrated. +# +# +# +# +# +# +# +# The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in +# the energy spread, this is a 2D array of dimension nP by m +# (slow to fast) of the spreads of the corresponding +# wavelength in incident_wavelength. +# +# +# +# +# In the case of a polychromatic beam this is an array of length m of the relative +# weights of the corresponding energies in incident_energy. In the case of a +# polychromatic beam that varies shot-to-shot, this is a 2D array of dimensions np +# by m (slow to fast) of the relative weights of the corresponding energies in +# incident_energy. +# +# +# +# +# Energy carried by each particle of the beam on leaving the beamline component +# +# +# +# +# +# +# +# Change in particle energy caused by the beamline component +# +# +# +# +# +# +# +# In the case of a monochromatic beam this is the scalar +# wavelength. +# +# Several other use cases are permitted, depending on the +# presence or absence of other incident_wavelength_X +# fields. +# +# In the case of a polychromatic beam this is an array of +# length **m** of wavelengths, with the relative weights +# in ``incident_wavelength_weights``. +# +# In the case of a monochromatic beam that varies shot- +# to-shot, this is an array of wavelengths, one for each +# recorded shot. Here, ``incident_wavelength_weights`` and +# incident_wavelength_spread are not set. +# +# In the case of a polychromatic beam that varies shot-to- +# shot, this is an array of length **m** with the relative +# weights in ``incident_wavelength_weights`` as a 2D array. +# +# In the case of a polychromatic beam that varies shot-to- +# shot and where the channels also vary, this is a 2D array +# of dimensions **nP** by **m** (slow to fast) with the +# relative weights in ``incident_wavelength_weights`` as a 2D +# array. +# +# Note, :ref:`variants <Design-Variants>` are a good way +# to represent several of these use cases in a single dataset, +# e.g. if a calibrated, single-value wavelength value is +# available along with the original spectrum from which it +# was calibrated. +# Wavelength on entering beamline component +# +# +# +# +# In the case of a polychromatic beam this is an array of +# length **m** of the relative weights of the corresponding +# wavelengths in ``incident_wavelength``. +# +# In the case of a polychromatic beam that varies shot-to- +# shot, this is a 2D array of dimensions **nP** by **m** +# (slow to fast) of the relative weights of the +# corresponding wavelengths in ``incident_wavelength``. +# +# +# +# +# The wavelength spread FWHM for the corresponding +# wavelength(s) in incident_wavelength. +# +# In the case of shot-to-shot variation in the wavelength +# spread, this is a 2D array of dimension **nP** by +# **m** (slow to fast) of the spreads of the +# corresponding wavelengths in incident_wavelength. +# +# +# +# +# +# +# +# Beam crossfire in degrees parallel to the laboratory X axis +# +# The dimension **c** is a series of moments of that represent +# the standard uncertainty (e.s.d.) of the directions of +# of the beam. The first and second moments are in the XZ and YZ +# planes around the mean source beam direction, respectively. +# +# Further moments in **c** characterize co-variance terms, so +# the next moment is the product of the first two, and so on. +# +# +# +# +# +# +# +# +# Size of the beam entering this component. Note this represents +# a rectangular beam aperture, and values represent FWHM +# +# +# +# +# +# +# +# +# Wavelength on leaving beamline component +# +# +# +# +# +# +# +# Incident polarization as a Stokes vector +# on entering beamline component +# +# +# +# +# +# +# +# The units for this observable are not included in the NIAC list. +# Responsibility on correct formatting and parsing is handed to the user +# by using `NX_ANY`. Correct parsing can still be implemented by using +# this attribute. +# +# | Fill with: +# +# * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). +# * The unit unidata name if the unit has a name (Example: farad for capacitance). +# * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and +# does not have a name. +# +# Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). +# Here: SI units are V2/m2. +# +# +# +# +# +# Polarization as Stokes vector on leaving beamline component +# +# +# +# +# +# +# +# The units for this observable are not included in the NIAC list. +# Responsibility on correct formatting and parsing is handed to the user +# by using `NX_ANY`. Correct parsing can still be implemented by using +# this attribute. +# +# | Fill with: +# +# * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). +# * The unit unidata name if the unit has a name (Example: farad for capacitance). +# * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and +# does not have a name. +# +# Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). +# Here: SI units are V2/m2. +# +# +# +# +# +# Polarization vector on entering beamline component using Stokes notation +# +# The Stokes parameters are four components labelled I,Q,U,V or S_0,S_1,S_2,S_3. +# These are defined with the standard Nexus coordinate frame unless it is +# overridden by an NXtransformations field pointed to by a depends_on attribute. +# The last component, describing the circular polarization state, is positive +# for a right-hand circular state - that is the electric field vector rotates +# clockwise at the sample and over time when observed from the source. +# +# I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale +# linearly with the total degree of polarization, and indicate the relative +# magnitudes of the pure linear and circular orientation contributions. +# +# Q (S_1) is linearly polarized along the x axis (Q > 0) or y axis (Q < 0). +# +# U (S_2) is linearly polarized along the x==y axis (U > 0) or the +# -x==y axis (U < 0). +# +# V (S_3) is circularly polarized. V > 0 when the electric field vector rotates +# clockwise at the sample with respect to time when observed from the source; +# V < 0 indicates the opposite rotation. +# +# +# +# +# +# +# +# +# Polarization vector on leaving beamline component using Stokes notation +# (see incident_polarization_stokes). +# +# +# +# +# +# +# +# +# Wavelength spread FWHM of beam leaving this component +# +# +# +# +# +# +# +# Divergence FWHM of beam leaving this component +# +# +# +# +# +# +# +# +# flux incident on beam plane area +# +# +# +# +# +# +# +# Energy of a single pulse at the diagnostic point +# +# +# +# +# Average power at the diagnostic point +# +# +# +# +# Incident fluence at the diagnostic point +# +# +# +# Here: SI units are 'J/m2', customary 'mJ/cm2'. +# +# +# +# +# +# FWHM duration of the pulses at the diagnostic point +# +# +# +# +# FROG trace of the pulse. +# +# +# +# +# +# +# +# +# Horizontal axis of a FROG trace, i.e. delay. +# +# +# +# +# +# +# +# Vertical axis of a FROG trace, i.e. frequency. +# +# +# +# +# +# +# +# The type of chirp implemented +# +# +# +# +# Group delay dispersion of the pulse for linear chirp +# +# +# +# +# Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly +# useful for simulations which need to store plottable information at each beamline +# component. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# The NeXus coordinate system defines the Z axis to be along the nominal beam +# direction. This is the same as the McStas coordinate system (see :ref:`Design-CoordinateSystem`). +# However, the additional transformations needed to represent an altered beam +# direction can be provided using this depends_on field that contains the path +# to a NXtransformations group. This could represent redirection of the beam, +# or a refined beam direction. +# +# +# +# +# Direction (and location) for the beam. The location of the beam can be given by +# any point which it passes through as its offset attribute. +# +# +# +# Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] +# and passes through the origin +# +# +# +# +# +# +# +# +# Three values that define the direction of beam vector +# +# +# +# +# Three values that define the location of a point through which the beam passes +# +# +# +# +# Points to the path to a field defining the location on which this +# depends or the string "." for origin. +# +# +# +# +# +# Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. +# This also defines the parallel and perpendicular components of the beam's polarization. +# If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin +# +# +# +# +# +# +# +# +# Three values that define the direction of reference plane normal +# +# +# +# +# Not required as beam direction offset locates the plane +# +# +# +# +# Points to the path to a field defining the location on which this +# depends or the string "." for origin. +# +# +# +# +# diff --git a/base_classes/nyaml/NXbeam_stop.yaml b/base_classes/nyaml/NXbeam_stop.yaml new file mode 100644 index 0000000000..f2cf05b88b --- /dev/null +++ b/base_classes/nyaml/NXbeam_stop.yaml @@ -0,0 +1,207 @@ +category: base +doc: | + A device that blocks the beam completely, usually to protect a detector. + + Beamstops and their positions are important for SANS + and SAXS experiments. +type: group +NXbeam_stop(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the beamstop and NXoff_geometry to describe its shape instead + doc: | + engineering shape, orientation and position of the beam stop. + description: + doc: | + description of beamstop + enumeration: [circular, rectangular] + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + (NXcylindrical_geometry): + exists: ['min', '0'] + doc: | + This group is an alternative to NXoff_geometry for describing the shape + of the beam stop. + size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of beamstop. If this is not sufficient to describe the beam stop use + NXoff_geometry instead. + x(NX_FLOAT): + unit: NX_LENGTH + doc: | + x position of the beamstop in relation to the detector. + Note, it is recommended to use NXtransformations instead. + y(NX_FLOAT): + unit: NX_LENGTH + doc: | + y position of the beamstop in relation to the detector. + Note, it is recommended to use NXtransformations instead. + distance_to_detector(NX_FLOAT): + unit: NX_LENGTH + doc: | + distance of the beamstop to the detector. + Note, it is recommended to use NXtransformations instead. + status: + enumeration: [in, out] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the beam stop is its center in the x and y axis. The reference point on the z axis is the + surface of the beam stop pointing towards the source. + + .. image:: beam_stop/beam_stop.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8c256286b0040d033d1e37850936cb15fbaf674606ac0e0ffcd7188c2684cb66 +# +# +# +# +# +# +# A device that blocks the beam completely, usually to protect a detector. +# +# Beamstops and their positions are important for SANS +# and SAXS experiments. +# +# +# engineering shape, orientation and position of the beam stop. +# +# +# description of beamstop +# +# +# +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# This group is an alternative to NXoff_geometry for describing the shape +# of the beam stop. +# +# +# +# +# Size of beamstop. If this is not sufficient to describe the beam stop use +# NXoff_geometry instead. +# +# +# +# +# x position of the beamstop in relation to the detector. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# y position of the beamstop in relation to the detector. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# distance of the beamstop to the detector. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the beam stop is its center in the x and y axis. The reference point on the z axis is the +# surface of the beam stop pointing towards the source. +# +# .. image:: beam_stop/beam_stop.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXbending_magnet.yaml b/base_classes/nyaml/NXbending_magnet.yaml new file mode 100644 index 0000000000..8cec9c3336 --- /dev/null +++ b/base_classes/nyaml/NXbending_magnet.yaml @@ -0,0 +1,210 @@ +category: base +doc: | + A bending magnet +type: group +NXbending_magnet(NXobject): + critical_energy(NX_FLOAT): + unit: NX_ENERGY + bending_radius(NX_FLOAT): + unit: NX_LENGTH + magnetic_field(NX_FLOAT): + unit: NX_CURRENT + doc: | + strength of magnetic field of dipole magnets + accepted_photon_beam_divergence(NX_FLOAT): + unit: NX_LENGTH + doc: | + An array of four numbers giving X+, X-, Y+ and Y- half divergence + source_distance_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance of source point from particle beam waist in X (horizontal) direction. + Note, it is recommended to use NXtransformations instead to place component. + source_distance_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance of source point from particle beam waist in Y (vertical) direction. + Note, it is recommended to use NXtransformations instead to place component. + divergence_x_plus(NX_FLOAT): + unit: NX_ANGLE + doc: | + Accepted photon beam divergence in X+ (horizontal outboard) direction. + Note that divergence_x_plus+divergence_x_minus is the total horizontal beam divergence. + divergence_x_minus(NX_FLOAT): + unit: NX_ANGLE + doc: | + Accepted photon beam divergence in X- (horizontal inboard) direction. + Note that divergence_x_plus+divergence_x_minus is the total horizontal beam divergence. + divergence_y_plus(NX_FLOAT): + unit: NX_ANGLE + doc: | + Accepted photon beam divergence in Y+ (vertical upward) direction. + Note that divergence_y_plus+divergence_y_minus is the total vertical beam divergence. + divergence_y_minus(NX_FLOAT): + unit: NX_ANGLE + doc: | + Accepted photon beam divergence in Y- (vertical downward) direction. + Note that divergence_y_plus+divergence_y_minus is the total vertical beam divergence. + spectrum(NXdata): + doc: | + bending magnet spectrum + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the bending magnet and NXoff_geometry to describe its shape instead + doc: | + "Engineering" position of bending magnet + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a bending magnet. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 99e6fdaf28f81ce18c473abeb17354d390f7383d1715f41e4cc141dbf447dc65 +# +# +# +# +# +# A bending magnet +# +# +# +# strength of magnetic field of dipole magnets +# +# +# +# An array of four numbers giving X+, X-, Y+ and Y- half divergence +# +# +# +# +# Distance of source point from particle beam waist in X (horizontal) direction. +# Note, it is recommended to use NXtransformations instead to place component. +# +# +# +# +# Distance of source point from particle beam waist in Y (vertical) direction. +# Note, it is recommended to use NXtransformations instead to place component. +# +# +# +# +# Accepted photon beam divergence in X+ (horizontal outboard) direction. +# Note that divergence_x_plus+divergence_x_minus is the total horizontal beam divergence. +# +# +# +# +# Accepted photon beam divergence in X- (horizontal inboard) direction. +# Note that divergence_x_plus+divergence_x_minus is the total horizontal beam divergence. +# +# +# +# +# Accepted photon beam divergence in Y+ (vertical upward) direction. +# Note that divergence_y_plus+divergence_y_minus is the total vertical beam divergence. +# +# +# +# +# Accepted photon beam divergence in Y- (vertical downward) direction. +# Note that divergence_y_plus+divergence_y_minus is the total vertical beam divergence. +# +# +# bending magnet spectrum +# "Engineering" position of bending magnet +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a bending magnet. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXcapillary.yaml b/base_classes/nyaml/NXcapillary.yaml new file mode 100644 index 0000000000..aacb021fd6 --- /dev/null +++ b/base_classes/nyaml/NXcapillary.yaml @@ -0,0 +1,163 @@ +category: base +doc: | + A capillary lens to focus the X-ray beam. + + Based on information provided by Gerd Wellenreuther (DESY). +type: group +NXcapillary(NXobject): + type(NX_CHAR): + doc: | + Type of the capillary + enumeration: [single_bounce, polycapillary, conical_capillary] + manufacturer(NX_CHAR): + doc: | + The manufacturer of the capillary. This is actually important as + it may have an impact on performance. + maximum_incident_angle(NX_FLOAT): + unit: NX_ANGLE + accepting_aperture(NX_FLOAT): + unit: NX_ANGLE + (NXdata)gain: + doc: | + The gain of the capillary as a function of energy + (NXdata)transmission: + doc: | + The transmission of the capillary as a function of energy + working_distance(NX_FLOAT): + unit: NX_LENGTH + focal_size(NX_FLOAT): + doc: | + The focal size in FWHM + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a capillary lens. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 532702bd23065d69a03c9e0b7aaf7136d411799faab901669a8be1f5d007b6c9 +# +# +# +# +# +# +# A capillary lens to focus the X-ray beam. +# +# Based on information provided by Gerd Wellenreuther (DESY). +# +# +# Type of the capillary +# +# +# +# +# +# +# +# +# The manufacturer of the capillary. This is actually important as +# it may have an impact on performance. +# +# +# +# +# +# +# The gain of the capillary as a function of energy +# +# +# +# +# The transmission of the capillary as a function of energy +# +# +# +# +# +# The focal size in FWHM +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a capillary lens. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXcite.yaml b/base_classes/nyaml/NXcite.yaml new file mode 100644 index 0000000000..d183f1fd89 --- /dev/null +++ b/base_classes/nyaml/NXcite.yaml @@ -0,0 +1,112 @@ +category: base +doc: | + A literature reference + + Definition to include references for example for detectors, + manuals, instruments, acquisition or analysis software used. + + The idea would be to include this in the relevant NeXus object: + :ref:`NXdetector` for detectors, :ref:`NXinstrument` for instruments, etc. +type: group +NXcite(NXobject): + description(NX_CHAR): + doc: | + This should describe the reason for including this reference. + For example: The dataset in this group was normalised using the method + which is described in detail in this reference. + url(NX_CHAR): + doc: | + URL referencing the document or data. + doi(NX_CHAR): + doc: | + DOI referencing the document or data. + endnote(NX_CHAR): + doc: | + Bibliographic reference data in EndNote format. + bibtex(NX_CHAR): + doc: | + Bibliographic reference data in BibTeX format. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 59929309fbee197465213bc3b923e04782d370b2058f5a970b41ecf71e85ba7a +# +# +# +# +# +# A literature reference +# +# Definition to include references for example for detectors, +# manuals, instruments, acquisition or analysis software used. +# +# The idea would be to include this in the relevant NeXus object: +# :ref:`NXdetector` for detectors, :ref:`NXinstrument` for instruments, etc. +# +# +# +# This should describe the reason for including this reference. +# For example: The dataset in this group was normalised using the method +# which is described in detail in this reference. +# +# +# +# URL referencing the document or data. +# +# +# DOI referencing the document or data. +# +# +# Bibliographic reference data in EndNote format. +# +# +# Bibliographic reference data in BibTeX format. +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXcollection.yaml b/base_classes/nyaml/NXcollection.yaml new file mode 100644 index 0000000000..5b3dd56a28 --- /dev/null +++ b/base_classes/nyaml/NXcollection.yaml @@ -0,0 +1,102 @@ +category: base + +# The ignoreExtra* attributes are used in the definition to +# avoid warning messages that would be generated from +# unexpected groups, fields, and attributes. +# Since no groups or attributes are declared here, _every_ +# child of this class would generate a warning message without this +# attribute being set to "true". +doc: | + An unvalidated set of terms, such as the description of a beam line. + + Use :ref:`NXcollection` to gather together any set of terms. + The original suggestion is to use this as a container + class for the description of a beamline. + + For NeXus validation, :ref:`NXcollection` will always generate + a warning since it is always an optional group. + Anything (groups, fields, or attributes) placed in + an :ref:`NXcollection` group will not be validated. +type: group +ignoreExtraGroups: true +ignoreExtraFields: true +ignoreExtraAttributes: true +NXcollection(NXobject): + + # any content is purely optional + + # NOTE + # ===== + # NXcollection is an unvalidated class, do not add any subgroups. + # See: https://github.com/nexusformat/definitions/issues/259 + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# fdd5367211b59613e74b746761c655ba70f7ae36889538b8eec14fd904748fbf +# +# +# +# +# +# +# +# +# An unvalidated set of terms, such as the description of a beam line. +# +# Use :ref:`NXcollection` to gather together any set of terms. +# The original suggestion is to use this as a container +# class for the description of a beamline. +# +# For NeXus validation, :ref:`NXcollection` will always generate +# a warning since it is always an optional group. +# Anything (groups, fields, or attributes) placed in +# an :ref:`NXcollection` group will not be validated. +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXcollimator.yaml b/base_classes/nyaml/NXcollimator.yaml new file mode 100644 index 0000000000..baab547487 --- /dev/null +++ b/base_classes/nyaml/NXcollimator.yaml @@ -0,0 +1,196 @@ +category: base +doc: | + A beamline collimator. +type: group +NXcollimator(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the collimator and NXoff_geometry to describe its shape instead + doc: | + position, shape and size + type: + enumeration: [Soller, radial, oscillating, honeycomb] + soller_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angular divergence of Soller collimator + divergence_x(NX_FLOAT): + unit: NX_ANGLE + doc: | + divergence of collimator in local x direction + divergence_y(NX_FLOAT): + unit: NX_ANGLE + doc: | + divergence of collimator in local y direction + frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Frequency of oscillating collimator + (NXlog)frequency_log: + doc: | + Log of frequency + blade_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + blade thickness + blade_spacing(NX_FLOAT): + unit: NX_LENGTH + doc: | + blade spacing + absorbing_material: + doc: | + name of absorbing material + transmitting_material: + doc: | + name of transmitting material + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + Assuming a collimator with a "flat" entry surface, the reference plane is the plane which contains this surface. The reference + point of the collimator in the x and y axis is the centre of the collimator entry surface on that plane. The reference plane is orthogonal + to the z axis and the location of this plane is the reference point on the z axis. The collimator faces negative z values. + + .. image:: collimator/collimator.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 00a9964086dc22e6087e2003333b5cff83695a44785b893c6d1604e7052defb2 +# +# +# +# +# +# A beamline collimator. +# +# position, shape and size +# +# +# +# +# +# +# +# +# +# +# Angular divergence of Soller collimator +# +# +# divergence of collimator in local x direction +# +# +# divergence of collimator in local y direction +# +# +# Frequency of oscillating collimator +# +# +# Log of frequency +# +# +# blade thickness +# +# +# blade spacing +# +# +# name of absorbing material +# +# +# name of transmitting material +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# Assuming a collimator with a "flat" entry surface, the reference plane is the plane which contains this surface. The reference +# point of the collimator in the x and y axis is the centre of the collimator entry surface on that plane. The reference plane is orthogonal +# to the z axis and the location of this plane is the reference point on the z axis. The collimator faces negative z values. +# +# .. image:: collimator/collimator.png +# :width: 40% +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXcrystal.yaml b/base_classes/nyaml/NXcrystal.yaml new file mode 100644 index 0000000000..3a1c66c55a --- /dev/null +++ b/base_classes/nyaml/NXcrystal.yaml @@ -0,0 +1,667 @@ +category: base +doc: | + A crystal monochromator or analyzer. + + Permits double bent + monochromator comprised of multiple segments with anisotropic + Gaussian mosaic. + + If curvatures are set to zero or are absent, array + is considered to be flat. + + Scattering vector is perpendicular to surface. Crystal is oriented + parallel to beam incident on crystal before rotation, and lies in + vertical plane. +symbols: + doc: | + These symbols will be used below to coordinate dimensions with the same lengths. + n_comp: | + number of different unit cells to be described + i: | + number of wavelengths +type: group +NXcrystal(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the crystal and NXoff_geometry to describe its shape instead + doc: | + Position of crystal + usage(NX_CHAR): + doc: | + How this crystal is used. Choices are in the list. + enumeration: + Bragg: + doc: | + reflection geometry + Laue: + doc: | + 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. + See, for example: + http://www.iucr.org/__data/iucr/cif/standard/cifstd15.html or + http://www.cas.org/training/stneasytips/subinforformula1.html. + type: + doc: | + Type or material of monochromating substance. + Chemical formula can be specified separately. + Use the "reflection" field to indicate the (hkl) orientation. + Use the "d_spacing" field to record the lattice plane spacing. + + This field was changed (2010-11-17) from an enumeration to + a string since common usage showed a wider variety of use + than a simple list. These are the items in the list at + the time of the change: PG (Highly Oriented Pyrolytic Graphite) | + Ge | Si | Cu | Fe3Si | CoFe | Cu2MnAl (Heusler) | Multilayer | + Diamond. + chemical_formula: + + # copied from NXsample + doc: | + 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. + order_no(NX_INT): + doc: | + A number which describes if this is the first, second,.. + :math:`n^{th}` crystal in a multi crystal monochromator + cut_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Cut angle of reflecting Bragg plane and plane of crystal surface + space_group: + doc: | + Space group of crystal structure + unit_cell(NX_FLOAT): + unit: NX_LENGTH + doc: | + Unit cell parameters (lengths and angles) + dimensions: + rank: 2 + dim: [[1, n_comp], [2, 6]] + + # NXfilter defines each unit cell parameter separately. Let's be consistent. + unit_cell_a(NX_FLOAT): + unit: NX_LENGTH + + # as used in NXfilter + doc: | + Unit cell lattice parameter: length of side a + unit_cell_b(NX_FLOAT): + unit: NX_LENGTH + + # as used in NXfilter + doc: | + Unit cell lattice parameter: length of side b + unit_cell_c(NX_FLOAT): + unit: NX_LENGTH + + # as used in NXfilter + doc: | + Unit cell lattice parameter: length of side c + unit_cell_alpha(NX_FLOAT): + unit: NX_ANGLE + + # as used in NXfilter + doc: | + Unit cell lattice parameter: angle alpha + unit_cell_beta(NX_FLOAT): + unit: NX_ANGLE + + # as used in NXfilter + doc: | + Unit cell lattice parameter: angle beta + unit_cell_gamma(NX_FLOAT): + unit: NX_ANGLE + + # as used in NXfilter + doc: | + Unit cell lattice parameter: angle gamma + unit_cell_volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Volume of the unit cell + orientation_matrix(NX_FLOAT): + doc: | + Orientation matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 2 + + # 3,3 + dim: [[1, 3], [2, 3]] + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Optimum diffracted wavelength + dimensions: + dim: [[1, i]] + d_spacing(NX_FLOAT): + unit: NX_LENGTH + doc: | + spacing between crystal planes of the reflection + scattering_vector(NX_FLOAT): + unit: NX_WAVENUMBER + doc: | + Scattering vector, Q, of nominal reflection + reflection(NX_INT): + unit: NX_UNITLESS + doc: | + Miller indices (hkl) values of nominal reflection + dimensions: + dim: [[1, 3]] + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the crystal. (Required for Laue orientations - see "usage" field) + density(NX_NUMBER): + unit: NX_MASS_DENSITY + doc: | + mass density of the crystal + segment_width(NX_FLOAT): + unit: NX_LENGTH + doc: | + Horizontal width of individual segment + segment_height(NX_FLOAT): + unit: NX_LENGTH + doc: | + Vertical height of individual segment + segment_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of individual segment + segment_gap(NX_FLOAT): + unit: NX_LENGTH + doc: | + Typical gap between adjacent segments + segment_columns(NX_FLOAT): + unit: NX_LENGTH + doc: | + number of segment columns in horizontal direction + segment_rows(NX_FLOAT): + unit: NX_LENGTH + doc: | + number of segment rows in vertical direction + mosaic_horizontal(NX_FLOAT): + unit: NX_ANGLE + doc: | + horizontal mosaic Full Width Half Maximum + mosaic_vertical(NX_FLOAT): + unit: NX_ANGLE + doc: | + vertical mosaic Full Width Half Maximum + curvature_horizontal(NX_FLOAT): + unit: NX_ANGLE + doc: | + Horizontal curvature of focusing crystal + curvature_vertical(NX_FLOAT): + unit: NX_ANGLE + doc: | + Vertical curvature of focusing crystal + is_cylindrical(NX_BOOLEAN): + doc: | + Is this crystal bent cylindrically? + cylindrical_orientation_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + If cylindrical: cylinder orientation angle + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Polar (scattering) angle at which crystal assembly is positioned. + Note: some instrument geometries call this term 2theta. + Note: it is recommended to use NXtransformations instead. + dimensions: + dim: [[1, i]] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Azimuthal angle at which crystal assembly is positioned. + Note: it is recommended to use NXtransformations instead. + dimensions: + dim: [[1, i]] + bragg_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Bragg angle of nominal reflection + dimensions: + dim: [[1, i]] + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + average/nominal crystal temperature + temperature_coefficient(NX_FLOAT): + unit: NX_ANY + doc: | + how lattice parameter changes with temperature + (NXlog)temperature_log: + doc: | + log file of crystal temperature + (NXdata)reflectivity: + doc: | + crystal reflectivity versus wavelength + (NXdata)transmission: + doc: | + crystal transmission versus wavelength + (NXshape)shape: + deprecated: Use NXoff_geometry instead to describe the shape of the monochromator + doc: | + A NXshape group describing the shape of the crystal arrangement + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a crystal. + (NXtransformations): + doc: | + Transformations used by this component to define its position and orientation. + + # TODO need more parameters here, such as ... + # list from Rainer Gehrke, DESY (some items may already be present) + # Parameters for crystals + # + Field indicating whether it is Bragg or Laue see usage + # + The crystal structure (enumeration, e.g. Zincblende ..) see space_group + # + Lattice constant see unit_cell + # + Miller indices of reflection (h,k,l) see reflection + # + First (or only) element see order_no + # + Second element (if any) see order_no + # + Temperature factor (optional) see temperature_coefficient + # + Asymmetric angle (if applicable) see cut_angle + # + Mosaic angular spread (if applicable) see mosaic_horizontal and mosaic_vertical + # + Thickness (mandatory for Laue, else optional) see thickness + # Figure for crystals and mirrors (to describe curved surfaces) + # + Field indicating whether concave or convex see curvature_horizontal and curvature_vertical + # + Field indicating whether cylindrical or not see is_cylindrical + # + If cylindrical: cylinder orientation angle see cylindrical_orientation_angle + # Now come the different surface figures with the necessary parameters: + # 1. Flat + # 2. Spherical (spherical radius) + # 3. Elliptical and hyperbolical (semi-major axis, semi-minor axis, angle of major axis and pole) + # 4. Toroidal (major radius, minor radius) + # 5. Parabolical (parabolic parameter a) + # 6. Conical (cone half aperture) + # 7. Polynomial (degree of polynom, array with polynom coefficients) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ff4ce24fb54dfca75794d2f6fcd2b632e90265354d07459acfdd18a8aaaf46a9 +# +# +# +# +# +# +# These symbols will be used below to coordinate dimensions with the same lengths. +# number of different unit cells to be described +# number of wavelengths +# +# +# +# A crystal monochromator or analyzer. +# +# Permits double bent +# monochromator comprised of multiple segments with anisotropic +# Gaussian mosaic. +# +# If curvatures are set to zero or are absent, array +# is considered to be flat. +# +# Scattering vector is perpendicular to surface. Crystal is oriented +# parallel to beam incident on crystal before rotation, and lies in +# vertical plane. +# +# +# +# Position of crystal +# +# +# How this crystal is used. Choices are in the list. +# +# reflection geometry +# +# +# 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. +# See, for example: +# http://www.iucr.org/__data/iucr/cif/standard/cifstd15.html or +# http://www.cas.org/training/stneasytips/subinforformula1.html. +# +# +# +# +# +# +# Type or material of monochromating substance. +# Chemical formula can be specified separately. +# Use the "reflection" field to indicate the (hkl) orientation. +# Use the "d_spacing" field to record the lattice plane spacing. +# +# This field was changed (2010-11-17) from an enumeration to +# a string since common usage showed a wider variety of use +# than a simple list. These are the items in the list at +# the time of the change: PG (Highly Oriented Pyrolytic Graphite) | +# Ge | Si | Cu | Fe3Si | CoFe | Cu2MnAl (Heusler) | Multilayer | +# Diamond. +# +# +# +# +# +# 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. +# +# +# +# +# A number which describes if this is the first, second,.. +# :math:`n^{th}` crystal in a multi crystal monochromator +# +# +# +# Cut angle of reflecting Bragg plane and plane of crystal surface +# +# +# Space group of crystal structure +# +# +# Unit cell parameters (lengths and angles) +# +# +# +# +# +# +# +# Unit cell lattice parameter: length of side a +# +# +# Unit cell lattice parameter: length of side b +# +# +# Unit cell lattice parameter: length of side c +# +# +# Unit cell lattice parameter: angle alpha +# +# +# Unit cell lattice parameter: angle beta +# +# +# Unit cell lattice parameter: angle gamma +# +# +# Volume of the unit cell +# +# +# +# Orientation matrix of single crystal sample using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# Optimum diffracted wavelength +# +# +# +# spacing between crystal planes of the reflection +# +# +# Scattering vector, Q, of nominal reflection +# +# +# Miller indices (hkl) values of nominal reflection +# +# +# +# Thickness of the crystal. (Required for Laue orientations - see "usage" field) +# +# +# mass density of the crystal +# +# +# Horizontal width of individual segment +# +# +# Vertical height of individual segment +# +# +# Thickness of individual segment +# +# +# Typical gap between adjacent segments +# +# +# number of segment columns in horizontal direction +# +# +# number of segment rows in vertical direction +# +# +# horizontal mosaic Full Width Half Maximum +# +# +# vertical mosaic Full Width Half Maximum +# +# +# Horizontal curvature of focusing crystal +# +# +# Vertical curvature of focusing crystal +# +# +# Is this crystal bent cylindrically? +# +# +# If cylindrical: cylinder orientation angle +# +# +# +# Polar (scattering) angle at which crystal assembly is positioned. +# Note: some instrument geometries call this term 2theta. +# Note: it is recommended to use NXtransformations instead. +# +# +# +# +# +# Azimuthal angle at which crystal assembly is positioned. +# Note: it is recommended to use NXtransformations instead. +# +# +# +# +# Bragg angle of nominal reflection +# +# +# +# average/nominal crystal temperature +# +# +# how lattice parameter changes with temperature +# +# +# log file of crystal temperature +# +# +# crystal reflectivity versus wavelength +# +# +# crystal transmission versus wavelength +# +# +# A NXshape group describing the shape of the crystal arrangement +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a crystal. +# +# +# +# +# Transformations used by this component to define its position and orientation. +# +# +# +# diff --git a/base_classes/nyaml/NXcylindrical_geometry.yaml b/base_classes/nyaml/NXcylindrical_geometry.yaml new file mode 100644 index 0000000000..189ede84aa --- /dev/null +++ b/base_classes/nyaml/NXcylindrical_geometry.yaml @@ -0,0 +1,169 @@ +category: base +doc: | + Geometry description for cylindrical shapes. + This class can be used in place of ``NXoff_geometry`` when an exact + representation for cylinders is preferred. + For example, for Helium-tube, neutron detectors. + It can be used to describe the shape of any beamline component, including detectors. + In the case of detectors it can be used to define the shape of a single pixel, or, + if the pixel shapes are non-uniform, to describe the shape of the whole detector. +symbols: + doc: | + These symbols will be used below. + i: | + number of vertices required to define all cylinders in the shape + j: | + number of cylinders in the shape + k: | + number cylinders which are detectors +type: group +NXcylindrical_geometry(NXobject): + vertices(NX_NUMBER): + unit: NX_LENGTH + doc: | + List of x,y,z coordinates for vertices. + The origin of the coordinates is the position of the parent component, for + example the NXdetector which the geometry describes. + If the shape describes a single pixel for a detector with uniform pixel shape + then the origin is the position of each pixel as described by the + ``x/y/z_pixel_offset`` datasets in ``NXdetector``. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + cylinders(NX_INT): + doc: | + List of indices of vertices in the ``vertices`` dataset to form each cylinder. + Each cylinder is described by three vertices A, B, C. + First vertex A lies on the cylinder axis and circular face, second point B + on edge of the same face as A, and third point C at the other face and on axis. + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + detector_number(NX_INT): + doc: | + Maps cylinders in ``cylinder``, by index, with a detector id. + dimensions: + rank: 1 + dim: [[1, k]] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9bbcf1ff2b2841c8960f59949dfb345ca6966cd04ab611c7e9843c1c81d643e6 +# +# +# +# +# +# +# These symbols will be used below. +# +# +# number of vertices required to define all cylinders in the shape +# +# +# number of cylinders in the shape +# number cylinders which are detectors +# +# +# +# Geometry description for cylindrical shapes. +# This class can be used in place of ``NXoff_geometry`` when an exact +# representation for cylinders is preferred. +# For example, for Helium-tube, neutron detectors. +# It can be used to describe the shape of any beamline component, including detectors. +# In the case of detectors it can be used to define the shape of a single pixel, or, +# if the pixel shapes are non-uniform, to describe the shape of the whole detector. +# +# +# +# +# +# List of x,y,z coordinates for vertices. +# The origin of the coordinates is the position of the parent component, for +# example the NXdetector which the geometry describes. +# If the shape describes a single pixel for a detector with uniform pixel shape +# then the origin is the position of each pixel as described by the +# ``x/y/z_pixel_offset`` datasets in ``NXdetector``. +# +# +# +# +# +# +# +# +# +# +# +# +# List of indices of vertices in the ``vertices`` dataset to form each cylinder. +# Each cylinder is described by three vertices A, B, C. +# First vertex A lies on the cylinder axis and circular face, second point B +# on edge of the same face as A, and third point C at the other face and on axis. +# +# +# +# +# +# +# +# +# +# +# +# Maps cylinders in ``cylinder``, by index, with a detector id. +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXdata.yaml b/base_classes/nyaml/NXdata.yaml new file mode 100644 index 0000000000..3bfbf1da82 --- /dev/null +++ b/base_classes/nyaml/NXdata.yaml @@ -0,0 +1,881 @@ +category: base +doc: | + :ref:`NXdata` describes the plottable data and related dimension scales. + + .. index:: plotting + + It is strongly recommended that there is at least one :ref:`NXdata` + group in each :ref:`NXentry` group. + Note that the fields named ``AXISNAME`` and ``DATA`` + can be defined with different names. + (Upper case is used to indicate that the actual name is left to the user.) + The ``signal`` and ``axes`` attributes of the + ``data`` group define which items + are plottable data and which are *dimension scales*, respectively. + + :ref:`NXdata` is used to implement one of the basic motivations in NeXus, + to provide a default plot for the data of this :ref:`NXentry`. The actual data + might be stored in another group and (hard) linked to the :ref:`NXdata` group. + + * Each :ref:`NXdata` group will define one field as the default + plottable data. The value of the ``signal`` attribute names this field. + Additional fields may be used to describe the dimension scales and + uncertainities. + The ``auxiliary_signals`` attribute is a list of the other fields + to be plotted with the ``signal`` data. + * The plottable data may be of arbitrary rank up to a maximum + of ``NX_MAXRANK=32`` (for compatibility with backend file formats). + * The plottable data will be named as the value of + the group ``signal`` attribute, such as:: + + data:NXdata + @signal = "counts" + @axes = "mr" + @mr_indices = 0 + counts: float[100] --> the default dependent data + mr: float[100] --> the default independent data + + The field named in the ``signal`` attribute **must** exist, either + directly as a NeXus field or defined through a link. + + * The group ``axes`` attribute will name the + *dimension scale* associated with the plottable data. + + If available, the standard deviations of the data are to be + stored in a data set of the same rank and dimensions, with the name ``errors``. + + * For each data dimension, there should be a one-dimensional array + of the same length. + * These one-dimensional arrays are the *dimension scales* of the + data, *i.e*. the values of the independent variables at which the data + is measured, such as scattering angle or energy transfer. + + .. index:: link + .. index:: axes (attribute) + + The preferred method to associate each data dimension with + its respective dimension scale is to specify the field name + of each dimension scale in the group ``axes`` attribute as a string list. + Here is an example for a 2-D data set *data* plotted + against *time*, and *pressure*. (An additional *temperature* data set + is provided and could be selected as an alternate for the *pressure* axis.):: + + data_2d:NXdata + @signal="data" + @axes=["time", "pressure"] + @pressure_indices=1 + @temperature_indices=1 + @time_indices=0 + data: float[1000,20] + pressure: float[20] + temperature: float[20] + time: float[1000] + + .. rubric:: Old methods to identify the plottable data + + There are two older methods of associating + each data dimension to its respective dimension scale. + Both are now out of date and + should not be used when writing new data files. + However, client software should expect to see data files + written with any of these methods. + + * One method uses the ``axes`` + attribute to specify the names of each *dimension scale*. + + * The oldest method uses the ``axis`` attribute on each + *dimension scale* to identify + with an integer the axis whose value is the number of the dimension. + + .. index: !plot; axis label + plot, axis units + units + dimension scale + + Each axis of the plot may be labeled with information from the + dimension scale for that axis. The optional ``@long_name`` attribute + is provided as the axis label default. If ``@long_name`` is not + defined, then use the name of the dimension scale. A ``@units`` attribute, + if available, may be added to the axis label for further description. + See the section :ref:`Design-Units` for more information. + + .. index: !plot; axis title + + The optional ``title`` field, if available, provides a suggested + title for the plot. If no ``title`` field is found in the :ref:`NXdata` + group, look for a ``title`` field in the parent :ref:`NXentry` group, + with a fallback to displaying the path to the :ref:`NXdata` group. + + NeXus is about how to find and annotate the data to be plotted + but not to describe how the data is to be plotted. + (https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute) + +# The ignoreExtra* attributes are used in the definition to +# avoid warning messages that would be generated from unexpected fields or attributes. +# Since common use of NXdata indicates field names of any value, _many_ +# instances of this class would generate a warning message during validation +# without this attribute being set to "true". +symbols: + doc: | + These symbols will be used below to coordinate fields with the same + shape. + dataRank: | + rank of the ``DATA`` field + n: | + length of the ``AXISNAME`` field + nx: | + length of the ``x`` field + ny: | + length of the ``y`` field + nz: | + length of the ``z`` field +type: group +ignoreExtraFields: true +ignoreExtraAttributes: true +NXdata(NXobject): + \@auxiliary_signals: + doc: | + .. index:: plotting + + Array of strings holding the :ref:`names ` of additional + signals to be plotted with the default :ref:`signal `. + These fields or links *must* exist and be direct children of this NXdata group. + + Each auxiliary signal needs to be of the same shape as the default signal. + + .. NIAC2018: + https://www.nexusformat.org/NIAC2018Minutes.html + \@signal: + doc: | + .. index:: find the default plottable data + .. index:: plotting + .. index:: signal attribute value + + Declares which NeXus field is the default. + The value is the :ref:`name ` of the data field to be plotted. + This field or link *must* exist and be a direct child of this NXdata group. + + It is recommended (as of NIAC2014) to use this attribute + rather than adding a signal attribute to the field. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + \@axes: + doc: | + .. index:: plotting + + Array of strings holding the :ref:`names ` of + the independent data fields used in the default plot for all of + the dimensions of the :ref:`signal ` + as well as any :ref:`auxiliary signals `. + + One name is provided for every dimension in the *signal* or *auxiliary signal* fields. + + The *axes* values are the names of fields or links that *must* exist and be direct + children of this NXdata group. + + An axis slice is specified using a field named ``AXISNAME_indices`` + as described below (where the text shown here as ``AXISNAME`` is to be + replaced by the actual field name). + + When no default axis is available for a particular dimension + of the plottable data, use a "." in that position. + Such as:: + + @axes=["time", ".", "."] + + Since there are three items in the list, the *signal* field + must be a three-dimensional array (rank=3). The first dimension + is described by the values of a one-dimensional array named ``time`` + while the other two dimensions have no fields to be used as dimension scales. + + See examples provided on the NeXus wiki: + https://www.nexusformat.org/2014_axes_and_uncertainties.html + + If there are no axes at all (such as with a stack of images), + the axes attribute can be omitted. + \@AXISNAME_indices: + type: NX_INT + + # nxdl.xsd rules do not allow us to show this as a variable name + # - we'll use ALL CAPS (see #562) + + # AXISNAME_indices documentation copied from datarules.rst + doc: | + Each ``AXISNAME_indices`` attribute indicates the dependency + relationship of the ``AXISNAME`` field (where ``AXISNAME`` + is the name of a field that exists in this ``NXdata`` group) + with one or more dimensions of the plottable data. + + Integer array that defines the indices of the *signal* field + (that field will be a multidimensional array) + which need to be used in the *AXISNAME* field in + order to reference the corresponding axis value. + + The first index of an array is ``0`` (zero). + + Here, *AXISNAME* is to be replaced by the name of each + field described in the ``axes`` attribute. + An example with 2-D data, :math:`d(t,P)`, will illustrate:: + + data_2d:NXdata + @signal="data" + @axes=["time", "pressure"] + @time_indices=0 + @pressure_indices=1 + data: float[1000,20] + time: float[1000] + pressure: float[20] + + This attribute is to be provided in all situations. + However, if the indices attributes are missing + (such as for data files written before this specification), + file readers are encouraged to make their best efforts + to plot the data. + Thus the implementation of the + ``AXISNAME_indices`` attribute is based on the model of + "strict writer, liberal reader". + + .. note:: Attributes potentially containing multiple values + (axes and _indices) are to be written as string or integer arrays, + to avoid string parsing in reading applications. + \@AXISNAME_depends: + doc: | + Points to the path of a field defining the axis on which the ``AXISNAME`` axis depends. + + This concept allows to link an axis to a respective field in the NeXus hierarchy, thereby + defining the physical quantity it represents. + + Here, *AXISNAME* is to be replaced by the name of each + field described in the ``axes`` attribute. + + Examples: + If a calibration has been performed, ``@AXISNAME_depends`` links to the result of + that calibration: + + @AXISNAME_depends: '/entry/process/calibration/calibrated_axis' + + If the axis corresponds to a coordinate of a detector, ``@AXISNAME_depends`` links + to that detector axis: + + @AXISNAME_depends: '/entry/instrument/detector/axis/some_axis' for a 2D detector + + If the axis is a scanned motor, ``@AXISNAME_depends`` links to the transformation + describing the respective motion, e.g.: + + @AXISNAME_depends: '/entry/instrument/detector/transformations/some_transformation' for a motion of the detector + AXISNAME(NX_NUMBER): + nameType: any + doc: | + Dimension scale defining an axis of the data. + Client is responsible for defining the dimensions of the data. + The name of this field may be changed to fit the circumstances. + Standard NeXus client tools will use the attributes to determine + how to use this field. + dimensions: + rank: 1 + doc: | + A *dimension scale* must have a rank of 1 and has length ``n``. + dim: [[1, n]] + \@long_name: + doc: | + Axis label + \@distribution: + type: NX_BOOLEAN + doc: | + ``0|false``: single value, + ``1|true``: multiple values + \@first_good: + type: NX_INT + doc: | + Index of first good value + \@last_good: + type: NX_INT + doc: | + Index of last good value + \@axis: + type: NX_POSINT + deprecated: Use the group ``axes`` attribute (NIAC2014) + doc: | + Index (positive integer) identifying this specific set of numbers. + + N.B. The ``axis`` attribute is the old way of designating a link. + Do not use the ``axes`` attribute with the ``axis`` attribute. + The ``axes`` *group* attribute is now preferred. + FIELDNAME_errors(NX_NUMBER): + nameType: any + doc: | + "Errors" (meaning *uncertainties* or *standard deviations*) + associated with any field named ``FIELDNAME`` in this ``NXdata`` + group (e.g. an axis, signal or auxiliary signal). + + The dimensions of the ``FIELDNAME_errors`` field must match + the dimensions of the ``FIELDNAME`` field. + DATA(NX_NUMBER): + nameType: any + doc: | + .. index:: plotting + + This field contains the data values to be used as the + NeXus *plottable data*. + Client is responsible for defining the dimensions of the data. + The name of this field may be changed to fit the circumstances. + Standard NeXus client tools will use the attributes to determine + how to use this field. + dimensions: + rank: dataRank + doc: | + The rank (``dataRank``) of the ``data`` must satisfy + ``1 <= dataRank <= NX_MAXRANK=32``. + At least one ``dim`` must have length ``n``. + dim: [] + \@signal: + type: NX_POSINT + deprecated: Use the group ``signal`` attribute (NIAC2014) + doc: | + .. index:: plotting + + Plottable (independent) axis, indicate index number. + Only one field in a :ref:`NXdata` group may have the + ``signal=1`` attribute. + Do not use the ``signal`` attribute with the ``axis`` attribute. + \@axes: + deprecated: Use the group ``axes`` attribute (NIAC2014) + doc: | + Defines the names of the dimension scales + (independent axes) for this data set + as a colon-delimited array. + NOTE: The ``axes`` attribute is the preferred + method of designating a link. + Do not use the ``axes`` attribute with the ``axis`` attribute. + \@long_name: + doc: | + data label + errors(NX_NUMBER): + deprecated: Use ``DATA_errors`` instead (NIAC2018) + doc: | + Standard deviations of data values - + the data array is identified by the group attribute ``signal``. + The ``errors`` array must have the same dimensions as ``DATA``. + Client is responsible for defining the dimensions of the data. + dimensions: + rank: dataRank + doc: | + The ``errors`` must have + the same rank (``dataRank``) + as the ``data``. + At least one ``dim`` must have length "n". + dim: [] + scaling_factor(NX_FLOAT): + doc: | + The elements in data are usually float values really. For + efficiency reasons these are usually stored as integers + after scaling with a scale factor. This value is the scale + factor. It is required to get the actual physical value, + when necessary. + offset(NX_FLOAT): + doc: | + An optional offset to apply to the values in data. + title: + doc: | + Title for the plot. + x(NX_FLOAT): + unit: NX_ANY + doc: | + This is an array holding the values to use for the x-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, nx]] + y(NX_FLOAT): + unit: NX_ANY + doc: | + This is an array holding the values to use for the y-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, ny]] + z(NX_FLOAT): + unit: NX_ANY + doc: | + This is an array holding the values to use for the z-axis of + data. The units must be appropriate for the measurement. + dimensions: + rank: 1 + dim: [[1, nz]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5a45322e878727216a5e86464351d5b329c144c33583ace0a439ce9c6cb7bb5a +# +# +# +# +# +# +# +# These symbols will be used below to coordinate fields with the same +# shape. +# +# +# +# rank of the ``DATA`` field +# +# +# +# +# length of the ``AXISNAME`` field +# +# +# +# +# length of the ``x`` field +# +# +# +# +# length of the ``y`` field +# +# +# +# +# length of the ``z`` field +# +# +# +# +# :ref:`NXdata` describes the plottable data and related dimension scales. +# +# .. index:: plotting +# +# It is strongly recommended that there is at least one :ref:`NXdata` +# group in each :ref:`NXentry` group. +# Note that the fields named ``AXISNAME`` and ``DATA`` +# can be defined with different names. +# (Upper case is used to indicate that the actual name is left to the user.) +# The ``signal`` and ``axes`` attributes of the +# ``data`` group define which items +# are plottable data and which are *dimension scales*, respectively. +# +# :ref:`NXdata` is used to implement one of the basic motivations in NeXus, +# to provide a default plot for the data of this :ref:`NXentry`. The actual data +# might be stored in another group and (hard) linked to the :ref:`NXdata` group. +# +# * Each :ref:`NXdata` group will define one field as the default +# plottable data. The value of the ``signal`` attribute names this field. +# Additional fields may be used to describe the dimension scales and +# uncertainities. +# The ``auxiliary_signals`` attribute is a list of the other fields +# to be plotted with the ``signal`` data. +# * The plottable data may be of arbitrary rank up to a maximum +# of ``NX_MAXRANK=32`` (for compatibility with backend file formats). +# * The plottable data will be named as the value of +# the group ``signal`` attribute, such as:: +# +# data:NXdata +# @signal = "counts" +# @axes = "mr" +# @mr_indices = 0 +# counts: float[100] --> the default dependent data +# mr: float[100] --> the default independent data +# +# The field named in the ``signal`` attribute **must** exist, either +# directly as a NeXus field or defined through a link. +# +# * The group ``axes`` attribute will name the +# *dimension scale* associated with the plottable data. +# +# If available, the standard deviations of the data are to be +# stored in a data set of the same rank and dimensions, with the name ``errors``. +# +# * For each data dimension, there should be a one-dimensional array +# of the same length. +# * These one-dimensional arrays are the *dimension scales* of the +# data, *i.e*. the values of the independent variables at which the data +# is measured, such as scattering angle or energy transfer. +# +# .. index:: link +# .. index:: axes (attribute) +# +# The preferred method to associate each data dimension with +# its respective dimension scale is to specify the field name +# of each dimension scale in the group ``axes`` attribute as a string list. +# Here is an example for a 2-D data set *data* plotted +# against *time*, and *pressure*. (An additional *temperature* data set +# is provided and could be selected as an alternate for the *pressure* axis.):: +# +# data_2d:NXdata +# @signal="data" +# @axes=["time", "pressure"] +# @pressure_indices=1 +# @temperature_indices=1 +# @time_indices=0 +# data: float[1000,20] +# pressure: float[20] +# temperature: float[20] +# time: float[1000] +# +# .. rubric:: Old methods to identify the plottable data +# +# There are two older methods of associating +# each data dimension to its respective dimension scale. +# Both are now out of date and +# should not be used when writing new data files. +# However, client software should expect to see data files +# written with any of these methods. +# +# * One method uses the ``axes`` +# attribute to specify the names of each *dimension scale*. +# +# * The oldest method uses the ``axis`` attribute on each +# *dimension scale* to identify +# with an integer the axis whose value is the number of the dimension. +# +# .. index: !plot; axis label +# plot, axis units +# units +# dimension scale +# +# Each axis of the plot may be labeled with information from the +# dimension scale for that axis. The optional ``@long_name`` attribute +# is provided as the axis label default. If ``@long_name`` is not +# defined, then use the name of the dimension scale. A ``@units`` attribute, +# if available, may be added to the axis label for further description. +# See the section :ref:`Design-Units` for more information. +# +# .. index: !plot; axis title +# +# The optional ``title`` field, if available, provides a suggested +# title for the plot. If no ``title`` field is found in the :ref:`NXdata` +# group, look for a ``title`` field in the parent :ref:`NXentry` group, +# with a fallback to displaying the path to the :ref:`NXdata` group. +# +# NeXus is about how to find and annotate the data to be plotted +# but not to describe how the data is to be plotted. +# (https://www.nexusformat.org/NIAC2018Minutes.html#nxdata-plottype--attribute) +# +# +# +# .. index:: plotting +# +# Array of strings holding the :ref:`names <validItemName>` of additional +# signals to be plotted with the default :ref:`signal </NXdata@signal-attribute>`. +# These fields or links *must* exist and be direct children of this NXdata group. +# +# Each auxiliary signal needs to be of the same shape as the default signal. +# +# .. NIAC2018: +# https://www.nexusformat.org/NIAC2018Minutes.html +# +# +# +# +# .. index:: find the default plottable data +# .. index:: plotting +# .. index:: signal attribute value +# +# Declares which NeXus field is the default. +# The value is the :ref:`name <validItemName>` of the data field to be plotted. +# This field or link *must* exist and be a direct child of this NXdata group. +# +# It is recommended (as of NIAC2014) to use this attribute +# rather than adding a signal attribute to the field. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# .. index:: plotting +# +# Array of strings holding the :ref:`names <validItemName>` of +# the independent data fields used in the default plot for all of +# the dimensions of the :ref:`signal </NXdata@signal-attribute>` +# as well as any :ref:`auxiliary signals </NXdata@auxiliary_signals-attribute>`. +# +# One name is provided for every dimension in the *signal* or *auxiliary signal* fields. +# +# The *axes* values are the names of fields or links that *must* exist and be direct +# children of this NXdata group. +# +# An axis slice is specified using a field named ``AXISNAME_indices`` +# as described below (where the text shown here as ``AXISNAME`` is to be +# replaced by the actual field name). +# +# When no default axis is available for a particular dimension +# of the plottable data, use a "." in that position. +# Such as:: +# +# @axes=["time", ".", "."] +# +# Since there are three items in the list, the *signal* field +# must be a three-dimensional array (rank=3). The first dimension +# is described by the values of a one-dimensional array named ``time`` +# while the other two dimensions have no fields to be used as dimension scales. +# +# See examples provided on the NeXus wiki: +# https://www.nexusformat.org/2014_axes_and_uncertainties.html +# +# If there are no axes at all (such as with a stack of images), +# the axes attribute can be omitted. +# +# +# +# +# +# +# Each ``AXISNAME_indices`` attribute indicates the dependency +# relationship of the ``AXISNAME`` field (where ``AXISNAME`` +# is the name of a field that exists in this ``NXdata`` group) +# with one or more dimensions of the plottable data. +# +# Integer array that defines the indices of the *signal* field +# (that field will be a multidimensional array) +# which need to be used in the *AXISNAME* field in +# order to reference the corresponding axis value. +# +# The first index of an array is ``0`` (zero). +# +# Here, *AXISNAME* is to be replaced by the name of each +# field described in the ``axes`` attribute. +# An example with 2-D data, :math:`d(t,P)`, will illustrate:: +# +# data_2d:NXdata +# @signal="data" +# @axes=["time", "pressure"] +# @time_indices=0 +# @pressure_indices=1 +# data: float[1000,20] +# time: float[1000] +# pressure: float[20] +# +# This attribute is to be provided in all situations. +# However, if the indices attributes are missing +# (such as for data files written before this specification), +# file readers are encouraged to make their best efforts +# to plot the data. +# Thus the implementation of the +# ``AXISNAME_indices`` attribute is based on the model of +# "strict writer, liberal reader". +# +# .. note:: Attributes potentially containing multiple values +# (axes and _indices) are to be written as string or integer arrays, +# to avoid string parsing in reading applications. +# +# +# +# +# Points to the path of a field defining the axis on which the ``AXISNAME`` axis depends. +# +# This concept allows to link an axis to a respective field in the NeXus hierarchy, thereby +# defining the physical quantity it represents. +# +# Here, *AXISNAME* is to be replaced by the name of each +# field described in the ``axes`` attribute. +# +# Examples: +# If a calibration has been performed, ``@AXISNAME_depends`` links to the result of +# that calibration: +# +# @AXISNAME_depends: '/entry/process/calibration/calibrated_axis' +# +# If the axis corresponds to a coordinate of a detector, ``@AXISNAME_depends`` links +# to that detector axis: +# +# @AXISNAME_depends: '/entry/instrument/detector/axis/AXISNAME' for a 2D detector +# +# If the axis is a scanned motor, ``@AXISNAME_depends`` links to the transformation +# describing the respective motion, e.g.: +# +# @AXISNAME_depends: '/entry/instrument/detector/transformations/AXISNAME' for a motion of the detector +# +# +# +# +# Dimension scale defining an axis of the data. +# Client is responsible for defining the dimensions of the data. +# The name of this field may be changed to fit the circumstances. +# Standard NeXus client tools will use the attributes to determine +# how to use this field. +# +# +# +# A *dimension scale* must have a rank of 1 and has length ``n``. +# +# +# +# +# +# Axis label +# +# +# +# +# ``0|false``: single value, +# ``1|true``: multiple values +# +# +# +# +# Index of first good value +# +# +# +# +# Index of last good value +# +# +# +# +# Index (positive integer) identifying this specific set of numbers. +# +# N.B. The ``axis`` attribute is the old way of designating a link. +# Do not use the ``axes`` attribute with the ``axis`` attribute. +# The ``axes`` *group* attribute is now preferred. +# +# +# +# +# +# "Errors" (meaning *uncertainties* or *standard deviations*) +# associated with any field named ``FIELDNAME`` in this ``NXdata`` +# group (e.g. an axis, signal or auxiliary signal). +# +# The dimensions of the ``FIELDNAME_errors`` field must match +# the dimensions of the ``FIELDNAME`` field. +# +# +# +# +# .. index:: plotting +# +# This field contains the data values to be used as the +# NeXus *plottable data*. +# Client is responsible for defining the dimensions of the data. +# The name of this field may be changed to fit the circumstances. +# Standard NeXus client tools will use the attributes to determine +# how to use this field. +# +# +# +# The rank (``dataRank``) of the ``data`` must satisfy +# ``1 <= dataRank <= NX_MAXRANK=32``. +# At least one ``dim`` must have length ``n``. +# +# +# +# +# .. index:: plotting +# +# Plottable (independent) axis, indicate index number. +# Only one field in a :ref:`NXdata` group may have the +# ``signal=1`` attribute. +# Do not use the ``signal`` attribute with the ``axis`` attribute. +# +# +# +# +# Defines the names of the dimension scales +# (independent axes) for this data set +# as a colon-delimited array. +# NOTE: The ``axes`` attribute is the preferred +# method of designating a link. +# Do not use the ``axes`` attribute with the ``axis`` attribute. +# +# +# +# +# data label +# +# +# +# +# +# Standard deviations of data values - +# the data array is identified by the group attribute ``signal``. +# The ``errors`` array must have the same dimensions as ``DATA``. +# Client is responsible for defining the dimensions of the data. +# +# +# +# The ``errors`` must have +# the same rank (``dataRank``) +# as the ``data``. +# At least one ``dim`` must have length "n". +# +# +# +# +# +# The elements in data are usually float values really. For +# efficiency reasons these are usually stored as integers +# after scaling with a scale factor. This value is the scale +# factor. It is required to get the actual physical value, +# when necessary. +# +# +# +# +# An optional offset to apply to the values in data. +# +# +# +# +# Title for the plot. +# +# +# +# +# This is an array holding the values to use for the x-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# +# +# This is an array holding the values to use for the y-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# +# +# This is an array holding the values to use for the z-axis of +# data. The units must be appropriate for the measurement. +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXdetector.yaml b/base_classes/nyaml/NXdetector.yaml new file mode 100644 index 0000000000..12df646e15 --- /dev/null +++ b/base_classes/nyaml/NXdetector.yaml @@ -0,0 +1,1751 @@ +category: base +doc: | + A detector, detector bank, or multidetector. +symbols: + doc: | + These symbols will be used below to illustrate the coordination of the + rank and sizes of datasets and the preferred ordering of the + dimensions. Each of these are optional (so the rank of the datasets + will vary according to the situation) and the general ordering + principle is slowest to fastest. The type of each dimension should + follow the order of scan points, detector output (e.g. pixels), then + time-of-flight (i.e. spectroscopy, spectrometry). Note that the output + of a detector is not limited to single values (0D), lists (1D) and + images (2), but three or higher dimensional arrays can be produced by + a detector at each trigger. + nP: | + number of scan points (only present in scanning measurements) + i: | + number of detector pixels in the first (slowest) direction + j: | + number of detector pixels in the second (faster) direction + k: | + number of detector pixels in the third (if necessary, fastest) + direction + tof: | + number of bins in the time-of-flight histogram +type: group +(NXobject)NXdetector: + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + doc: | + Total time of flight + dimensions: + rank: 1 + dim: [[1, tof+1]] + \@axis: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [3] + \@primary: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [1] + \@long_name: + doc: | + Total time of flight + raw_time_of_flight(NX_INT): + unit: NX_PULSES + doc: | + In DAQ clock pulses + dimensions: + rank: 1 + dim: [[1, tof+1]] + \@frequency: + type: NX_NUMBER + doc: | + Clock frequency in Hz + detector_number(NX_INT): + doc: | + Identifier for detector (pixels) + Can be multidimensional, if needed + data(NX_NUMBER): + unit: NX_ANY + doc: | + Data values from the detector. The rank and dimension ordering should follow a principle of + slowest to fastest measurement axes and may be explicitly specified in application definitions. + + Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be + the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions + of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single + scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. + Repetition of an experiment in a time series tends to be used similar to a slow scan axis + and so will often be in the first dimension of the data array. + + The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions + (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an + imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data + will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to + be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. + + Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift + detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. + + The type of each dimension should should follow the order of scan points, detector pixels, + then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) + shown here are merely illustrative of coordination between related datasets. + dimensions: + rank: 4 + dim: [[1, nP], [2, i], [3, j], [4, tof]] + \@long_name: + doc: | + Title of measurement + \@check_sum: + type: NX_INT + doc: | + Integral of data as check of data integrity + data_errors(NX_NUMBER): + unit: NX_ANY + doc: | + The best estimate of the uncertainty in the data value (array size should match the data field). Where + possible, this should be the standard deviation, which has the same units + as the data. The form data_error is deprecated. + dimensions: + rank: 4 + dim: [[1, nP], [2, i], [3, j], [4, tof]] + x_pixel_offset(NX_FLOAT): + unit: NX_LENGTH + doc: | + Offset from the detector center in x-direction. + Can be multidimensional when needed. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@axis: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [1] + \@primary: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [1] + \@long_name: + doc: | + x-axis offset from detector center + y_pixel_offset(NX_FLOAT): + unit: NX_LENGTH + doc: | + Offset from the detector center in the y-direction. + Can be multidimensional when different values are required for each pixel. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@axis: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [2] + \@primary: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [1] + \@long_name: + doc: | + y-axis offset from detector center + z_pixel_offset(NX_FLOAT): + unit: NX_LENGTH + doc: | + Offset from the detector center in the z-direction. + Can be multidimensional when different values are required for each pixel. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@axis: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [3] + \@primary: + type: NX_POSINT + deprecated: | + see: https://github.com/nexusformat/definitions/issues/436 + enumeration: [1] + \@long_name: + doc: | + y-axis offset from detector center + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the distance to the previous component in the + instrument; most often the sample. The usage depends on the + nature of the detector: Most often it is the distance of the + detector assembly. But there are irregular detectors. In this + case the distance must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + dimensions: + rank: 3 + dim: [[1, nP], [2, i], [3, j]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + This is the polar angle of the detector towards the previous + component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the polar_angle of the detector assembly. + But there are irregular detectors. + In this + case, the polar_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + dimensions: + rank: 3 + dim: [[1, nP], [2, i], [3, j]] + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + This is the azimuthal angle angle of the detector towards + the previous component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the azimuthal_angle of the detector assembly. + But there are irregular detectors. + In this + case, the azimuthal_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + dimensions: + rank: 3 + dim: [[1, nP], [2, i], [3, j]] + description: + doc: | + name/manufacturer/model/etc. information + serial_number: + doc: | + Serial number for the detector + local_name: + doc: | + Local name for the detector + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the detector and NXoff_geometry to describe its shape instead + doc: | + Position and orientation of detector + solid_angle(NX_FLOAT): + unit: NX_SOLID_ANGLE + doc: | + Solid angle subtended by the detector at the sample + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of each detector pixel. If it is scalar all pixels are the same size. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of each detector pixel. If it is scalar all pixels are the same size + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + dead_time(NX_FLOAT): + unit: NX_TIME + doc: | + Detector dead time + dimensions: + rank: 3 + dim: [[1, nP], [2, i], [3, j]] + gas_pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Detector gas pressure + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + detection_gas_path(NX_FLOAT): + unit: NX_LENGTH + doc: | + maximum drift space dimension + crate(NX_INT): + doc: | + Crate number of detector + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@local_name: + doc: | + Equivalent local term + slot(NX_INT): + doc: | + Slot number of detector + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@local_name: + doc: | + Equivalent local term + input(NX_INT): + doc: | + Input number of detector + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + \@local_name: + doc: | + Equivalent local term + type: + doc: | + Description of type such as He3 gas cylinder, He3 PSD, scintillator, + fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, + CMOS, ... + efficiency(NXdata): + doc: | + Spectral efficiency of detector with respect to e.g. wavelength + \@signal: + enumeration: [efficiency] + \@axes: + + # TODO: clarify the various use cases + enumeration: [., . ., . . ., . . . ., wavelength] + \@wavelength_indices: + + # TODO: clarify the actual possibilities + enumeration: [0] + efficiency(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + efficiency of the detector + dimensions: + rank: 3 + dim: [[1, i], [2, j], [3, k]] + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + This field can be two things: + + 1. For a pixel detector it provides the nominal wavelength + for which the detector has been calibrated. + + 2. For other detectors this field has to be seen together with + the efficiency field above. + For some detectors, the efficiency is wavelength dependent. + Thus this field provides the wavelength axis for the efficiency field. + In this use case, the efficiency and wavelength arrays must + have the same dimensionality. + dimensions: + rank: 3 + dim: [[1, i], [2, j], [3, k]] + real_time(NX_NUMBER): + unit: NX_TIME + doc: | + Real-time of the exposure (use this if exposure time varies for + each array element, otherwise use ``count_time`` field). + + Most often there is a single real time value that is constant across + an entire image frame. In such cases, only a 1-D array is needed. + But there are detectors in which the real time + changes per pixel. In that case, more than one dimension is needed. Therefore + the rank of this field should be less than or equal to (detector rank + 1). + dimensions: + rank: 3 + dim: [[1, nP], [2, i], [3, j]] + start_time(NX_FLOAT): + unit: NX_TIME + doc: | + start time for each frame, with the ``start`` attribute as absolute reference + dimensions: + rank: 1 + dim: [[1, nP]] + \@start: + type: NX_DATE_TIME + stop_time(NX_FLOAT): + unit: NX_TIME + doc: | + stop time for each frame, with the ``start`` attribute as absolute reference + dimensions: + rank: 1 + dim: [[1, nP]] + \@start: + type: NX_DATE_TIME + calibration_date(NX_DATE_TIME): + doc: | + date of last calibration (geometry and/or efficiency) measurements + calibration_method(NXnote): + doc: | + summary of conversion of array data to pixels (e.g. polynomial + approximations) and location of details of the calibrations + layout: + doc: | + How the detector is represented + enumeration: [point, linear, area] + count_time(NX_NUMBER): + unit: NX_TIME + doc: | + Elapsed actual counting time + dimensions: + rank: 1 + dim: [[1, nP]] + data_file(NXnote): + (NXcollection): + doc: | + Use this group to provide other data related to this NXdetector group. + sequence_number(NX_INT): + doc: | + In order to properly sort the order of the images taken in (for + example) a tomography experiment, a sequence number is stored with each + image. + dimensions: + rank: 1 + dim: [[1, nBrightFrames]] + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the x position where the direct beam would hit the detector. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the y position where the direct beam would hit the detector. + This is a length and can be outside of the actual + detector. The length can be in physical units or pixels + as documented by the units attribute. + frame_start_number(NX_INT): + doc: | + This is the start number of the first frame of a scan. In protein crystallography measurements one + often scans a couple of frames on a give sample, then does something else, + then returns to the same sample and scans some more frames. Each time with + a new data file. This number helps concatenating such measurements. + diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + The diameter of a cylindrical detector + acquisition_mode(NX_CHAR): + doc: | + The acquisition mode of the detector. + enumeration: [gated, triggered, summed, event, histogrammed, decimated] + angular_calibration_applied(NX_BOOLEAN): + doc: | + True when the angular calibration has been applied in the + electronics, false otherwise. + angular_calibration(NX_FLOAT): + doc: | + Angular calibration data. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + flatfield_applied(NX_BOOLEAN): + doc: | + True when the flat field correction has been applied in the + electronics, false otherwise. + flatfield(NX_FLOAT): + doc: | + Flat field correction data. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + flatfield_errors(NX_FLOAT): + doc: | + Errors of the flat field correction data. + The form flatfield_error is deprecated. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + pixel_mask_applied(NX_BOOLEAN): + doc: | + True when the pixel mask correction has been applied in the + electronics, false otherwise. + pixel_mask(NX_INT): + doc: | + The 32-bit pixel mask for the detector. Can be either one mask + for the whole dataset (i.e. an array with indices i, j) or + each frame can have its own mask (in which case it would be + an array with indices np, i, j). + + Contains a bit field for each pixel to signal dead, + blind or high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + .. can't make a table here, a bullet list will have to do for now + + * bit 0: gap (pixel with no sensor) + * bit 1: dead + * bit 2: under responding + * bit 3: over responding + * bit 4: noisy + * bit 5: -undefined- + * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) + * bit 7: -undefined- + * bit 8: user defined mask (e.g. around beamstop) + * bits 9-30: -undefined- + * bit 31: virtual pixel (corner pixel with interpolated value) + + Normal data analysis software would + not take pixels into account + when a bit in (mask & 0x0000FFFF) is + set. Tag bit in the upper + two bytes would indicate special pixel + properties that normally + would not be a sole reason to reject the + intensity value (unless + lower bits are set. + + If the full bit depths is not required, providing a + mask with fewer bits is permissible. + + If needed, additional pixel masks can be specified by + including additional entries named pixel_mask_N, where + N is an integer. For example, a general bad pixel mask + could be specified in pixel_mask that indicates noisy + and dead pixels, and an additional pixel mask from + experiment-specific shadowing could be specified in + pixel_mask_2. The cumulative mask is the bitwise OR + of pixel_mask and any pixel_mask_N entries. + dimensions: + rank: 2 + dim: [[1, i], [2, j]] + image_key(NX_INT): + doc: | + This field allow to distinguish different types of exposure to the same detector "data" field. + Some techniques require frequent (re-)calibration inbetween measuremnts and this way of + recording the different measurements preserves the chronological order with is important for + correct processing. + + This is used for example in tomography (`:ref:`NXtomo`) sample projections, + dark and flat images, a magic number is recorded per frame. + + The key is as follows: + + * projection (sample) = 0 + * flat field = 1 + * dark field = 2 + * invalid = 3 + * background (no sample, but buffer where applicable) = 4 + + In cases where the data is of type :ref:`NXlog` this can also be an NXlog. + dimensions: + rank: 1 + dim: [[1, np]] + countrate_correction_applied(NX_BOOLEAN): + doc: | + Counting detectors usually are not able to measure all incoming particles, + especially at higher count-rates. Count-rate correction is applied to + account for these errors. + + True when count-rate correction has been applied, false otherwise. + countrate_correction_lookup_table(NX_NUMBER): + doc: | + The countrate_correction_lookup_table defines the LUT used for count-rate + correction. It maps a measured count :math:`c` to its corrected value + :math:`countrate\_correction\_lookup\_table[c]`. + + :math:`m` denotes the length of the table. + dimensions: + rank: 1 + dim: [[1, m]] + virtual_pixel_interpolation_applied(NX_BOOLEAN): + doc: | + True when virtual pixel interpolation has been applied, false otherwise. + + When virtual pixel interpolation is applied, values of some pixels may + contain interpolated values. For example, to account for space between + readout chips on a module, physical pixels on edges and corners between + chips may have larger sensor areas and counts may be distributed between + their logical pixels. + bit_depth_readout(NX_INT): + doc: | + How many bits the electronics reads per pixel. + With CCD's and single photon counting detectors, + this must not align with traditional integer sizes. + This can be 4, 8, 12, 14, 16, ... + detector_readout_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + trigger_delay_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector firmware after receiving the trigger signal + to when the detector starts to acquire the exposure, including any user set delay.. + This is important to know for time resolved experiments. + trigger_delay_time_set(NX_FLOAT): + unit: NX_TIME + doc: | + User-specified trigger delay. + trigger_internal_delay_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector hardware after receiving the + trigger signal to when the detector starts to acquire the exposure. + It forms the lower boundary of the trigger_delay_time when the user + does not request an additional delay. + trigger_dead_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time during which no new trigger signal can be accepted. + Typically this is the + trigger_delay_time + exposure_time + readout_time. + This is important to know for time resolved experiments. + frame_time(NX_FLOAT): + unit: NX_TIME + doc: | + This is time for each frame. This is exposure_time + readout time. + dimensions: + rank: 1 + dim: [[1, nP]] + gain_setting(NX_CHAR): + doc: | + The gain setting of the detector. This is a detector-specific value + meant to document the gain setting of the detector during data + collection, for detectors with multiple available gain settings. + + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low`` + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. + saturation_value(NX_NUMBER): + doc: | + The value at which the detector goes into saturation. + Especially common to CCD detectors, the data + is known to be invalid above this value. + + For example, given a saturation_value and an underload_value, the valid + pixels are those less than or equal to the saturation_value and greater + than or equal to the underload_value. + + The precise type should match the type of the data. + underload_value(NX_NUMBER): + doc: | + The lowest value at which pixels for this detector would be reasonably + measured. The data is known to be invalid below this value. + + For example, given a saturation_value and an underload_value, the valid + pixels are those less than or equal to the saturation_value and greater + than or equal to the underload_value. + + The precise type should match the type of the data. + number_of_cycles(NX_INT): + doc: | + CCD images are sometimes constructed by summing + together multiple short exposures in the + electronics. This reduces background etc. + This is the number of short exposures used to sum + images for an image. + sensor_material(NX_CHAR): + doc: | + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the name of this converter material. + sensor_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the thickness of this converter material. + threshold_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Single photon counter detectors can be adjusted + for a certain energy range in which they + work optimally. This is the energy setting for this. + (NXdetector_module): + doc: | + For use in special cases where the data in NXdetector + is represented in several parts, each with a separate geometry. + pixel_shape(choice): + (NXoff_geometry): + doc: | + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape. + (NXcylindrical_geometry): + doc: | + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape and require being described by cylinders. + detector_shape(choice): + (NXoff_geometry): + doc: | + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape. + (NXcylindrical_geometry): + doc: | + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape and require being described by cylinders. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + amplifier_type(NX_CHAR): + doc: | + Type of electron amplifier, MCP, channeltron, etc. + detector_type(NX_CHAR): + doc: | + Description of the detector type, DLD, Phosphor+CCD, CMOS. + detector_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Voltage applied to detector. + amplifier_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Voltage applied to the amplifier. + amplifier_bias(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + The low voltage of the amplifier migh not be the ground. + sensor_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of each imaging sensor chip on the detector. + sensor_count(NX_INT): + unit: NX_UNITLESS + doc: | + Number of imaging sensor chips on the detector. + sensor_pixel_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Physical size of the pixels of the imaging chip on the detector. + sensor_pixels(NX_INT): + unit: NX_UNITLESS + doc: | + Number of raw active elements in each dimension. Important for swept scans. + (NXfabrication): + (NXdata): + doc: | + raw data output from the detector + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the detector is the center of the first pixel. + In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cf337a792e12304ca6fa5767928b3a58b6527152c48a24d0406e227efc050cb7 +# +# +# +# +# +# +# These symbols will be used below to illustrate the coordination of the +# rank and sizes of datasets and the preferred ordering of the +# dimensions. Each of these are optional (so the rank of the datasets +# will vary according to the situation) and the general ordering +# principle is slowest to fastest. The type of each dimension should +# follow the order of scan points, detector output (e.g. pixels), then +# time-of-flight (i.e. spectroscopy, spectrometry). Note that the output +# of a detector is not limited to single values (0D), lists (1D) and +# images (2), but three or higher dimensional arrays can be produced by +# a detector at each trigger. +# +# +# +# number of scan points (only present in scanning measurements) +# +# +# +# +# number of detector pixels in the first (slowest) direction +# +# +# +# +# number of detector pixels in the second (faster) direction +# +# +# +# +# number of detector pixels in the third (if necessary, fastest) +# direction +# +# +# +# +# number of bins in the time-of-flight histogram +# +# +# +# +# A detector, detector bank, or multidetector. +# +# +# +# Total time of flight +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total time of flight +# +# +# +# +# +# In DAQ clock pulses +# +# +# +# +# +# +# Clock frequency in Hz +# +# +# +# +# +# Identifier for detector (pixels) +# Can be multidimensional, if needed +# +# +# +# +# Data values from the detector. The rank and dimension ordering should follow a principle of +# slowest to fastest measurement axes and may be explicitly specified in application definitions. +# +# Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be +# the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions +# of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single +# scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. +# Repetition of an experiment in a time series tends to be used similar to a slow scan axis +# and so will often be in the first dimension of the data array. +# +# The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions +# (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an +# imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data +# will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to +# be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. +# +# Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift +# detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. +# +# The type of each dimension should should follow the order of scan points, detector pixels, +# then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) +# shown here are merely illustrative of coordination between related datasets. +# +# +# +# +# +# +# +# +# +# Title of measurement +# +# +# +# +# Integral of data as check of data integrity +# +# +# +# +# +# The best estimate of the uncertainty in the data value (array size should match the data field). Where +# possible, this should be the standard deviation, which has the same units +# as the data. The form data_error is deprecated. +# +# +# +# +# +# +# +# +# +# +# Offset from the detector center in x-direction. +# Can be multidimensional when needed. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# x-axis offset from detector center +# +# +# +# +# +# Offset from the detector center in the y-direction. +# Can be multidimensional when different values are required for each pixel. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# y-axis offset from detector center +# +# +# +# +# +# Offset from the detector center in the z-direction. +# Can be multidimensional when different values are required for each pixel. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# y-axis offset from detector center +# +# +# +# +# +# This is the distance to the previous component in the +# instrument; most often the sample. The usage depends on the +# nature of the detector: Most often it is the distance of the +# detector assembly. But there are irregular detectors. In this +# case the distance must be specified for each detector pixel. +# +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# +# +# +# +# +# This is the polar angle of the detector towards the previous +# component in the instrument; most often the sample. +# The usage depends on the +# nature of the detector. +# Most often it is the polar_angle of the detector assembly. +# But there are irregular detectors. +# In this +# case, the polar_angle must be specified for each detector pixel. +# +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# +# +# +# +# +# This is the azimuthal angle angle of the detector towards +# the previous component in the instrument; most often the sample. +# The usage depends on the +# nature of the detector. +# Most often it is the azimuthal_angle of the detector assembly. +# But there are irregular detectors. +# In this +# case, the azimuthal_angle must be specified for each detector pixel. +# +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# +# +# +# +# +# name/manufacturer/model/etc. information +# +# +# +# +# Serial number for the detector +# +# +# +# +# Local name for the detector +# +# +# +# +# Position and orientation of detector +# +# +# +# +# Solid angle subtended by the detector at the sample +# +# +# +# +# +# +# +# +# Size of each detector pixel. If it is scalar all pixels are the same size. +# +# +# +# +# +# +# +# +# Size of each detector pixel. If it is scalar all pixels are the same size +# +# +# +# +# +# +# +# +# Detector dead time +# +# +# +# +# +# +# +# +# +# Detector gas pressure +# +# +# +# +# +# +# +# +# maximum drift space dimension +# +# +# +# +# Crate number of detector +# +# +# +# +# +# +# +# Equivalent local term +# +# +# +# +# +# Slot number of detector +# +# +# +# +# +# +# +# Equivalent local term +# +# +# +# +# +# Input number of detector +# +# +# +# +# +# +# +# Equivalent local term +# +# +# +# +# +# Description of type such as He3 gas cylinder, He3 PSD, scintillator, +# fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, +# CMOS, ... +# +# +# +# +# Spectral efficiency of detector with respect to e.g. wavelength +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# efficiency of the detector +# +# +# +# +# +# +# +# +# +# This field can be two things: +# +# 1. For a pixel detector it provides the nominal wavelength +# for which the detector has been calibrated. +# +# 2. For other detectors this field has to be seen together with +# the efficiency field above. +# For some detectors, the efficiency is wavelength dependent. +# Thus this field provides the wavelength axis for the efficiency field. +# In this use case, the efficiency and wavelength arrays must +# have the same dimensionality. +# +# +# +# +# +# +# +# +# +# +# Real-time of the exposure (use this if exposure time varies for +# each array element, otherwise use ``count_time`` field). +# +# Most often there is a single real time value that is constant across +# an entire image frame. In such cases, only a 1-D array is needed. +# But there are detectors in which the real time +# changes per pixel. In that case, more than one dimension is needed. Therefore +# the rank of this field should be less than or equal to (detector rank + 1). +# +# +# +# +# +# +# +# +# +# start time for each frame, with the ``start`` attribute as absolute reference +# +# +# +# +# +# +# +# +# stop time for each frame, with the ``start`` attribute as absolute reference +# +# +# +# +# +# +# +# +# date of last calibration (geometry and/or efficiency) measurements +# +# +# +# +# summary of conversion of array data to pixels (e.g. polynomial +# approximations) and location of details of the calibrations +# +# +# +# +# How the detector is represented +# +# +# +# +# +# +# +# +# +# Elapsed actual counting time +# +# +# +# +# +# +# +# +# Use this group to provide other data related to this NXdetector group. +# +# +# +# +# In order to properly sort the order of the images taken in (for +# example) a tomography experiment, a sequence number is stored with each +# image. +# +# +# +# +# +# +# +# This is the x position where the direct beam would hit the detector. +# This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels +# as documented by the units attribute. +# +# +# +# +# This is the y position where the direct beam would hit the detector. +# This is a length and can be outside of the actual +# detector. The length can be in physical units or pixels +# as documented by the units attribute. +# +# +# +# +# This is the start number of the first frame of a scan. In protein crystallography measurements one +# often scans a couple of frames on a give sample, then does something else, +# then returns to the same sample and scans some more frames. Each time with +# a new data file. This number helps concatenating such measurements. +# +# +# +# +# The diameter of a cylindrical detector +# +# +# +# +# The acquisition mode of the detector. +# +# +# +# +# +# +# +# +# +# +# +# +# True when the angular calibration has been applied in the +# electronics, false otherwise. +# +# +# +# +# Angular calibration data. +# +# +# +# +# +# +# +# +# True when the flat field correction has been applied in the +# electronics, false otherwise. +# +# +# +# +# Flat field correction data. +# +# +# +# +# +# +# +# +# Errors of the flat field correction data. +# The form flatfield_error is deprecated. +# +# +# +# +# +# +# +# +# True when the pixel mask correction has been applied in the +# electronics, false otherwise. +# +# +# +# +# The 32-bit pixel mask for the detector. Can be either one mask +# for the whole dataset (i.e. an array with indices i, j) or +# each frame can have its own mask (in which case it would be +# an array with indices np, i, j). +# +# Contains a bit field for each pixel to signal dead, +# blind or high or otherwise unwanted or undesirable pixels. +# They have the following meaning: +# +# .. can't make a table here, a bullet list will have to do for now +# +# * bit 0: gap (pixel with no sensor) +# * bit 1: dead +# * bit 2: under responding +# * bit 3: over responding +# * bit 4: noisy +# * bit 5: -undefined- +# * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) +# * bit 7: -undefined- +# * bit 8: user defined mask (e.g. around beamstop) +# * bits 9-30: -undefined- +# * bit 31: virtual pixel (corner pixel with interpolated value) +# +# Normal data analysis software would +# not take pixels into account +# when a bit in (mask & 0x0000FFFF) is +# set. Tag bit in the upper +# two bytes would indicate special pixel +# properties that normally +# would not be a sole reason to reject the +# intensity value (unless +# lower bits are set. +# +# If the full bit depths is not required, providing a +# mask with fewer bits is permissible. +# +# If needed, additional pixel masks can be specified by +# including additional entries named pixel_mask_N, where +# N is an integer. For example, a general bad pixel mask +# could be specified in pixel_mask that indicates noisy +# and dead pixels, and an additional pixel mask from +# experiment-specific shadowing could be specified in +# pixel_mask_2. The cumulative mask is the bitwise OR +# of pixel_mask and any pixel_mask_N entries. +# +# +# +# +# +# +# +# +# This field allow to distinguish different types of exposure to the same detector "data" field. +# Some techniques require frequent (re-)calibration inbetween measuremnts and this way of +# recording the different measurements preserves the chronological order with is important for +# correct processing. +# +# This is used for example in tomography (`:ref:`NXtomo`) sample projections, +# dark and flat images, a magic number is recorded per frame. +# +# The key is as follows: +# +# * projection (sample) = 0 +# * flat field = 1 +# * dark field = 2 +# * invalid = 3 +# * background (no sample, but buffer where applicable) = 4 +# +# In cases where the data is of type :ref:`NXlog` this can also be an NXlog. +# +# +# +# +# +# +# +# Counting detectors usually are not able to measure all incoming particles, +# especially at higher count-rates. Count-rate correction is applied to +# account for these errors. +# +# True when count-rate correction has been applied, false otherwise. +# +# +# +# +# The countrate_correction_lookup_table defines the LUT used for count-rate +# correction. It maps a measured count :math:`c` to its corrected value +# :math:`countrate\_correction\_lookup\_table[c]`. +# +# :math:`m` denotes the length of the table. +# +# +# +# +# +# +# +# True when virtual pixel interpolation has been applied, false otherwise. +# +# When virtual pixel interpolation is applied, values of some pixels may +# contain interpolated values. For example, to account for space between +# readout chips on a module, physical pixels on edges and corners between +# chips may have larger sensor areas and counts may be distributed between +# their logical pixels. +# +# +# +# +# How many bits the electronics reads per pixel. +# With CCD's and single photon counting detectors, +# this must not align with traditional integer sizes. +# This can be 4, 8, 12, 14, 16, ... +# +# +# +# +# Time it takes to read the detector (typically milliseconds). +# This is important to know for time resolved experiments. +# +# +# +# +# Time it takes to start exposure after a trigger signal has been received. +# This is the reaction time of the detector firmware after receiving the trigger signal +# to when the detector starts to acquire the exposure, including any user set delay.. +# This is important to know for time resolved experiments. +# +# +# +# +# User-specified trigger delay. +# +# +# +# +# Time it takes to start exposure after a trigger signal has been received. +# This is the reaction time of the detector hardware after receiving the +# trigger signal to when the detector starts to acquire the exposure. +# It forms the lower boundary of the trigger_delay_time when the user +# does not request an additional delay. +# +# +# +# +# Time during which no new trigger signal can be accepted. +# Typically this is the +# trigger_delay_time + exposure_time + readout_time. +# This is important to know for time resolved experiments. +# +# +# +# +# This is time for each frame. This is exposure_time + readout time. +# +# +# +# +# +# +# +# The gain setting of the detector. This is a detector-specific value +# meant to document the gain setting of the detector during data +# collection, for detectors with multiple available gain settings. +# +# Examples of gain settings include: +# +# * ``standard`` +# * ``fast`` +# * ``auto`` +# * ``high`` +# * ``medium`` +# * ``low`` +# * ``mixed high to medium`` +# * ``mixed medium to low`` +# +# Developers are encouraged to use one of these terms, or to submit +# additional terms to add to the list. +# +# +# +# +# The value at which the detector goes into saturation. +# Especially common to CCD detectors, the data +# is known to be invalid above this value. +# +# For example, given a saturation_value and an underload_value, the valid +# pixels are those less than or equal to the saturation_value and greater +# than or equal to the underload_value. +# +# The precise type should match the type of the data. +# +# +# +# +# The lowest value at which pixels for this detector would be reasonably +# measured. The data is known to be invalid below this value. +# +# For example, given a saturation_value and an underload_value, the valid +# pixels are those less than or equal to the saturation_value and greater +# than or equal to the underload_value. +# +# The precise type should match the type of the data. +# +# +# +# +# CCD images are sometimes constructed by summing +# together multiple short exposures in the +# electronics. This reduces background etc. +# This is the number of short exposures used to sum +# images for an image. +# +# +# +# +# At times, radiation is not directly sensed by the detector. +# Rather, the detector might sense the output from some +# converter like a scintillator. +# This is the name of this converter material. +# +# +# +# +# At times, radiation is not directly sensed by the detector. +# Rather, the detector might sense the output from some +# converter like a scintillator. +# This is the thickness of this converter material. +# +# +# +# +# Single photon counter detectors can be adjusted +# for a certain energy range in which they +# work optimally. This is the energy setting for this. +# +# +# +# +# For use in special cases where the data in NXdetector +# is represented in several parts, each with a separate geometry. +# +# +# +# +# +# Shape description of each pixel. Use only if all pixels in the detector +# are of uniform shape. +# +# +# +# +# Shape description of each pixel. Use only if all pixels in the detector +# are of uniform shape and require being described by cylinders. +# +# +# +# +# +# +# Shape description of the whole detector. Use only if pixels in the +# detector are not of uniform shape. +# +# +# +# +# Shape description of the whole detector. Use only if pixels in the +# detector are not of uniform shape and require being described by cylinders. +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# Type of electron amplifier, MCP, channeltron, etc. +# +# +# +# +# Description of the detector type, DLD, Phosphor+CCD, CMOS. +# +# +# +# +# Voltage applied to detector. +# +# +# +# +# Voltage applied to the amplifier. +# +# +# +# +# The low voltage of the amplifier migh not be the ground. +# +# +# +# +# Size of each imaging sensor chip on the detector. +# +# +# +# +# Number of imaging sensor chips on the detector. +# +# +# +# +# Physical size of the pixels of the imaging chip on the detector. +# +# +# +# +# Number of raw active elements in each dimension. Important for swept scans. +# +# +# +# +# +# raw data output from the detector +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the detector is the center of the first pixel. +# In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXdetector_group.yaml b/base_classes/nyaml/NXdetector_group.yaml new file mode 100644 index 0000000000..c087d3b193 --- /dev/null +++ b/base_classes/nyaml/NXdetector_group.yaml @@ -0,0 +1,182 @@ +category: base +doc: | + Logical grouping of detectors. When used, describes a group of detectors. + + Each detector is represented as an NXdetector + with its own detector data array. Each detector data array + may be further decomposed into array sections by use of + NXdetector_module groups. Detectors can be grouped logically + together using NXdetector_group. Groups can be further grouped + hierarchically in a single NXdetector_group (for example, if + there are multiple detectors at an endstation or multiple + endstations at a facility). Alternatively, multiple + NXdetector_groups can be provided. + + The groups are defined hierarchically, with names given + in the group_names field, unique identifying indices given + in the field group_index, and the level in the hierarchy + given in the group_parent field. For example if an x-ray + detector group, DET, consists of four detectors in a + rectangular array:: + + DTL DTR + DLL DLR + + We could have:: + + group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] + group_index: [1, 2, 3, 4, 5] + group_parent: [-1, 1, 1, 1, 1] +type: group +NXdetector_group(NXobject): + group_names(NX_CHAR): + doc: | + An array of the names of the detectors given in NXdetector + groups or the names of hierarchical groupings of detectors + given as names of NXdetector_group groups or in + NXdetector_group group_names and group_parent fields as + having children. + group_index(NX_INT): + doc: | + An array of unique identifiers for detectors or groupings + of detectors. + + Each ID is a unique ID for the corresponding detector or group + named in the field group_names. The IDs are positive integers + starting with 1. + dimensions: + dim: [[1, i]] + group_parent(NX_INT): + doc: | + An array of the hierarchical levels of the parents of detectors + or groupings of detectors. + + A top-level grouping has parent level -1. + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['group_index'] + group_type(NX_INT): + doc: | + Code number for group type, e.g. bank=1, tube=2 etc. + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['group_index'] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 691ea608a29ca9acf2ea185458c9dc75285438032148ac1529e5ebcf0d96b4b7 +# +# +# +# +# +# Logical grouping of detectors. When used, describes a group of detectors. +# +# Each detector is represented as an NXdetector +# with its own detector data array. Each detector data array +# may be further decomposed into array sections by use of +# NXdetector_module groups. Detectors can be grouped logically +# together using NXdetector_group. Groups can be further grouped +# hierarchically in a single NXdetector_group (for example, if +# there are multiple detectors at an endstation or multiple +# endstations at a facility). Alternatively, multiple +# NXdetector_groups can be provided. +# +# The groups are defined hierarchically, with names given +# in the group_names field, unique identifying indices given +# in the field group_index, and the level in the hierarchy +# given in the group_parent field. For example if an x-ray +# detector group, DET, consists of four detectors in a +# rectangular array:: +# +# DTL DTR +# DLL DLR +# +# We could have:: +# +# group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] +# group_index: [1, 2, 3, 4, 5] +# group_parent: [-1, 1, 1, 1, 1] +# +# +# +# An array of the names of the detectors given in NXdetector +# groups or the names of hierarchical groupings of detectors +# given as names of NXdetector_group groups or in +# NXdetector_group group_names and group_parent fields as +# having children. +# +# +# +# +# An array of unique identifiers for detectors or groupings +# of detectors. +# +# Each ID is a unique ID for the corresponding detector or group +# named in the field group_names. The IDs are positive integers +# starting with 1. +# +# +# +# +# +# An array of the hierarchical levels of the parents of detectors +# or groupings of detectors. +# +# A top-level grouping has parent level -1. +# +# +# +# Code number for group type, e.g. bank=1, tube=2 etc. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXdetector_module.yaml b/base_classes/nyaml/NXdetector_module.yaml new file mode 100644 index 0000000000..d7e1c35f76 --- /dev/null +++ b/base_classes/nyaml/NXdetector_module.yaml @@ -0,0 +1,302 @@ +category: base +doc: | + Geometry and logical description of a detector module. When used, child group to NXdetector. + + Many detectors consist of multiple + smaller modules. Sometimes it is important to know the exact position of such + modules. + This is the purpose of this group. It is a child group to NXdetector. + + Note, the pixel size is given as values in the array fast_pixel_direction and slow_pixel_direction. +type: group +NXdetector_module(NXobject): + data_origin(NX_INT): + doc: | + A dimension-2 or dimension-3 field which gives the indices + of the origin of the hyperslab of data for this module in the + main area detector image in the parent NXdetector module. + + The data_origin is 0-based. + + The frame number dimension (np) is omitted. Thus the + data_origin field for a dimension-2 dataset with indices (np, i, j) + will be an array with indices (i, j), and for a dimension-3 + dataset with indices (np, i, j, k) will be an array with indices + (i, j, k). + + The :ref:`order ` of indices (i, j or i, j, k) is slow to fast. + data_size(NX_INT): + doc: | + Two or three values for the size of the module in pixels in + each direction. Dimensionality and order of indices is the + same as for data_origin. + module_offset(NX_NUMBER): + unit: NX_LENGTH + doc: | + Offset of the module in regards to the origin of the detector in an + arbitrary direction. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + doc: | + Three values that define the axis for this transformation + \@offset: + type: NX_NUMBER + doc: | + A fixed offset applied before the transformation (three vector components). + \@offset_units: + type: NX_CHAR + doc: | + Units of the offset. + \@depends_on: + type: NX_CHAR + doc: | + Points to the path of the next element in the geometry chain. + fast_pixel_direction(NX_NUMBER): + unit: NX_LENGTH + doc: | + Values along the direction of :ref:`fastest varying ` :index:`pixel direction`. Each value in this + array is the size of a pixel in the units specified. Alternatively, if only one + value is given, all pixels in this direction have the same value. The direction + itself is given through the vector attribute. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + doc: | + Three values that define the axis for this transformation + \@offset: + type: NX_NUMBER + doc: | + A fixed offset applied before the transformation (three vector components). + \@offset_units: + type: NX_CHAR + doc: | + Units of the offset. + \@depends_on: + type: NX_CHAR + doc: | + Points to the path of the next element in the geometry chain. + slow_pixel_direction(NX_NUMBER): + unit: NX_LENGTH + doc: | + Values along the direction of :ref:`slowest varying` :index:`pixel direction`. Each value in this + array is the size of a pixel in the units specified. Alternatively, if only one + value is given, all pixels in this direction have the same value. The direction + itself is given through the vector attribute. + \@transformation_type: + enumeration: [translation] + \@vector: + type: NX_NUMBER + doc: | + Three values that define the axis for this transformation + \@offset: + type: NX_NUMBER + doc: | + A fixed offset applied before the transformation (three vector components). + \@offset_units: + type: NX_CHAR + doc: | + Units of the offset. + \@depends_on: + type: NX_CHAR + doc: | + Points to the path of the next element in the geometry chain. + depends_on(NX_CHAR): + doc: | + Points to the start of the dependency chain for this module. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 648bcf7b5b6f0a233d30dfbea9f75968750c251551912aa642fa2172e8d6413a +# +# +# +# +# +# Geometry and logical description of a detector module. When used, child group to NXdetector. +# +# Many detectors consist of multiple +# smaller modules. Sometimes it is important to know the exact position of such +# modules. +# This is the purpose of this group. It is a child group to NXdetector. +# +# Note, the pixel size is given as values in the array fast_pixel_direction and slow_pixel_direction. +# +# +# +# A dimension-2 or dimension-3 field which gives the indices +# of the origin of the hyperslab of data for this module in the +# main area detector image in the parent NXdetector module. +# +# The data_origin is 0-based. +# +# The frame number dimension (np) is omitted. Thus the +# data_origin field for a dimension-2 dataset with indices (np, i, j) +# will be an array with indices (i, j), and for a dimension-3 +# dataset with indices (np, i, j, k) will be an array with indices +# (i, j, k). +# +# The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j or i, j, k) is slow to fast. +# +# +# +# +# Two or three values for the size of the module in pixels in +# each direction. Dimensionality and order of indices is the +# same as for data_origin. +# +# +# +# +# Offset of the module in regards to the origin of the detector in an +# arbitrary direction. +# +# +# +# +# +# +# +# +# Three values that define the axis for this transformation +# +# +# +# +# A fixed offset applied before the transformation (three vector components). +# +# +# +# +# Units of the offset. +# +# +# +# +# Points to the path of the next element in the geometry chain. +# +# +# +# +# +# Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` :index:`pixel direction<dimension; fastest varying>`. Each value in this +# array is the size of a pixel in the units specified. Alternatively, if only one +# value is given, all pixels in this direction have the same value. The direction +# itself is given through the vector attribute. +# +# +# +# +# +# +# +# +# Three values that define the axis for this transformation +# +# +# +# +# A fixed offset applied before the transformation (three vector components). +# +# +# +# +# Units of the offset. +# +# +# +# +# Points to the path of the next element in the geometry chain. +# +# +# +# +# +# Values along the direction of :ref:`slowest varying<Design-ArrayStorageOrder>` :index:`pixel direction<dimension; slowest varying>`. Each value in this +# array is the size of a pixel in the units specified. Alternatively, if only one +# value is given, all pixels in this direction have the same value. The direction +# itself is given through the vector attribute. +# +# +# +# +# +# +# +# +# Three values that define the axis for this transformation +# +# +# +# +# A fixed offset applied before the transformation (three vector components). +# +# +# +# +# Units of the offset. +# +# +# +# +# Points to the path of the next element in the geometry chain. +# +# +# +# +# +# Points to the start of the dependency chain for this module. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXdisk_chopper.yaml b/base_classes/nyaml/NXdisk_chopper.yaml new file mode 100644 index 0000000000..9d7e271d6a --- /dev/null +++ b/base_classes/nyaml/NXdisk_chopper.yaml @@ -0,0 +1,322 @@ +category: base +doc: | + A device blocking the beam in a temporal periodic pattern. + + A disk which blocks the beam but has one or more slits to periodically + let neutrons through as the disk rotates. Often used in pairs, one + NXdisk_chopper should be defined for each disk. + + The rotation of the disk is commonly monitored by recording a timestamp for + each full rotation of disk, by having a sensor in the stationary disk housing + sensing when it is aligned with a feature (such as a magnet) on the disk. + We refer to this below as the "top-dead-center signal". + + Angles and positive rotation speeds are measured in an anticlockwise + direction when facing away from the source. +symbols: + doc: | + This symbol will be used below to coordinate datasets with the same shape. + n: | + Number of slits in the disk +type: group +NXdisk_chopper(NXobject): + type: + doc: | + Type of the disk-chopper: only one from the enumerated list (match text exactly) + enumeration: [Chopper type single, contra_rotating_pair, synchro_pair] + rotation_speed(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Chopper rotation speed. Positive for anticlockwise rotation when + facing away from the source, negative otherwise. + slits(NX_INT): + doc: | + Number of slits + slit_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angular opening + pair_separation(NX_FLOAT): + unit: NX_LENGTH + doc: | + Disk spacing in direction of beam + slit_edges(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angle of each edge of every slit from the position of the + top-dead-center timestamp sensor, anticlockwise when facing + away from the source. + The first edge must be the opening edge of a slit, thus the last edge + may have an angle greater than 360 degrees. + dimensions: + dim: [[1, 2n]] + top_dead_center(NX_NUMBER): + unit: NX_TIME + doc: | + Timestamps of the top-dead-center signal. The times are relative + to the "start" attribute and in the units specified in the "units" + attribute. Please note that absolute + timestamps under unix are relative to ``1970-01-01T00:00:00.0Z``. + \@start: + type: NX_DATE_TIME + beam_position(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angular separation of the center of the beam and the + top-dead-center timestamp sensor, anticlockwise when facing + away from the source. + radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + Radius of the disk + slit_height(NX_FLOAT): + unit: NX_LENGTH + doc: | + Total slit height + phase(NX_FLOAT): + unit: NX_ANGLE + doc: | + Chopper phase angle + delay(NX_NUMBER): + unit: NX_TIME + doc: | + Time difference between timing system t0 and chopper driving clock signal + ratio(NX_INT): + doc: | + Pulse reduction factor of this chopper in relation to other + choppers/fastest pulse in the instrument + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Effective distance to the origin. + Note, it is recommended to use NXtransformations instead. + wavelength_range(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Low and high values of wavelength range transmitted + dimensions: + dim: [[1, 2]] + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the chopper and NXoff_geometry to describe its shape instead + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference plane of the disk chopper includes the surface of the spinning disk which faces + the source. The reference point in the x and y axis is the point on this surface which is the + centre of the axle which the disk is spinning around. The reference plane is orthogonal to + the z axis and its position is the reference point on that axis. + + Note: This reference point in almost all practical cases is not where the beam passes though. + + .. image:: disk_chopper/disk_chopper.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8746243b86eb8172d6bdcd6ae4e98f815d918d58349a17d67abc02d5af5214f8 +# +# +# +# +# +# +# This symbol will be used below to coordinate datasets with the same shape. +# Number of slits in the disk +# +# +# +# A device blocking the beam in a temporal periodic pattern. +# +# A disk which blocks the beam but has one or more slits to periodically +# let neutrons through as the disk rotates. Often used in pairs, one +# NXdisk_chopper should be defined for each disk. +# +# The rotation of the disk is commonly monitored by recording a timestamp for +# each full rotation of disk, by having a sensor in the stationary disk housing +# sensing when it is aligned with a feature (such as a magnet) on the disk. +# We refer to this below as the "top-dead-center signal". +# +# Angles and positive rotation speeds are measured in an anticlockwise +# direction when facing away from the source. +# +# +# +# Type of the disk-chopper: only one from the enumerated list (match text exactly) +# +# +# +# +# +# +# +# +# Chopper rotation speed. Positive for anticlockwise rotation when +# facing away from the source, negative otherwise. +# +# +# +# Number of slits +# +# +# Angular opening +# +# +# Disk spacing in direction of beam +# +# +# +# Angle of each edge of every slit from the position of the +# top-dead-center timestamp sensor, anticlockwise when facing +# away from the source. +# The first edge must be the opening edge of a slit, thus the last edge +# may have an angle greater than 360 degrees. +# +# +# +# +# +# Timestamps of the top-dead-center signal. The times are relative +# to the "start" attribute and in the units specified in the "units" +# attribute. Please note that absolute +# timestamps under unix are relative to ``1970-01-01T00:00:00.0Z``. +# +# +# +# +# +# Angular separation of the center of the beam and the +# top-dead-center timestamp sensor, anticlockwise when facing +# away from the source. +# +# +# +# Radius of the disk +# +# +# Total slit height +# +# +# Chopper phase angle +# +# +# +# Time difference between timing system t0 and chopper driving clock signal +# +# +# +# +# Pulse reduction factor of this chopper in relation to other +# choppers/fastest pulse in the instrument +# +# +# +# +# Effective distance to the origin. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# Low and high values of wavelength range transmitted +# +# +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference plane of the disk chopper includes the surface of the spinning disk which faces +# the source. The reference point in the x and y axis is the point on this surface which is the +# centre of the axle which the disk is spinning around. The reference plane is orthogonal to +# the z axis and its position is the reference point on that axis. +# +# Note: This reference point in almost all practical cases is not where the beam passes though. +# +# .. image:: disk_chopper/disk_chopper.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXentry.yaml b/base_classes/nyaml/NXentry.yaml new file mode 100644 index 0000000000..a1275a308b --- /dev/null +++ b/base_classes/nyaml/NXentry.yaml @@ -0,0 +1,521 @@ +category: base +doc: | + (**required**) :ref:`NXentry` describes the measurement. + + The top-level NeXus group which contains all the data and associated + information that comprise a single measurement. + It is mandatory that there is at least one + group of this type in the NeXus file. +type: group +NXentry(NXobject): + \@default: + doc: | + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXdata` group contains the data + to be shown by default. + It is used to resolve ambiguity when + one :ref:`NXdata` group exists. + The value :ref:`names ` a child group. If that group + itself has a ``default`` attribute, continue this chain until an + :ref:`NXdata` group is reached. + + For more information about how NeXus identifies the default + plottable data, see the + :ref:`Find Plottable Data, v3 ` + section. + (NXdata): + doc: | + The data group + + .. note:: Before the NIAC2016 meeting [#]_, at least one + :ref:`NXdata` group was required in each :ref:`NXentry` group. + At the NIAC2016 meeting, it was decided to make :ref:`NXdata` + an optional group in :ref:`NXentry` groups for data files that + do not use an application definition. + It is recommended strongly that all NeXus data files provide + a NXdata group. + It is permissable to omit the NXdata group only when + defining the default plot is not practical or possible + from the available data. + + For example, neutron event data may not have anything that + makes a useful plot without extensive processing. + + Certain application definitions override this decision and + require an :ref:`NXdata` group + in the :ref:`NXentry` group. The ``minOccurs=0`` attribute + in the application definition will indicate the + :ref:`NXdata` group + is optional, otherwise, it is required. + + .. [#] NIAC2016: + https://www.nexusformat.org/NIAC2016.html, + https://github.com/nexusformat/NIAC/issues/16 + \@IDF_Version: + + # as ratified at NIAC2010 + doc: | + ISIS Muon IDF_Version + title: + doc: | + Extended title for entry + experiment_identifier: + doc: | + Unique identifier for the experiment, + defined by the facility, + possibly linked to the proposals + experiment_description: + doc: | + Brief summary of the experiment, including key objectives. + (NXnote)experiment_documentation: + doc: | + Description of the full experiment (document in pdf, latex, ...) + collection_identifier: + doc: | + User or Data Acquisition defined group of NeXus files or NXentry + collection_description: + doc: | + Brief summary of the collection, including grouping criteria. + entry_identifier: + doc: | + unique identifier for the measurement, defined by the facility. + entry_identifier_uuid: + doc: | + UUID identifier for the measurement. + \@version: + doc: | + Version of UUID used + features: + doc: | + Reserved for future use by NIAC. + + See https://github.com/nexusformat/definitions/issues/382 + definition: + doc: | + (alternate use: see same field in :ref:`NXsubentry` for preferred) + + Official NeXus NXDL schema to which this entry conforms which must be + the name of the NXDL file (case sensitive without the file extension) + that the NXDL schema is defined in. + + For example the ``definition`` field for a file that conformed to the + *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. + + This field is provided so that :ref:`NXentry` can be the overlay position + in a NeXus data file for an application definition and its + set of groups, fields, and attributes. + + *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. + \@version: + doc: | + NXDL version number + \@URL: + doc: | + URL of NXDL file + definition_local: + deprecated: | + see same field in :ref:`NXsubentry` for preferred use + doc: | + Local NXDL schema extended from the entry + specified in the ``definition`` field. + This contains any locally-defined, + additional fields in the entry. + \@version: + doc: | + NXDL version number + \@URL: + doc: | + URL of NXDL file + start_time(NX_DATE_TIME): + doc: | + Starting time of measurement + end_time(NX_DATE_TIME): + doc: | + Ending time of measurement + duration(NX_INT): + unit: NX_TIME + doc: | + Duration of measurement + collection_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time transpired actually collecting data i.e. taking out time when collection was + suspended due to e.g. temperature out of range + run_cycle: + doc: | + Such as "2007-3". Some user facilities organize their beam time into run cycles. + program_name: + doc: | + Name of program used to generate this file + \@version: + doc: | + Program version number + \@configuration: + doc: | + configuration of the program + revision: + doc: | + Revision id of the file due to re-calibration, reprocessing, new analysis, new + instrument definition format, ... + \@comment: + pre_sample_flightpath(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the flightpath before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + notes(NXnote): + doc: | + Notes describing entry + thumbnail(NXnote): + doc: | + A small image that is representative of the entry. An example of this is a 640x480 + jpeg image automatically produced by a low resolution plot of the NXdata. + \@type: + doc: | + The mime type should be an ``image/*`` + + # This is not perfect. + # How do we set a default value for the type attribute? + enumeration: [image/*] + experiment_location: + doc: | + City and country where the experiment took place + experiment_start_date(NX_DATE_TIME): + doc: | + Start time of experimental run that includes the current + measurement, for example a beam time. + experiment_end_date(NX_DATE_TIME): + doc: | + End time of experimental run that includes the current + measurement, for example a beam time. + experiment_institution: + doc: | + Name of the institution hosting the facility + experiment_facility: + doc: | + Name of the experimental facility + experiment_laboratory: + doc: | + Name of the laboratory or beamline + (NXuser): + (NXsample): + (NXinstrument): + (NXcollection): + (NXmonitor): + (NXparameters): + (NXprocess): + (NXsubentry): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c174932eb1ad851dc9e15d607deb596334b909da162638734c332774c77b1c09 +# +# +# +# +# +# (**required**) :ref:`NXentry` describes the measurement. +# +# The top-level NeXus group which contains all the data and associated +# information that comprise a single measurement. +# It is mandatory that there is at least one +# group of this type in the NeXus file. +# +# +# +# .. index:: find the default plottable data +# .. index:: plotting +# .. index:: default attribute value +# +# Declares which :ref:`NXdata` group contains the data +# to be shown by default. +# It is used to resolve ambiguity when +# one :ref:`NXdata` group exists. +# The value :ref:`names <validItemName>` a child group. If that group +# itself has a ``default`` attribute, continue this chain until an +# :ref:`NXdata` group is reached. +# +# For more information about how NeXus identifies the default +# plottable data, see the +# :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` +# section. +# +# +# +# +# The data group +# +# .. note:: Before the NIAC2016 meeting [#]_, at least one +# :ref:`NXdata` group was required in each :ref:`NXentry` group. +# At the NIAC2016 meeting, it was decided to make :ref:`NXdata` +# an optional group in :ref:`NXentry` groups for data files that +# do not use an application definition. +# It is recommended strongly that all NeXus data files provide +# a NXdata group. +# It is permissable to omit the NXdata group only when +# defining the default plot is not practical or possible +# from the available data. +# +# For example, neutron event data may not have anything that +# makes a useful plot without extensive processing. +# +# Certain application definitions override this decision and +# require an :ref:`NXdata` group +# in the :ref:`NXentry` group. The ``minOccurs=0`` attribute +# in the application definition will indicate the +# :ref:`NXdata` group +# is optional, otherwise, it is required. +# +# .. [#] NIAC2016: +# https://www.nexusformat.org/NIAC2016.html, +# https://github.com/nexusformat/NIAC/issues/16 +# +# +# +# +# +# ISIS Muon IDF_Version +# +# +# +# +# Extended title for entry +# +# +# +# +# Unique identifier for the experiment, +# defined by the facility, +# possibly linked to the proposals +# +# +# +# +# Brief summary of the experiment, including key objectives. +# +# +# +# +# Description of the full experiment (document in pdf, latex, ...) +# +# +# +# +# User or Data Acquisition defined group of NeXus files or NXentry +# +# +# +# +# Brief summary of the collection, including grouping criteria. +# +# +# +# +# unique identifier for the measurement, defined by the facility. +# +# +# +# +# UUID identifier for the measurement. +# +# +# +# Version of UUID used +# +# +# +# +# +# Reserved for future use by NIAC. +# +# See https://github.com/nexusformat/definitions/issues/382 +# +# +# +# +# (alternate use: see same field in :ref:`NXsubentry` for preferred) +# +# Official NeXus NXDL schema to which this entry conforms which must be +# the name of the NXDL file (case sensitive without the file extension) +# that the NXDL schema is defined in. +# +# For example the ``definition`` field for a file that conformed to the +# *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. +# +# This field is provided so that :ref:`NXentry` can be the overlay position +# in a NeXus data file for an application definition and its +# set of groups, fields, and attributes. +# +# *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. +# +# +# +# NXDL version number +# +# +# +# +# URL of NXDL file +# +# +# +# +# +# Local NXDL schema extended from the entry +# specified in the ``definition`` field. +# This contains any locally-defined, +# additional fields in the entry. +# +# +# +# NXDL version number +# +# +# +# +# URL of NXDL file +# +# +# +# +# +# Starting time of measurement +# +# +# +# +# Ending time of measurement +# +# +# +# +# Duration of measurement +# +# +# +# +# Time transpired actually collecting data i.e. taking out time when collection was +# suspended due to e.g. temperature out of range +# +# +# +# +# Such as "2007-3". Some user facilities organize their beam time into run cycles. +# +# +# +# +# Name of program used to generate this file +# +# +# +# Program version number +# +# +# +# +# configuration of the program +# +# +# +# +# +# Revision id of the file due to re-calibration, reprocessing, new analysis, new +# instrument definition format, ... +# +# +# +# +# +# This is the flightpath before the sample position. This can be determined by a chopper, +# by the moderator or the source itself. In other words: it the distance to the component +# which gives the T0 signal to the detector electronics. If another component in the +# NXinstrument hierarchy provides this information, this should be a link. +# +# +# +# +# Notes describing entry +# +# +# +# +# A small image that is representative of the entry. An example of this is a 640x480 +# jpeg image automatically produced by a low resolution plot of the NXdata. +# +# +# +# The mime type should be an ``image/*`` +# +# +# +# +# +# +# +# +# +# City and country where the experiment took place +# +# +# +# +# Start time of experimental run that includes the current +# measurement, for example a beam time. +# +# +# +# +# End time of experimental run that includes the current +# measurement, for example a beam time. +# +# +# +# +# Name of the institution hosting the facility +# +# +# +# +# Name of the experimental facility +# +# +# +# +# Name of the laboratory or beamline +# +# +# +# +# +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXenvironment.yaml b/base_classes/nyaml/NXenvironment.yaml new file mode 100644 index 0000000000..92efc44ec0 --- /dev/null +++ b/base_classes/nyaml/NXenvironment.yaml @@ -0,0 +1,151 @@ +category: base +doc: | + Parameters for controlling external conditions +type: group +NXenvironment(NXobject): + name: + doc: | + Apparatus identification code/model number; e.g. OC100 011 + short_name: + doc: | + Alternative short name, perhaps for dashboard display like a present Seblock + name + type: + doc: | + Type of apparatus. This could be the SE codes in scheduling database; e.g. + OC/100 + description: + doc: | + Description of the apparatus; e.g. 100mm bore orange cryostat with Roots pump + program: + doc: | + Program controlling the apparatus; e.g. LabView VI name + position(NXgeometry): + doc: | + The position and orientation of the apparatus. + Note, it is recommended to use NXtransformations instead. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + (NXtransformations): + exists: ['min', '0'] + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + (NXnote): + doc: | + Additional information, LabView logs, digital photographs, etc + (NXactuator): + doc: | + Any actuator used to control the environment. This can be linked to an actuator + defined in an NXinstrument instance. + (NXsensor): + doc: | + Any sensor used to monitor the environment. This can be linked to a sensor + defined in an NXinstrument instance. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# edb4357785f3ad2e7c84849c787be220920b9eef3a18ee1c8d251327873c87b7 +# +# +# +# +# +# Parameters for controlling external conditions +# +# +# +# Apparatus identification code/model number; e.g. OC100 011 +# +# +# +# +# Alternative short name, perhaps for dashboard display like a present Seblock +# name +# +# +# +# +# Type of apparatus. This could be the SE codes in scheduling database; e.g. +# OC/100 +# +# +# +# +# Description of the apparatus; e.g. 100mm bore orange cryostat with Roots pump +# +# +# +# +# Program controlling the apparatus; e.g. LabView VI name +# +# +# +# +# The position and orientation of the apparatus. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# Additional information, LabView logs, digital photographs, etc +# +# +# +# +# Any actuator used to control the environment. This can be linked to an actuator +# defined in an NXinstrument instance. +# +# +# +# +# Any sensor used to monitor the environment. This can be linked to a sensor +# defined in an NXinstrument instance. +# +# +# diff --git a/base_classes/nyaml/NXevent_data.yaml b/base_classes/nyaml/NXevent_data.yaml new file mode 100644 index 0000000000..c75f0ee867 --- /dev/null +++ b/base_classes/nyaml/NXevent_data.yaml @@ -0,0 +1,220 @@ +category: base +doc: | + NXevent_data is a special group for storing data from neutron + detectors in event mode. In this mode, the detector electronics + emits a stream of detectorID, timestamp pairs. With detectorID + describing the detector element in which the neutron was detected + and timestamp the timestamp at which the neutron event was + detected. In NeXus detectorID maps to event_id, event_time_offset + to the timestamp. + + As this kind of data is common at pulsed neutron + sources, the timestamp is almost always relative to the start of a + neutron pulse. Thus the pulse timestamp is recorded too together + with an index in the event_id, event_time_offset pair at which data for + that pulse starts. At reactor source the same pulsed data effect + may be achieved through the use of choppers or in stroboscopic + measurement setups. + + In order to make random access to timestamped data + faster there is an optional array pair of + cue_timestamp_zero and cue_index. The cue_timestamp_zero will + contain courser timestamps then in the time array, say + every five minutes. The cue_index will then contain the + index into the event_id,event_time_offset pair of arrays for that + courser cue_timestamp_zero. +type: group +NXevent_data(NXobject): + event_time_offset(NX_NUMBER): + unit: NX_TIME_OF_FLIGHT + doc: | + A list of timestamps for each event as it comes in. + dimensions: + rank: 1 + dim: [[1, i]] + event_id(NX_INT): + unit: NX_DIMENSIONLESS + doc: | + There will be extra information in the NXdetector to convert + event_id to detector_number. + dimensions: + rank: 1 + dim: [[1, i]] + event_time_zero(NX_NUMBER): + unit: NX_TIME + doc: | + The time that each pulse started with respect to the offset + dimensions: + rank: 1 + dim: [[1, j]] + \@offset: + type: NX_DATE_TIME + doc: | + ISO8601 + event_index(NX_INT): + unit: NX_DIMENSIONLESS + doc: | + The index into the event_time_offset, event_id pair for + the pulse occurring at the matching entry in event_time_zero. + dimensions: + rank: 1 + dim: [[1, j]] + pulse_height(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + If voltages from the ends of the detector are read out this + is where they go. This list is for all events with information + to attach to a particular pulse height. The information to + attach to a particular pulse is located in events_per_pulse. + dimensions: + rank: 2 + + # i,k? + dim: [[1, i], [2, k]] + cue_timestamp_zero(NX_DATE_TIME): + unit: NX_TIME + doc: | + Timestamps matching the corresponding cue_index into the + event_id, event_time_offset pair. + \@start: + type: NX_DATE_TIME + cue_index(NX_INT): + doc: | + Index into the event_id, event_time_offset pair matching the corresponding + cue_timestamp. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8ed9dbd7316d38b106211e5be368886684addd89e347b28ec11e7e88d6ca88bb +# +# +# +# +# +# NXevent_data is a special group for storing data from neutron +# detectors in event mode. In this mode, the detector electronics +# emits a stream of detectorID, timestamp pairs. With detectorID +# describing the detector element in which the neutron was detected +# and timestamp the timestamp at which the neutron event was +# detected. In NeXus detectorID maps to event_id, event_time_offset +# to the timestamp. +# +# As this kind of data is common at pulsed neutron +# sources, the timestamp is almost always relative to the start of a +# neutron pulse. Thus the pulse timestamp is recorded too together +# with an index in the event_id, event_time_offset pair at which data for +# that pulse starts. At reactor source the same pulsed data effect +# may be achieved through the use of choppers or in stroboscopic +# measurement setups. +# +# In order to make random access to timestamped data +# faster there is an optional array pair of +# cue_timestamp_zero and cue_index. The cue_timestamp_zero will +# contain courser timestamps then in the time array, say +# every five minutes. The cue_index will then contain the +# index into the event_id,event_time_offset pair of arrays for that +# courser cue_timestamp_zero. +# +# +# +# A list of timestamps for each event as it comes in. +# +# +# +# +# +# There will be extra information in the NXdetector to convert +# event_id to detector_number. +# +# +# +# +# +# The time that each pulse started with respect to the offset +# +# +# +# ISO8601 +# +# +# +# +# The index into the event_time_offset, event_id pair for +# the pulse occurring at the matching entry in event_time_zero. +# +# +# +# +# +# If voltages from the ends of the detector are read out this +# is where they go. This list is for all events with information +# to attach to a particular pulse height. The information to +# attach to a particular pulse is located in events_per_pulse. +# +# +# +# +# +# +# +# +# Timestamps matching the corresponding cue_index into the +# event_id, event_time_offset pair. +# +# +# +# +# +# Index into the event_id, event_time_offset pair matching the corresponding +# cue_timestamp. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXfermi_chopper.yaml b/base_classes/nyaml/NXfermi_chopper.yaml new file mode 100644 index 0000000000..08073753d0 --- /dev/null +++ b/base_classes/nyaml/NXfermi_chopper.yaml @@ -0,0 +1,210 @@ +category: base +doc: | + A Fermi chopper, possibly with curved slits. +type: group +NXfermi_chopper(NXobject): + type: + doc: | + Fermi chopper type + rotation_speed(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + chopper rotation speed + radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + radius of chopper + slit(NX_FLOAT): + unit: NX_LENGTH + doc: | + width of an individual slit + r_slit(NX_FLOAT): + unit: NX_LENGTH + doc: | + radius of curvature of slits + number(NX_INT): + unit: NX_UNITLESS + doc: | + number of slits + height(NX_FLOAT): + unit: NX_LENGTH + doc: | + input beam height + width(NX_FLOAT): + unit: NX_LENGTH + doc: | + input beam width + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + distance. Note, it is recommended to use NXtransformations instead. + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + + # should have units of angstroms or nm or pm + doc: | + Wavelength transmitted by chopper + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy selected + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the chopper and NXoff_geometry to describe its shape instead + doc: | + geometry of the fermi chopper + absorbing_material: + doc: | + absorbing material + transmitting_material: + doc: | + transmitting material + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a fermi chopper. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2407282663e1772239751fbb10e88d002cc9382fce57cd6badbaeff0d0c2d7d6 +# +# +# +# +# A Fermi chopper, possibly with curved slits. +# +# Fermi chopper type +# +# +# chopper rotation speed +# +# +# radius of chopper +# +# +# width of an individual slit +# +# +# radius of curvature of slits +# +# +# number of slits +# +# +# input beam height +# +# +# input beam width +# +# +# distance. Note, it is recommended to use NXtransformations instead. +# +# +# +# Wavelength transmitted by chopper +# +# +# energy selected +# +# +# geometry of the fermi chopper +# +# +# absorbing material +# +# +# transmitting material +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a fermi chopper. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXfilter.yaml b/base_classes/nyaml/NXfilter.yaml new file mode 100644 index 0000000000..7eb6622a69 --- /dev/null +++ b/base_classes/nyaml/NXfilter.yaml @@ -0,0 +1,373 @@ +category: base +doc: | + For band pass beam filters. + + If uncertain whether to use :ref:`NXfilter` (band-pass filter) + or :ref:`NXattenuator` (reduces beam intensity), then use + :ref:`NXattenuator`. +type: group +NXfilter(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to filter the beamstop and NXoff_geometry to describe its shape instead + doc: | + Geometry of the filter + description: + doc: | + Composition of the filter. Chemical formula can be specified separately. + + This field was changed (2010-11-17) from an enumeration to + a string since common usage showed a wider variety of use + than a simple list. These are the items in the list at + the time of the change: Beryllium | Pyrolytic Graphite | + Graphite | Sapphire | Silicon | Supermirror. + status: + doc: | + position with respect to in or out of the beam (choice of only "in" or "out") + enumeration: + in: + doc: | + in the beam + out: + doc: | + out of the beam + transmission(NXdata): + doc: | + Wavelength transmission profile of filter + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + average/nominal filter temperature + temperature_log(NXlog): + doc: | + Linked temperature_log for the filter + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the filter + density(NX_NUMBER): + unit: NX_MASS_DENSITY + doc: | + mass density of the filter + chemical_formula: + + # copied from NXsample + doc: | + 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. + sensor_type(NXsensor): + doc: | + Sensor(s)used to monitor the filter temperature + unit_cell_a(NX_FLOAT): + unit: NX_LENGTH + doc: | + Unit cell lattice parameter: length of side a + unit_cell_b(NX_FLOAT): + unit: NX_LENGTH + doc: | + Unit cell lattice parameter: length of side b + unit_cell_c(NX_FLOAT): + unit: NX_LENGTH + doc: | + Unit cell lattice parameter: length of side c + unit_cell_alpha(NX_FLOAT): + unit: NX_ANGLE + doc: | + Unit cell lattice parameter: angle alpha + unit_cell_beta(NX_FLOAT): + unit: NX_ANGLE + doc: | + Unit cell lattice parameter: angle beta + unit_cell_gamma(NX_FLOAT): + unit: NX_ANGLE + doc: | + Unit cell lattice parameter: angle gamma + unit_cell_volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Unit cell + dimensions: + rank: 1 + dim: [[1, n_comp]] + orientation_matrix(NX_FLOAT): + doc: | + Orientation matrix of single crystal filter using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 3 + + # n_comp,3,3 + + # TODO n_comp is number of different compositions? + dim: [[1, n_comp], [2, 3], [3, 3]] + m_value(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + m value of supermirror filter + substrate_material: + doc: | + substrate material of supermirror filter + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + substrate thickness of supermirror filter + coating_material: + doc: | + coating material of supermirror filter + substrate_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + substrate roughness (RMS) of supermirror filter + coating_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + coating roughness (RMS) of supermirror filter + dimensions: + rank: 1 + dim: [[1, nsurf]] + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a filter. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d2cc3057e66871057ddf851fbe725f22606e3a84fa54746d87674d898b0eace0 +# +# +# +# +# +# For band pass beam filters. +# +# If uncertain whether to use :ref:`NXfilter` (band-pass filter) +# or :ref:`NXattenuator` (reduces beam intensity), then use +# :ref:`NXattenuator`. +# +# +# Geometry of the filter +# +# +# +# Composition of the filter. Chemical formula can be specified separately. +# +# This field was changed (2010-11-17) from an enumeration to +# a string since common usage showed a wider variety of use +# than a simple list. These are the items in the list at +# the time of the change: Beryllium | Pyrolytic Graphite | +# Graphite | Sapphire | Silicon | Supermirror. +# +# +# +# position with respect to in or out of the beam (choice of only "in" or "out") +# +# in the beam +# out of the beam +# +# +# +# Wavelength transmission profile of filter +# +# +# average/nominal filter temperature +# +# +# Linked temperature_log for the filter +# +# +# Thickness of the filter +# +# +# mass density of the filter +# +# +# +# +# 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. +# +# +# +# Sensor(s)used to monitor the filter temperature +# +# +# Unit cell lattice parameter: length of side a +# +# +# Unit cell lattice parameter: length of side b +# +# +# Unit cell lattice parameter: length of side c +# +# +# Unit cell lattice parameter: angle alpha +# +# +# Unit cell lattice parameter: angle beta +# +# +# Unit cell lattice parameter: angle gamma +# +# +# Unit cell +# +# +# +# +# Orientation matrix of single crystal filter using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# +# m value of supermirror filter +# +# +# substrate material of supermirror filter +# +# +# substrate thickness of supermirror filter +# +# +# coating material of supermirror filter +# +# +# substrate roughness (RMS) of supermirror filter +# +# +# coating roughness (RMS) of supermirror filter +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a filter. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXflipper.yaml b/base_classes/nyaml/NXflipper.yaml new file mode 100644 index 0000000000..ea20d1a8d4 --- /dev/null +++ b/base_classes/nyaml/NXflipper.yaml @@ -0,0 +1,159 @@ +category: base +doc: | + A spin flipper. +type: group +NXflipper(NXobject): + type: + enumeration: [coil, current-sheet] + flip_turns(NX_FLOAT): + unit: NX_PER_LENGTH + doc: | + Linear density of turns (such as number of turns/cm) in flipping field coils + comp_turns(NX_FLOAT): + unit: NX_PER_LENGTH + doc: | + Linear density of turns (such as number of turns/cm) in compensating field coils + guide_turns(NX_FLOAT): + unit: NX_PER_LENGTH + doc: | + Linear density of turns (such as number of turns/cm) in guide field coils + flip_current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Flipping field coil current in "on" state" + comp_current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Compensating field coil current in "on" state" + guide_current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Guide field coil current in "on" state + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + thickness along path of neutron travel + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a spin flipper. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 62c4f526c364c8ede653c3a19e5aed1dae3a51685eb7137a46a3d906c1cc60bf +# +# +# +# +# A spin flipper. +# +# +# +# +# +# +# +# Linear density of turns (such as number of turns/cm) in flipping field coils +# +# +# Linear density of turns (such as number of turns/cm) in compensating field coils +# +# +# Linear density of turns (such as number of turns/cm) in guide field coils +# +# +# Flipping field coil current in "on" state" +# +# +# Compensating field coil current in "on" state" +# +# +# Guide field coil current in "on" state +# +# +# thickness along path of neutron travel +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a spin flipper. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXfresnel_zone_plate.yaml b/base_classes/nyaml/NXfresnel_zone_plate.yaml new file mode 100644 index 0000000000..eea7e942f1 --- /dev/null +++ b/base_classes/nyaml/NXfresnel_zone_plate.yaml @@ -0,0 +1,178 @@ +category: base +doc: | + A fresnel zone plate +type: group +NXfresnel_zone_plate(NXobject): + focus_parameters(NX_FLOAT): + doc: | + list of polynomial coefficients describing the focal length of the zone plate, in increasing powers of photon energy, + that describes the focal length of the zone plate (in microns) at an X-ray photon energy (in electron volts). + dimensions: + rank: 1 + dim: [] + outer_diameter(NX_FLOAT): + unit: NX_LENGTH + outermost_zone_width(NX_FLOAT): + unit: NX_LENGTH + central_stop_diameter(NX_FLOAT): + unit: NX_LENGTH + fabrication: + doc: | + how the zone plate was manufactured + enumeration: [etched, plated, zone doubled, other] + zone_height(NX_FLOAT): + unit: NX_LENGTH + zone_material: + doc: | + Material of the zones themselves + zone_support_material: + doc: | + Material present between the zones. This is usually only present for the "zone doubled" fabrication process + central_stop_material: + central_stop_thickness(NX_FLOAT): + unit: NX_LENGTH + mask_thickness(NX_FLOAT): + unit: NX_LENGTH + mask_material: + doc: | + If no mask is present, set mask_thickness to 0 and omit the mask_material field + support_membrane_material: + support_membrane_thickness(NX_FLOAT): + unit: NX_LENGTH + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a fresnel zone plate. + (NXtransformations): + doc: | + "Engineering" position of the fresnel zone plate + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 53901ea435d088aedb91b2f3fa70e315e6269a25bb0b871d938a2cfd0c5a82ec +# +# +# +# +# +# A fresnel zone plate +# +# +# list of polynomial coefficients describing the focal length of the zone plate, in increasing powers of photon energy, +# that describes the focal length of the zone plate (in microns) at an X-ray photon energy (in electron volts). +# +# +# +# +# +# +# +# +# how the zone plate was manufactured +# +# +# +# +# +# +# +# +# +# Material of the zones themselves +# +# +# Material present between the zones. This is usually only present for the "zone doubled" fabrication process +# +# +# +# +# +# If no mask is present, set mask_thickness to 0 and omit the mask_material field +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a fresnel zone plate. +# +# +# +# +# +# "Engineering" position of the fresnel zone plate +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXgeometry.yaml b/base_classes/nyaml/NXgeometry.yaml new file mode 100644 index 0000000000..5c1dfb277f --- /dev/null +++ b/base_classes/nyaml/NXgeometry.yaml @@ -0,0 +1,128 @@ +category: base +doc: | + legacy class - recommend to use :ref:`NXtransformations` now + + It is recommended that instances of :ref:`NXgeometry` be converted to + use :ref:`NXtransformations`. + + This is the description for a general position of a component. + It is recommended to name an instance of :ref:`NXgeometry` as "geometry" + to aid in the use of the definition in simulation codes such as McStas. + Also, in HDF, linked items must share the same name. + However, it might not be possible or practical in all situations. +type: group +deprecated: as decided at 2014 NIAC meeting, convert to use :ref:`NXtransformations` +NXgeometry(NXobject): + (NXshape): + doc: | + shape/size information of component + (NXtranslation): + doc: | + translation of component + (NXorientation): + doc: | + orientation of component + description: + doc: | + Optional description/label. Probably only present if we are + an additional reference point for components rather than the + location of a real component. + component_index(NX_INT): + doc: | + Position of the component along the beam path. The sample is at 0, components upstream + have negative component_index, components downstream have positive + component_index. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d7d64aa78775fa8184154f30651e5def6856d4f76f490ba44df0f5a37463b670 +# +# +# +# +# +# legacy class - recommend to use :ref:`NXtransformations` now +# +# It is recommended that instances of :ref:`NXgeometry` be converted to +# use :ref:`NXtransformations`. +# +# This is the description for a general position of a component. +# It is recommended to name an instance of :ref:`NXgeometry` as "geometry" +# to aid in the use of the definition in simulation codes such as McStas. +# Also, in HDF, linked items must share the same name. +# However, it might not be possible or practical in all situations. +# +# +# shape/size information of component +# +# +# translation of component +# +# +# orientation of component +# +# +# +# Optional description/label. Probably only present if we are +# an additional reference point for components rather than the +# location of a real component. +# +# +# +# +# Position of the component along the beam path. The sample is at 0, components upstream +# have negative component_index, components downstream have positive +# component_index. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXgrating.yaml b/base_classes/nyaml/NXgrating.yaml new file mode 100644 index 0000000000..9603971d7c --- /dev/null +++ b/base_classes/nyaml/NXgrating.yaml @@ -0,0 +1,202 @@ +category: base +doc: | + A diffraction grating, as could be used in a soft X-ray monochromator +type: group +NXgrating(NXobject): + angles(NX_FLOAT): + unit: NX_ANGLE + doc: | + Blaze or trapezoidal angles, with the angle of the upstream facing edge listed first. Blazed gratings can be identified by the low value of the first-listed angle. + dimensions: + rank: 1 + dim: [[1, 2]] + period(NX_FLOAT): + unit: NX_LENGTH + doc: | + List of polynomial coefficients describing the spatial separation of lines/grooves as a function of position along the grating, in increasing powers of position. Gratings which do not have variable line spacing will only have a single coefficient (constant). + dimensions: + rank: 1 + dim: [] + duty_cycle(NX_FLOAT): + unit: NX_UNITLESS + depth(NX_FLOAT): + unit: NX_LENGTH + diffraction_order(NX_INT): + unit: NX_UNITLESS + deflection_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angle between the incident beam and the utilised outgoing beam. + interior_atmosphere: + enumeration: [vacuum, helium, argon] + substrate_material: + doc: | + substrate_density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + coating_material: + substrate_roughness(NX_FLOAT): + unit: NX_LENGTH + coating_roughness(NX_FLOAT): + unit: NX_LENGTH + layer_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + An array describing the thickness of each layer + (NXshape)shape: + deprecated: Use NXoff_geometry to describe the shape of grating + doc: | + A NXshape group describing the shape of the mirror + figure_data(NXdata): + doc: | + Numerical description of the surface figure of the mirror. + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a bending grating. + (NXtransformations): + doc: | + "Engineering" position of the grating + Transformations used by this component to define its position and orientation. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e3c616b8b6027b862a3946ab63674969147bd291cefbad316bfb6fdb3477305e +# +# +# +# +# +# A diffraction grating, as could be used in a soft X-ray monochromator +# +# Blaze or trapezoidal angles, with the angle of the upstream facing edge listed first. Blazed gratings can be identified by the low value of the first-listed angle. +# +# +# +# +# +# List of polynomial coefficients describing the spatial separation of lines/grooves as a function of position along the grating, in increasing powers of position. Gratings which do not have variable line spacing will only have a single coefficient (constant). +# +# +# +# +# +# +# Angle between the incident beam and the utilised outgoing beam. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# An array describing the thickness of each layer +# +# +# A NXshape group describing the shape of the mirror +# +# +# Numerical description of the surface figure of the mirror. +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a bending grating. +# +# +# +# +# +# "Engineering" position of the grating +# Transformations used by this component to define its position and orientation. +# +# +# diff --git a/base_classes/nyaml/NXguide.yaml b/base_classes/nyaml/NXguide.yaml new file mode 100644 index 0000000000..fd2f276229 --- /dev/null +++ b/base_classes/nyaml/NXguide.yaml @@ -0,0 +1,416 @@ +category: base +doc: | + A neutron optical element to direct the path of the beam. + + :ref:`NXguide` is used by neutron instruments to describe + a guide consists of several mirrors building a shape through which + neutrons can be guided or directed. The simplest such form is box shaped + although elliptical guides are gaining in popularity. + The individual parts of a guide usually have common characteristics + but there are cases where they are different. + For example, a neutron guide might consist of 2 or 4 coated walls or + a supermirror bender with multiple, coated vanes. + + To describe polarizing supermirrors such as used in neutron reflection, + it may be necessary to revise this definition of :ref:`NXguide` + to include :ref:`NXpolarizer` and/or :ref:`NXmirror`. + + When even greater complexity exists in the definition of what + constitutes a *guide*, it has been suggested that :ref:`NXguide` + be redefined as a :ref:`NXcollection` of :ref:`NXmirror` each + having their own :ref:`NXgeometry` describing their location(s). + + For the more general case when describing mirrors, consider using + :ref:`NXmirror`. + + NOTE: The NeXus International Advisory Committee welcomes + comments for revision and improvement of + this definition of :ref:`NXguide`. +symbols: + nsurf: | + number of reflecting surfaces + nwl: | + number of wavelengths +type: group +NXguide(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the guid and NXoff_geometry to describe its shape instead + doc: | + TODO: Explain what this NXgeometry group means. What is intended here? + description: + doc: | + A description of this particular instance of ``NXguide``. + incident_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + TODO: documentation needed + (NXdata)reflectivity: + doc: | + Reflectivity as function of reflecting surface and wavelength + \@signal: + enumeration: [data] + \@axes: + enumeration: [surface wavelength] + \@surface_indices: + enumeration: [0] + \@wavelength_indices: + enumeration: [1] + data(NX_NUMBER): + doc: | + reflectivity of each surface as a function of wavelength + dimensions: + rank: 2 + + # was [nsurf,i] + dim: [[1, nsurf], [2, nwl]] + surface(NX_NUMBER): + unit: NX_ANY + doc: | + List of surfaces. Probably best to use index + numbers but the specification is very loose. + dimensions: + rank: 1 + dim: [[1, nsurf]] + wavelength(NX_NUMBER): + unit: NX_WAVELENGTH + doc: | + wavelengths at which reflectivity was measured + dimensions: + rank: 1 + dim: [[1, nwl]] + bend_angle_x(NX_FLOAT): + unit: NX_ANGLE + doc: | + TODO: documentation needed + bend_angle_y(NX_FLOAT): + unit: NX_ANGLE + doc: | + TODO: documentation needed + interior_atmosphere: + doc: | + + # TODO + enumeration: [vacuum, helium, argon] + external_material: + doc: | + external material outside substrate + m_value(NX_FLOAT): + doc: | + The ``m`` value for a supermirror, which defines the supermirror + regime in multiples of the critical angle of Nickel. + dimensions: + rank: 1 + dim: [[1, nsurf]] + substrate_material(NX_FLOAT): + doc: | + TODO: documentation needed + + # Why is this field a "float"? + dimensions: + rank: 1 + dim: [[1, nsurf]] + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + TODO: documentation needed + dimensions: + rank: 1 + dim: [[1, nsurf]] + coating_material(NX_FLOAT): + doc: | + TODO: documentation needed + + # Why is this field a "float"? + dimensions: + rank: 1 + dim: [[1, nsurf]] + substrate_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + TODO: documentation needed + dimensions: + rank: 1 + dim: [[1, nsurf]] + coating_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + TODO: documentation needed + dimensions: + rank: 1 + dim: [[1, nsurf]] + number_sections(NX_INT): + unit: NX_UNITLESS + doc: | + number of substrate sections (also called ``nsurf`` as an + index in the ``NXguide`` specification) + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The entry opening of the guide lies on the reference plane. The center of the opening on that plane is + the reference point on the x and y axis. The reference plane is orthogonal to the z axis and is the + reference point along the z axis. Given no bend in the guide, it is parallel with z axis and extends + in the positive direction of the z axis. + + .. image:: guide/guide.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2896d5121b533db5a14ea0d8e98e1e1f707720fce199691a2c7b85756ffb0d7e +# +# +# +# +# +# +# number of reflecting surfaces +# number of wavelengths +# +# +# +# A neutron optical element to direct the path of the beam. +# +# :ref:`NXguide` is used by neutron instruments to describe +# a guide consists of several mirrors building a shape through which +# neutrons can be guided or directed. The simplest such form is box shaped +# although elliptical guides are gaining in popularity. +# The individual parts of a guide usually have common characteristics +# but there are cases where they are different. +# For example, a neutron guide might consist of 2 or 4 coated walls or +# a supermirror bender with multiple, coated vanes. +# +# To describe polarizing supermirrors such as used in neutron reflection, +# it may be necessary to revise this definition of :ref:`NXguide` +# to include :ref:`NXpolarizer` and/or :ref:`NXmirror`. +# +# When even greater complexity exists in the definition of what +# constitutes a *guide*, it has been suggested that :ref:`NXguide` +# be redefined as a :ref:`NXcollection` of :ref:`NXmirror` each +# having their own :ref:`NXgeometry` describing their location(s). +# +# For the more general case when describing mirrors, consider using +# :ref:`NXmirror`. +# +# NOTE: The NeXus International Advisory Committee welcomes +# comments for revision and improvement of +# this definition of :ref:`NXguide`. +# +# +# +# +# TODO: Explain what this NXgeometry group means. What is intended here? +# +# +# A description of this particular instance of ``NXguide``. +# +# +# TODO: documentation needed +# +# +# Reflectivity as function of reflecting surface and wavelength +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# reflectivity of each surface as a function of wavelength +# +# +# +# +# +# +# +# List of surfaces. Probably best to use index +# numbers but the specification is very loose. +# +# +# +# +# +# +# wavelengths at which reflectivity was measured +# +# +# +# +# +# +# TODO: documentation needed +# +# +# TODO: documentation needed +# +# +# +# +# +# +# +# +# +# +# external material outside substrate +# +# +# +# The ``m`` value for a supermirror, which defines the supermirror +# regime in multiples of the critical angle of Nickel. +# +# +# +# +# +# +# TODO: documentation needed +# +# +# +# +# +# TODO: documentation needed +# +# +# +# +# +# TODO: documentation needed +# +# +# +# +# +# TODO: documentation needed +# +# +# +# +# +# TODO: documentation needed +# +# +# +# +# +# +# number of substrate sections (also called ``nsurf`` as an +# index in the ``NXguide`` specification) +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The entry opening of the guide lies on the reference plane. The center of the opening on that plane is +# the reference point on the x and y axis. The reference plane is orthogonal to the z axis and is the +# reference point along the z axis. Given no bend in the guide, it is parallel with z axis and extends +# in the positive direction of the z axis. +# +# .. image:: guide/guide.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXinsertion_device.yaml b/base_classes/nyaml/NXinsertion_device.yaml new file mode 100644 index 0000000000..a766eea7f8 --- /dev/null +++ b/base_classes/nyaml/NXinsertion_device.yaml @@ -0,0 +1,203 @@ +category: base +doc: | + An insertion device, as used in a synchrotron light source. +type: group +NXinsertion_device(NXobject): + type: + enumeration: [undulator, wiggler] + gap(NX_FLOAT): + unit: NX_LENGTH + doc: | + separation between opposing pairs of magnetic poles + taper(NX_FLOAT): + unit: NX_ANGLE + doc: | + angular of gap difference between upstream and downstream ends of the insertion device + phase(NX_FLOAT): + unit: NX_ANGLE + poles(NX_INT): + unit: NX_UNITLESS + doc: | + number of poles + magnetic_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + k(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + beam displacement parameter + length(NX_FLOAT): + unit: NX_LENGTH + doc: | + length of insertion device + power(NX_FLOAT): + unit: NX_POWER + doc: | + total power delivered by insertion device + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy of peak intensity in output spectrum + bandwidth(NX_FLOAT): + unit: NX_ENERGY + doc: | + bandwidth of peak energy + + # What are the best units here? + harmonic(NX_INT): + unit: NX_UNITLESS + doc: | + harmonic number of peak + (NXdata)spectrum: + doc: | + spectrum of insertion device + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the device and NXoff_geometry to describe its shape instead + doc: | + "Engineering" position of insertion device + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a insertion device. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 66cc252b3f21c2e74504d10b2f495979e96ee7818751b8cfca5265c900729b97 +# +# +# +# +# An insertion device, as used in a synchrotron light source. +# +# +# +# +# +# +# +# separation between opposing pairs of magnetic poles +# +# +# angular of gap difference between upstream and downstream ends of the insertion device +# +# +# +# number of poles +# +# +# +# beam displacement parameter +# +# +# length of insertion device +# +# +# total power delivered by insertion device +# +# +# energy of peak intensity in output spectrum +# +# +# bandwidth of peak energy +# +# +# harmonic number of peak +# +# +# spectrum of insertion device +# +# +# "Engineering" position of insertion device +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a insertion device. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXinstrument.yaml b/base_classes/nyaml/NXinstrument.yaml new file mode 100644 index 0000000000..55843e9061 --- /dev/null +++ b/base_classes/nyaml/NXinstrument.yaml @@ -0,0 +1,152 @@ +category: base +doc: | + Collection of the components of the instrument or beamline. + + Template of instrument descriptions comprising various beamline components. + Each component will also be a NeXus group defined by its distance from the + sample. Negative distances represent beamline components that are before the + sample while positive distances represent components that are after the sample. + This device allows the unique identification of beamline components in a way + that is valid for both reactor and pulsed instrumentation. +type: group +NXinstrument(NXobject): + name: + doc: | + Name of instrument + \@short_name: + doc: | + short name for instrument, perhaps the acronym + (NXactuator): + (NXaperture): + (NXattenuator): + (NXbeam): + (NXbeam_stop): + (NXbending_magnet): + (NXcollimator): + (NXcollection): + (NXcapillary): + (NXcrystal): + (NXdetector): + (NXdetector_group): + (NXdisk_chopper): + (NXevent_data): + (NXfabrication): + (NXfermi_chopper): + (NXfilter): + (NXflipper): + (NXguide): + (NXinsertion_device): + (NXmirror): + (NXmoderator): + (NXmonochromator): + (NXpolarizer): + (NXpositioner): + (NXsensor): + (NXresolution): + (NXsource): + (NXtransformations)DIFFRACTOMETER: + (NXvelocity_selector): + (NXxraylens): + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e89eac143a0a1145377ca71b55368c7158a95b46f8a784ded37cc17e3c23046a +# +# +# +# +# +# Collection of the components of the instrument or beamline. +# +# Template of instrument descriptions comprising various beamline components. +# Each component will also be a NeXus group defined by its distance from the +# sample. Negative distances represent beamline components that are before the +# sample while positive distances represent components that are after the sample. +# This device allows the unique identification of beamline components in a way +# that is valid for both reactor and pulsed instrumentation. +# +# +# +# Name of instrument +# +# +# +# short name for instrument, perhaps the acronym +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXlog.yaml b/base_classes/nyaml/NXlog.yaml new file mode 100644 index 0000000000..23c562f8ce --- /dev/null +++ b/base_classes/nyaml/NXlog.yaml @@ -0,0 +1,252 @@ +category: base +doc: | + Information recorded as a function of time. + + Description of information that is recorded against + time. There are two common use cases for this: + + - When logging data such as temperature during a run + - When data is taken in streaming mode data acquisition, + i.e. just timestamp, value pairs are stored and + correlated later in data reduction with other data, + + + In both cases, NXlog contains + the logged or streamed values and the times at which they were measured as elapsed time since a starting + time recorded in ISO8601 format. The time units are + specified in the units attribute. An optional scaling attribute + can be used to accomodate non standard clocks. + + + This method of storing logged data helps to distinguish + instances in which a variable is a dimension scale of the data, in which case it is stored + in an :ref:`NXdata` group, and instances in which it is logged during the + run, when it should be stored in an :ref:`NXlog` group. + + In order to make random access to timestamped data faster there is an optional array pair of + ``cue_timestamp_zero`` and ``cue_index``. The ``cue_timestamp_zero`` will + contain coarser timestamps than in the time array, say + every five minutes. The ``cue_index`` will then contain the + index into the time,value pair of arrays for that + coarser ``cue_timestamp_zero``. +type: group +NXlog(NXobject): + time(NX_NUMBER): + unit: NX_TIME + doc: | + Time of logged entry. The times are relative to the "start" attribute + and in the units specified in the "units" + attribute. Please note that absolute + timestamps under unix are relative to ``1970-01-01T00:00:00.0Z``. + + The scaling_factor, when present, has to be applied to the time values in order + to arrive at the units specified in the units attribute. The scaling_factor allows + for arbitrary time units such as ticks of some hardware clock. + \@start: + type: NX_DATE_TIME + \@scaling_factor: + type: NX_NUMBER + value(NX_NUMBER): + unit: NX_ANY + doc: | + Array of logged value, such as temperature. If this is + a single value the dimensionality is + nEntries. However, NXlog can also be used to store + multi dimensional time stamped data such as images. In + this example the dimensionality of values would be value[nEntries,xdim,ydim]. + raw_value(NX_NUMBER): + unit: NX_ANY + doc: | + Array of raw information, such as thermocouple voltage + description: + doc: | + Description of logged value + average_value(NX_FLOAT): + unit: NX_ANY + average_value_error(NX_FLOAT): + unit: NX_ANY + deprecated: | + see: https://github.com/nexusformat/definitions/issues/639 + doc: | + estimated uncertainty (often used: standard deviation) of average_value + average_value_errors(NX_FLOAT): + unit: NX_ANY + doc: | + estimated uncertainty (often used: standard deviation) of average_value + minimum_value(NX_FLOAT): + unit: NX_ANY + maximum_value(NX_FLOAT): + unit: NX_ANY + duration(NX_FLOAT): + unit: NX_ANY + doc: | + Total time log was taken + cue_timestamp_zero(NX_NUMBER): + unit: NX_TIME + doc: | + Timestamps matching the corresponding cue_index into the + time, value pair. + \@start: + type: NX_DATE_TIME + doc: | + If missing start is assumed to be the same as for "time". + \@scaling_factor: + type: NX_NUMBER + doc: | + If missing start is assumed to be the same as for "time". + cue_index(NX_INT): + doc: | + Index into the time, value pair matching the corresponding + cue_timestamp_zero. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 775c7adbe6f8bd856db0bf06a7f0f735b669cbd37ac5ff47634f9e5bddc485fe +# +# +# +# +# +# Information recorded as a function of time. +# +# Description of information that is recorded against +# time. There are two common use cases for this: +# +# - When logging data such as temperature during a run +# - When data is taken in streaming mode data acquisition, +# i.e. just timestamp, value pairs are stored and +# correlated later in data reduction with other data, +# +# +# In both cases, NXlog contains +# the logged or streamed values and the times at which they were measured as elapsed time since a starting +# time recorded in ISO8601 format. The time units are +# specified in the units attribute. An optional scaling attribute +# can be used to accomodate non standard clocks. +# +# +# This method of storing logged data helps to distinguish +# instances in which a variable is a dimension scale of the data, in which case it is stored +# in an :ref:`NXdata` group, and instances in which it is logged during the +# run, when it should be stored in an :ref:`NXlog` group. +# +# In order to make random access to timestamped data faster there is an optional array pair of +# ``cue_timestamp_zero`` and ``cue_index``. The ``cue_timestamp_zero`` will +# contain coarser timestamps than in the time array, say +# every five minutes. The ``cue_index`` will then contain the +# index into the time,value pair of arrays for that +# coarser ``cue_timestamp_zero``. +# +# +# +# +# Time of logged entry. The times are relative to the "start" attribute +# and in the units specified in the "units" +# attribute. Please note that absolute +# timestamps under unix are relative to ``1970-01-01T00:00:00.0Z``. +# +# The scaling_factor, when present, has to be applied to the time values in order +# to arrive at the units specified in the units attribute. The scaling_factor allows +# for arbitrary time units such as ticks of some hardware clock. +# +# +# +# +# +# +# Array of logged value, such as temperature. If this is +# a single value the dimensionality is +# nEntries. However, NXlog can also be used to store +# multi dimensional time stamped data such as images. In +# this example the dimensionality of values would be value[nEntries,xdim,ydim]. +# +# +# +# Array of raw information, such as thermocouple voltage +# +# +# Description of logged value +# +# +# +# estimated uncertainty (often used: standard deviation) of average_value +# +# +# estimated uncertainty (often used: standard deviation) of average_value +# +# +# +# +# Total time log was taken +# +# +# +# Timestamps matching the corresponding cue_index into the +# time, value pair. +# +# +# If missing start is assumed to be the same as for "time". +# +# +# If missing start is assumed to be the same as for "time". +# +# +# +# +# Index into the time, value pair matching the corresponding +# cue_timestamp_zero. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXmirror.yaml b/base_classes/nyaml/NXmirror.yaml new file mode 100644 index 0000000000..1f2d7fde93 --- /dev/null +++ b/base_classes/nyaml/NXmirror.yaml @@ -0,0 +1,346 @@ +category: base +doc: | + A beamline mirror or supermirror. +type: group +NXmirror(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the mirror and NXoff_geometry to describe its shape instead + doc: | + + # TODO explain what this group means + type: + enumeration: + single: + doc: | + mirror with a single material as a reflecting surface + multi: + doc: | + mirror with stacked, multiple layers as a reflecting surface + description: + doc: | + description of this mirror + incident_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + (NXdata)reflectivity: + + # TODO Trac ticket #45 applies here. + # https://github.com/nexusformat/definitions/issues/45 + # TODO Solution of ticket #41 will apply here, as well. + # https://github.com/nexusformat/definitions/issues/41 + doc: | + Reflectivity as function of wavelength + + # TODO need more documentation throughout + bend_angle_x(NX_FLOAT): + unit: NX_ANGLE + doc: | + bend_angle_y(NX_FLOAT): + unit: NX_ANGLE + doc: | + interior_atmosphere: + enumeration: [vacuum, helium, argon] + external_material: + doc: | + external material outside substrate + m_value(NX_FLOAT): + unit: NX_UNITLESS + doc: | + The m value for a supermirror, which defines the supermirror + regime in multiples of the critical angle of Nickel. + substrate_material: + doc: | + substrate_density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + coating_material: + doc: | + substrate_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + coating_roughness(NX_FLOAT): + unit: NX_LENGTH + doc: | + even_layer_material: + doc: | + even_layer_density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + odd_layer_material: + doc: | + odd_layer_density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + layer_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + An array describing the thickness of each layer + (NXshape)shape: + deprecated: Use NXoff_geometry instead + doc: | + A NXshape group describing the shape of the mirror + figure_data(NXdata): + doc: | + Numerical description of the surface figure of the mirror. + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + Given a flat mirror, the reference plane is the plane which contains the "entry" surface of the mirror. The reference + point of the mirror in the x and y axis is the centre of the mirror on that plane. The reference plane is orthogonal + to the z axis and the location of this plane is the reference point on the z axis. The mirror faces negative z values. + + .. image:: mirror/mirror.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + # TODO need more parameters here, such as ... + # list from Rainer Gehrke, DESY (some items may already be present) + # Parameters for mirrors + # Field indicating whether simple or multilayer + # Substrate element or compound + # Substrate density + # In case of multilayer: Even layer material (element or compound) + # Even layer density + # Odd layer material (element or compound) + # Odd layer density + # Number of layer pairs + # Layer thickness (array) + # Figure for crystals and mirrors (to describe curved surfaces) + # Field indicating whether concave or convex + # Field indicating whether cylindrical or not + # If cylindrical: cylinder orientation angle + # Now come the different surface figures with the necessary parameters: + # 1. Flat + # 2. Spherical (spherical radius) + # 3. Elliptical and hyperbolical (semi-major axis, semi-minor axis, angle of major axis and pole) + # 4. Toroidal (major radius, minor radius) + # 5. Parabolical (parabolic parameter a) + # 6. Conical (cone half aperture) + # 7. Polynomial (degree of polynom, array with polynom coefficients) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a03676b8f4d052897916c9b81795834122a04f213afa50c03aa362eb1386a7c4 +# +# +# +# +# A beamline mirror or supermirror. +# +# +# +# +# +# +# mirror with a single material as a reflecting surface +# mirror with stacked, multiple layers as a reflecting surface +# +# +# +# description of this mirror +# +# +# +# +# +# +# Reflectivity as function of wavelength +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# external material outside substrate +# +# +# +# The m value for a supermirror, which defines the supermirror +# regime in multiples of the critical angle of Nickel. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# An array describing the thickness of each layer +# +# +# A NXshape group describing the shape of the mirror +# +# +# Numerical description of the surface figure of the mirror. +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# Given a flat mirror, the reference plane is the plane which contains the "entry" surface of the mirror. The reference +# point of the mirror in the x and y axis is the centre of the mirror on that plane. The reference plane is orthogonal +# to the z axis and the location of this plane is the reference point on the z axis. The mirror faces negative z values. +# +# .. image:: mirror/mirror.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXmoderator.yaml b/base_classes/nyaml/NXmoderator.yaml new file mode 100644 index 0000000000..933a5d19eb --- /dev/null +++ b/base_classes/nyaml/NXmoderator.yaml @@ -0,0 +1,193 @@ +category: base +doc: | + A neutron moderator +type: group +NXmoderator(NXobject): + (NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the moderator and NXoff_geometry to describe its shape instead + doc: | + "Engineering" position of moderator + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Effective distance as seen by measuring radiation. + Note, it is recommended to use NXtransformations instead. + type: + enumeration: [H20, D20, Liquid H2, Liquid CH4, Liquid D2, Solid D2, C, Solid CH4, Solid H2] + poison_depth(NX_FLOAT): + unit: NX_LENGTH + coupled(NX_BOOLEAN): + doc: | + whether the moderator is coupled + coupling_material: + doc: | + The material used for coupling. Usually Cd. + poison_material: + enumeration: [Gd, Cd] + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + average/nominal moderator temperature + (NXlog)temperature_log: + doc: | + log file of moderator temperature + (NXdata)pulse_shape: + doc: | + moderator pulse shape + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the moderator + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the moderator is its center in the x and y axis. The reference point on the z axis is the + surface of the moderator pointing towards the source (the negative part of the z axis). + + .. image:: moderator/moderator.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ff14aa8ec99692829b7fdf4b0cef94d8ec8835d366dab359d75fdf1754289e8a +# +# +# +# +# A neutron moderator +# +# "Engineering" position of moderator +# +# +# +# Effective distance as seen by measuring radiation. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# whether the moderator is coupled +# +# +# The material used for coupling. Usually Cd. +# +# +# +# +# +# +# +# +# average/nominal moderator temperature +# +# +# log file of moderator temperature +# +# +# moderator pulse shape +# +# +# +# This group describes the shape of the moderator +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the moderator is its center in the x and y axis. The reference point on the z axis is the +# surface of the moderator pointing towards the source (the negative part of the z axis). +# +# .. image:: moderator/moderator.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXmonitor.yaml b/base_classes/nyaml/NXmonitor.yaml new file mode 100644 index 0000000000..7135187cd0 --- /dev/null +++ b/base_classes/nyaml/NXmonitor.yaml @@ -0,0 +1,293 @@ +category: base +doc: | + A monitor of incident beam data. + + It is similar to the :ref:`NXdata` groups containing + monitor data and its associated dimension scale, e.g. time_of_flight or + wavelength in pulsed neutron instruments. However, it may also include + integrals, or scalar monitor counts, which are often used in both in both + pulsed and steady-state instrumentation. +type: group +NXmonitor(NXobject): + mode: + doc: | + Count to a preset value based on either clock time (timer) + or received monitor counts (monitor). + enumeration: [monitor, timer] + start_time(NX_DATE_TIME): + doc: | + Starting time of measurement + end_time(NX_DATE_TIME): + doc: | + Ending time of measurement + preset(NX_NUMBER): + unit: NX_ANY + doc: | + preset value for time or monitor + distance(NX_FLOAT): + unit: NX_LENGTH + deprecated: Use transformations/distance instead + doc: | + Distance of monitor from sample + range(NX_FLOAT): + unit: NX_ANY + doc: | + Range (X-axis, Time-of-flight, etc.) over which the integral was calculated + dimensions: + dim: [[1, 2]] + nominal(NX_NUMBER): + unit: NX_ANY + doc: | + Nominal reading to be used for normalisation purposes. + integral(NX_NUMBER): + unit: NX_ANY + doc: | + Total integral monitor counts + integral_log(NXlog): + doc: | + Time variation of monitor counts + type: + enumeration: [Fission Chamber, Scintillator] + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + doc: | + Time-of-flight + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['efficiency'] + efficiency(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Monitor efficiency + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['i'] + data(NX_NUMBER): + unit: NX_ANY + doc: | + Monitor data + dimensions: + rank: dataRank + doc: | + The rank (``dataRank``) of the ``data`` must satisfy + ``1 <= dataRank <= NX_MAXRANK=32``. + At least one ``dim`` must have length ``n``. + dim: [] + sampled_fraction(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Proportion of incident beam sampled by the monitor (0 +# +# +# +# +# A monitor of incident beam data. +# +# It is similar to the :ref:`NXdata` groups containing +# monitor data and its associated dimension scale, e.g. time_of_flight or +# wavelength in pulsed neutron instruments. However, it may also include +# integrals, or scalar monitor counts, which are often used in both in both +# pulsed and steady-state instrumentation. +# +# +# +# Count to a preset value based on either clock time (timer) +# or received monitor counts (monitor). +# +# +# +# +# +# +# +# Starting time of measurement +# +# +# Ending time of measurement +# +# +# preset value for time or monitor +# +# +# Distance of monitor from sample +# +# +# Range (X-axis, Time-of-flight, etc.) over which the integral was calculated +# +# +# +# Nominal reading to be used for normalisation purposes. +# +# +# Total integral monitor counts +# +# +# Time variation of monitor counts +# +# +# +# +# +# +# +# +# Time-of-flight +# +# +# +# +# +# Monitor efficiency +# +# +# +# +# Monitor data +# +# +# +# The rank (``dataRank``) of the ``data`` must satisfy +# ``1 <= dataRank <= NX_MAXRANK=32``. +# At least one ``dim`` must have length ``n``. +# +# +# +# +# Proportion of incident beam sampled by the monitor (0<x<1) +# +# +# Geometry of the monitor +# +# +# +# Elapsed actual counting time, can be an array of size ``np`` +# when scanning. This is not the difference of the calendar time +# but the time the instrument was really counting, without +# pauses or times lost due beam unavailability +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference plane of the monitor contains the surface of the detector that faces the source +# and is the entry point of the beam. The reference point of the monitor in the x and y axis is +# its centre on this surface. The reference plane is orthogonal to the the z axis and the +# reference point on this z axis is where they intersect. +# +# .. image:: monitor/monitor.png +# :width: 40% +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXmonochromator.yaml b/base_classes/nyaml/NXmonochromator.yaml new file mode 100644 index 0000000000..83a26bf0a6 --- /dev/null +++ b/base_classes/nyaml/NXmonochromator.yaml @@ -0,0 +1,197 @@ +category: base +doc: | + A wavelength defining device. + + This is a base class for everything which + selects a wavelength or energy, be it a + monochromator crystal, a velocity selector, + an undulator or whatever. + + The expected units are: + + * wavelength: angstrom + * energy: eV +type: group +NXmonochromator(NXobject): + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + wavelength selected + wavelength_error(NX_FLOAT): + unit: NX_WAVELENGTH + deprecated: | + see https://github.com/nexusformat/definitions/issues/820 + doc: | + wavelength standard deviation + wavelength_errors(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + wavelength standard deviation + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy selected + energy_error(NX_FLOAT): + unit: NX_ENERGY + deprecated: | + see https://github.com/nexusformat/definitions/issues/820 + doc: | + energy standard deviation + energy_errors(NX_FLOAT): + unit: NX_ENERGY + doc: | + energy standard deviation + (NXdata)distribution: + (NXgeometry)geometry: + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the monochromator and NXoff_geometry to describe its shape instead + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + (NXcrystal): + doc: | + Use as many crystals as necessary to describe + (NXvelocity_selector): + (NXgrating): + doc: | + For diffraction grating based monochromators + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a monochromator. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7c8e15a2e9b17a3867e3f0c2b0b16c8a8c70c7b512f1f20340e7a2398b21ab7b +# +# +# +# +# +# A wavelength defining device. +# +# This is a base class for everything which +# selects a wavelength or energy, be it a +# monochromator crystal, a velocity selector, +# an undulator or whatever. +# +# The expected units are: +# +# * wavelength: angstrom +# * energy: eV +# +# +# +# wavelength selected +# +# +# wavelength standard deviation +# +# +# wavelength standard deviation +# +# +# energy selected +# +# +# energy standard deviation +# +# +# energy standard deviation +# +# +# +# +# +# This group describes the shape of the beam line component +# +# +# Use as many crystals as necessary to describe +# +# For diffraction grating based monochromators +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a monochromator. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXnote.yaml b/base_classes/nyaml/NXnote.yaml new file mode 100644 index 0000000000..229f0c82b0 --- /dev/null +++ b/base_classes/nyaml/NXnote.yaml @@ -0,0 +1,116 @@ +category: base +doc: | + Any additional freeform information not covered by the other base classes. + + This class can be used to store additional information in a + NeXus file e.g. pictures, movies, audio, additional text logs +type: group +NXnote(NXobject): + author: + doc: | + Author or creator of note + date(NX_DATE_TIME): + doc: | + Date note created/added + type: + doc: | + Mime content type of note data field e.g. image/jpeg, text/plain, text/html + file_name: + doc: | + Name of original file name if note was read from an external source + description: + doc: | + Title of an image or other details of the note + sequence_index(NX_POSINT): + doc: | + Sequence index of note, for placing a sequence of + multiple **NXnote** groups in an order. Starts with 1. + data(NX_BINARY): + doc: | + Binary note data - if text, line terminator is [CR][LF]. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cac46891aabdb595f69910c7ddb6a496bd16f4e98055ddc5570ef01fbeed1e73 +# +# +# +# +# +# Any additional freeform information not covered by the other base classes. +# +# This class can be used to store additional information in a +# NeXus file e.g. pictures, movies, audio, additional text logs +# +# +# Author or creator of note +# +# +# Date note created/added +# +# +# Mime content type of note data field e.g. image/jpeg, text/plain, text/html +# +# +# Name of original file name if note was read from an external source +# +# +# Title of an image or other details of the note +# +# +# +# Sequence index of note, for placing a sequence of +# multiple **NXnote** groups in an order. Starts with 1. +# +# +# +# Binary note data - if text, line terminator is [CR][LF]. +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXobject.yaml b/base_classes/nyaml/NXobject.yaml new file mode 100644 index 0000000000..cbf07862fb --- /dev/null +++ b/base_classes/nyaml/NXobject.yaml @@ -0,0 +1,44 @@ +category: base +doc: | + This is the base object of NeXus +type: group +NXobject: + + # attribute name="name">name of instance +# +# +# +# +# This is the base object of NeXus +# +# +# +# diff --git a/base_classes/nyaml/NXoff_geometry.yaml b/base_classes/nyaml/NXoff_geometry.yaml new file mode 100644 index 0000000000..abc3de7ede --- /dev/null +++ b/base_classes/nyaml/NXoff_geometry.yaml @@ -0,0 +1,197 @@ +category: base +doc: | + Geometry (shape) description. + The format closely matches the Object File Format (OFF) which can be output + by most CAD software. + It can be used to describe the shape of any beamline component, including detectors. + In the case of detectors it can be used to define the shape of a single pixel, or, + if the pixel shapes are non-uniform, to describe the shape of the whole detector. +symbols: + doc: | + These symbols will be used below. + i: | + number of vertices in the shape + k: | + number of faces in the shape + l: | + number faces which are detecting surfaces or form the boundary of + detecting volumes +type: group +NXoff_geometry(NXobject): + vertices(NX_NUMBER): + unit: NX_LENGTH + doc: | + List of x,y,z coordinates for vertices. + The origin of the coordinates is the position of the parent component, for + example the NXdetector which the geometry describes. + If the shape describes a single pixel for a detector with uniform pixel + shape then the origin is the position of each pixel as described by the + ``x/y/z_pixel_offset`` datasets in ``NXdetector``. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + winding_order(NX_INT): + doc: | + List of indices of vertices in the ``vertices`` dataset to form each face, + right-hand rule for face normal. + dimensions: + rank: 1 + dim: [[1, j]] + faces(NX_INT): + doc: | + The start index in ``winding_order`` for each face. + dimensions: + rank: 1 + dim: [[1, k]] + detector_faces(NX_INT): + doc: | + List of pairs of index in the "faces" dataset and detector id. Face IDs in + the first column, and corresponding detector IDs in the second column. + This dataset should only be used only if the ``NXoff_geometry`` group is + describing a detector. + Note, the face indices must be in ascending order but need not be + consecutive as not every face in faces need be a detecting surface or + boundary of detecting volume. + Can use multiple entries with the same detector id to define detector volumes. + dimensions: + rank: 2 + dim: [[1, l], [2, 2]] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 593884a075055d155060d7a8bb7a8d3b3164efcad905aed084064fc4ae052ead +# +# +# +# +# +# +# These symbols will be used below. +# number of vertices in the shape +# number of faces in the shape +# +# +# number faces which are detecting surfaces or form the boundary of +# detecting volumes +# +# +# +# +# +# Geometry (shape) description. +# The format closely matches the Object File Format (OFF) which can be output +# by most CAD software. +# It can be used to describe the shape of any beamline component, including detectors. +# In the case of detectors it can be used to define the shape of a single pixel, or, +# if the pixel shapes are non-uniform, to describe the shape of the whole detector. +# +# +# +# +# +# List of x,y,z coordinates for vertices. +# The origin of the coordinates is the position of the parent component, for +# example the NXdetector which the geometry describes. +# If the shape describes a single pixel for a detector with uniform pixel +# shape then the origin is the position of each pixel as described by the +# ``x/y/z_pixel_offset`` datasets in ``NXdetector``. +# +# +# +# +# +# +# +# +# +# +# +# +# List of indices of vertices in the ``vertices`` dataset to form each face, +# right-hand rule for face normal. +# +# +# +# +# +# +# +# +# +# +# The start index in ``winding_order`` for each face. +# +# +# +# +# +# +# +# +# +# +# List of pairs of index in the "faces" dataset and detector id. Face IDs in +# the first column, and corresponding detector IDs in the second column. +# This dataset should only be used only if the ``NXoff_geometry`` group is +# describing a detector. +# Note, the face indices must be in ascending order but need not be +# consecutive as not every face in faces need be a detecting surface or +# boundary of detecting volume. +# Can use multiple entries with the same detector id to define detector volumes. +# +# +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXorientation.yaml b/base_classes/nyaml/NXorientation.yaml new file mode 100644 index 0000000000..04a28a40cb --- /dev/null +++ b/base_classes/nyaml/NXorientation.yaml @@ -0,0 +1,111 @@ +category: base +doc: | + legacy class - recommend to use :ref:`NXtransformations` now + + Description for a general orientation of a component - used by :ref:`NXgeometry` +type: group +NXorientation(NXobject): + (NXgeometry): + doc: | + Link to another object if we are using relative positioning, else absent + value(NX_FLOAT): + unit: NX_UNITLESS + doc: | + The orientation information is stored as direction cosines. The direction cosines will + be between the local coordinate directions and the reference directions (to origin or + relative NXgeometry). Calling the local unit vectors (x',y',z') and the reference unit + vectors (x,y,z) the six numbers will be [x' dot x, x' dot y, x' dot z, y' dot x, y' dot + y, y' dot z] where "dot" is the scalar dot product (cosine of the angle between the unit + vectors). The unit vectors in both the local and reference coordinates are right-handed + and orthonormal. + + The pair of groups NXtranslation and NXorientation together + describe the position of a component. + dimensions: + + # numobj,6 + dim: [[1, numobj], [2, 6]] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b837027cfb5d13fbee2db64988ee3af2d8ea788d712eaf5455b1eba597023f42 +# +# +# +# +# +# legacy class - recommend to use :ref:`NXtransformations` now +# +# Description for a general orientation of a component - used by :ref:`NXgeometry` +# +# +# Link to another object if we are using relative positioning, else absent +# +# +# +# The orientation information is stored as direction cosines. The direction cosines will +# be between the local coordinate directions and the reference directions (to origin or +# relative NXgeometry). Calling the local unit vectors (x',y',z') and the reference unit +# vectors (x,y,z) the six numbers will be [x' dot x, x' dot y, x' dot z, y' dot x, y' dot +# y, y' dot z] where "dot" is the scalar dot product (cosine of the angle between the unit +# vectors). The unit vectors in both the local and reference coordinates are right-handed +# and orthonormal. +# +# The pair of groups NXtranslation and NXorientation together +# describe the position of a component. +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXparameters.yaml b/base_classes/nyaml/NXparameters.yaml new file mode 100644 index 0000000000..e81a3b034b --- /dev/null +++ b/base_classes/nyaml/NXparameters.yaml @@ -0,0 +1,75 @@ +category: base +doc: | + Container for parameters, usually used in processing or analysis. +type: group +NXparameters(NXobject): + term(NX_CHAR): + exists: ['min', '0', 'max', 'unbounded'] + + # maxOccurs="unbounded" is intended but is not allowed by current syntax + doc: | + A parameter (also known as a term) that is used in or results from processing. + \@units: + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4306876a0e67eaf3b38dfb0d8c2236908c7816908082629bdeb23948c1842a87 +# +# +# +# +# Container for parameters, usually used in processing or analysis. +# +# +# A parameter (also known as a term) that is used in or results from processing. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXpdb.yaml b/base_classes/nyaml/NXpdb.yaml new file mode 100644 index 0000000000..24cfd73920 --- /dev/null +++ b/base_classes/nyaml/NXpdb.yaml @@ -0,0 +1,329 @@ +category: base + +# The ignoreExtra* attributes are used in the definition to +# avoid warning messages that would be generated from +# unexpected groups, fields, and attributes. +# Since no groups or attributes are declared here, _every_ +# child of this class would generate a warning message without this +# attribute being set to "true". +doc: | + A NeXus transliteration of a PDB file, to be validated only as a PDB + rather than in NeXus. + + Use :ref:`NXpdb` to incorporate the information in an arbitrary + PDB into a NeXus file. + + The main suggestion is to use this as a container + class for a PDB entry to describe a sample in NXsample, + but it may be more appropriate to place this higher in the + hierarchy, say in NXentry. + + The structure has to follow the structure of a PDB + with each PDB data block mapped to a NeXus group of class NXpdb, + using a lowercase version of the data block name as the name + of the NeXus group, each PDB category in that data block + mapped to a NeXus group of class NXpdb and with each PDB column + mapped to a NeXus field. Each column in a looped PDB category + should always be presented as a 1-dimensional array. The columns + in an unlooped PDB category should be presented as scalar values. + If a PDB category specifies particular units for columns, the same + units should beused for the corresponding fields. + + A PDB entry is unambigous when all information is carried as text. + All text data should be presented as quoted strings, with the quote + marks except for the null values "." or "?" + + For clarity in NXpdb form, numeric data may be presented using the + numeric types specified in the mmCIF dictionary. In that case, + if a PDB null value, "." or "?", is contained in a numeric column, the + IEEE nan should be used for "?" and the IEEE inf should be used for ".". + + An arbitrary DDL2 CIF file can be represented in NeXus using NXpdb. + However, if save frames are required, an NXpdb_class attribute with the + value "CBF_cbfsf" is required for each NeXus group representing a save + frame. NXpdb attributes are not required for other CIF components, + but may be used to provide internal documentation. + + The nesting of NXpdb groups and datasets that correspond to a CIF with + two categories and one saveframe, including the NXpdb_class attribues is:: + + (datablock1):NXpdb + @NXpdb_class:CBF_cbfdb + (category1):NXpdb + @NXpdb_class:CBF_cbfcat + (column_name1):[...] + (column_name2):[...] + (column_name3):[...] + ... + (category2):NXpdb + @NXpdb_class:CBF_cbfcat + (column_name4):[...] + (column_name5):[...] + (column_name6):[...] + ... + (saveframe1):NXpdb + @NXpdb_class:CBF_cbfsf + (category3):NXpdb + @NXpdb_class:CBF_cbfcat + (column_name7):[...] + (column_name8):[...] + (column_name9):[...] + ... + ... + ... + + + + For example, a PDB entry that begins:: + + data_1YVA + # + _entry.id 1YVA + # + _audit_conform.dict_name mmcif_pdbx.dic + _audit_conform.dict_version 5.279 + _audit_conform.dict_location http://mmcif.pdb.org/dictionaries/ascii/mmcif_pdbx.dic + # + loop_ + _database_2.database_id + _database_2.database_code + PDB 1YVA + RCSB RCSB031959 + WWPDB D_1000031959 + # + + would produce:: + + sample:NXsample + 1yva:NXpdb + entry:NXpdb + id:"1YVA" + audit_conform:NXpdb + dict_name:"mmcif_pdbx.dic" + dict_version:"5.279" + dict_location:"http://mmcif.pdb.org/dictionaries/ascii/mmcif_pdbx.dic" + database_2:NXpdb + database_id:["PDB","RCSB","WWPDB"] + database_code:["1YVA","RCSB031959","D_1000031959"] + + another example is the following excerpt from pdb entry 9ins, giving the sequences + of the two chains:: + + loop_ + _entity_poly.entity_id + _entity_poly.nstd_linkage + _entity_poly.nstd_monomer + _entity_poly.pdbx_seq_one_letter_code + _entity_poly.pdbx_seq_one_letter_code_can + _entity_poly.type + 1 no no GIVEQCCTSICSLYQLENYCN GIVEQCCTSICSLYQLENYCN polypeptide(L) + 2 no no FVNQHLCGSHLVEALYLVCGERGFFYTPKA FVNQHLCGSHLVEALYLVCGERGFFYTPKA + polypeptide(L) + + which converts to:: + + entity_poly:NXpdb + @NXpdb_class:CBF_cbfcat + entity_id:["1", "2"] + nstd_linkage:["no", "no"] + nstd_monomer:["no", "no"] + pdbx_seq_one_letter_code:["GIVEQCCTSICSLYQLENYCN","FVNQHLCGSHLVEALYLVCGERGFFYTPKA"] + pdbx_seq_one_letter_code_can:["GIVEQCCTSICSLYQLENYCN","FVNQHLCGSHLVEALYLVCGERGFFYTPKA"] + type:["polypeptide(L)", "polypeptide(L)"] +type: group +ignoreExtraGroups: true +ignoreExtraFields: true +ignoreExtraAttributes: true +NXpdb(NXobject): + + # NOTE + # ===== + # NXpdb is a class not validated by the NXDL tools. + # Do not add any subgroups in this nxdl file. + # See: https://github.com/nexusformat/definitions/issues/259 + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a7abffb938a9848149b6d1c2b7f0e7d0f47792f36c6dc44ad9f3831a9c3c0172 +# +# +# +# +# +# +# +# +# A NeXus transliteration of a PDB file, to be validated only as a PDB +# rather than in NeXus. +# +# Use :ref:`NXpdb` to incorporate the information in an arbitrary +# PDB into a NeXus file. +# +# The main suggestion is to use this as a container +# class for a PDB entry to describe a sample in NXsample, +# but it may be more appropriate to place this higher in the +# hierarchy, say in NXentry. +# +# The structure has to follow the structure of a PDB +# with each PDB data block mapped to a NeXus group of class NXpdb, +# using a lowercase version of the data block name as the name +# of the NeXus group, each PDB category in that data block +# mapped to a NeXus group of class NXpdb and with each PDB column +# mapped to a NeXus field. Each column in a looped PDB category +# should always be presented as a 1-dimensional array. The columns +# in an unlooped PDB category should be presented as scalar values. +# If a PDB category specifies particular units for columns, the same +# units should beused for the corresponding fields. +# +# A PDB entry is unambigous when all information is carried as text. +# All text data should be presented as quoted strings, with the quote +# marks except for the null values "." or "?" +# +# For clarity in NXpdb form, numeric data may be presented using the +# numeric types specified in the mmCIF dictionary. In that case, +# if a PDB null value, "." or "?", is contained in a numeric column, the +# IEEE nan should be used for "?" and the IEEE inf should be used for ".". +# +# An arbitrary DDL2 CIF file can be represented in NeXus using NXpdb. +# However, if save frames are required, an NXpdb_class attribute with the +# value "CBF_cbfsf" is required for each NeXus group representing a save +# frame. NXpdb attributes are not required for other CIF components, +# but may be used to provide internal documentation. +# +# The nesting of NXpdb groups and datasets that correspond to a CIF with +# two categories and one saveframe, including the NXpdb_class attribues is:: +# +# (datablock1):NXpdb +# @NXpdb_class:CBF_cbfdb +# (category1):NXpdb +# @NXpdb_class:CBF_cbfcat +# (column_name1):[...] +# (column_name2):[...] +# (column_name3):[...] +# ... +# (category2):NXpdb +# @NXpdb_class:CBF_cbfcat +# (column_name4):[...] +# (column_name5):[...] +# (column_name6):[...] +# ... +# (saveframe1):NXpdb +# @NXpdb_class:CBF_cbfsf +# (category3):NXpdb +# @NXpdb_class:CBF_cbfcat +# (column_name7):[...] +# (column_name8):[...] +# (column_name9):[...] +# ... +# ... +# ... +# +# +# +# For example, a PDB entry that begins:: +# +# data_1YVA +# # +# _entry.id 1YVA +# # +# _audit_conform.dict_name mmcif_pdbx.dic +# _audit_conform.dict_version 5.279 +# _audit_conform.dict_location http://mmcif.pdb.org/dictionaries/ascii/mmcif_pdbx.dic +# # +# loop_ +# _database_2.database_id +# _database_2.database_code +# PDB 1YVA +# RCSB RCSB031959 +# WWPDB D_1000031959 +# # +# +# would produce:: +# +# sample:NXsample +# 1yva:NXpdb +# entry:NXpdb +# id:"1YVA" +# audit_conform:NXpdb +# dict_name:"mmcif_pdbx.dic" +# dict_version:"5.279" +# dict_location:"http://mmcif.pdb.org/dictionaries/ascii/mmcif_pdbx.dic" +# database_2:NXpdb +# database_id:["PDB","RCSB","WWPDB"] +# database_code:["1YVA","RCSB031959","D_1000031959"] +# +# another example is the following excerpt from pdb entry 9ins, giving the sequences +# of the two chains:: +# +# loop_ +# _entity_poly.entity_id +# _entity_poly.nstd_linkage +# _entity_poly.nstd_monomer +# _entity_poly.pdbx_seq_one_letter_code +# _entity_poly.pdbx_seq_one_letter_code_can +# _entity_poly.type +# 1 no no GIVEQCCTSICSLYQLENYCN GIVEQCCTSICSLYQLENYCN polypeptide(L) +# 2 no no FVNQHLCGSHLVEALYLVCGERGFFYTPKA FVNQHLCGSHLVEALYLVCGERGFFYTPKA +# polypeptide(L) +# +# which converts to:: +# +# entity_poly:NXpdb +# @NXpdb_class:CBF_cbfcat +# entity_id:["1", "2"] +# nstd_linkage:["no", "no"] +# nstd_monomer:["no", "no"] +# pdbx_seq_one_letter_code:["GIVEQCCTSICSLYQLENYCN","FVNQHLCGSHLVEALYLVCGERGFFYTPKA"] +# pdbx_seq_one_letter_code_can:["GIVEQCCTSICSLYQLENYCN","FVNQHLCGSHLVEALYLVCGERGFFYTPKA"] +# type:["polypeptide(L)", "polypeptide(L)"] +# +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXpinhole.yaml b/base_classes/nyaml/NXpinhole.yaml new file mode 100644 index 0000000000..69fd2fe2cb --- /dev/null +++ b/base_classes/nyaml/NXpinhole.yaml @@ -0,0 +1,125 @@ +category: base +doc: | + A simple pinhole. + + For more complex geometries, :ref:`NXaperture` should be used. +type: group +NXpinhole(NXobject): + depends_on(NX_CHAR): + doc: | + Points to the path of the last element in the geometry chain that places + this object in space. + When followed through that chain is supposed to end at an element depending + on "." i.e. the origin of the coordinate system. + If desired the location of the slit can also be described relative to + an NXbeam, which will allow a simple description of a non-centred pinhole. + + The reference direction of the pinhole is parallel with the z axis. The reference + point of the pinhole is its center in the x and y axis. The reference point on the z axis is the + plane which overlaps the side of the opening of the pin hole pointing towards the source (minus on the z axis). + + .. image:: pinhole/pinhole.png + :width: 40% + diameter(NX_NUMBER): + unit: NX_LENGTH + doc: | + Size of the circular hole defining the transmitted beam size. + (NXtransformations): + exists: ['min', '0'] + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c70638ef9748cfd94d36132613305136639cd062a10e8771d7e78ba4f865dd85 +# +# +# +# +# +# A simple pinhole. +# +# For more complex geometries, :ref:`NXaperture` should be used. +# +# +# +# Points to the path of the last element in the geometry chain that places +# this object in space. +# When followed through that chain is supposed to end at an element depending +# on "." i.e. the origin of the coordinate system. +# If desired the location of the slit can also be described relative to +# an NXbeam, which will allow a simple description of a non-centred pinhole. +# +# The reference direction of the pinhole is parallel with the z axis. The reference +# point of the pinhole is its center in the x and y axis. The reference point on the z axis is the +# plane which overlaps the side of the opening of the pin hole pointing towards the source (minus on the z axis). +# +# .. image:: pinhole/pinhole.png +# :width: 40% +# +# +# +# +# Size of the circular hole defining the transmitted beam size. +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXpolarizer.yaml b/base_classes/nyaml/NXpolarizer.yaml new file mode 100644 index 0000000000..0380ddb99e --- /dev/null +++ b/base_classes/nyaml/NXpolarizer.yaml @@ -0,0 +1,135 @@ +category: base +doc: | + A spin polarizer. +type: group +NXpolarizer(NXobject): + type: + doc: | + one of these values: "crystal", "supermirror", "3He" + composition: + doc: | + description of the composition of the polarizing material + reflection(NX_INT): + unit: NX_UNITLESS + doc: | + [hkl] values of nominal reflection + dimensions: + dim: [[1, 3]] + efficiency(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + polarizing efficiency + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a polarizer. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 489a3377a505248d4d66e2c674c112f1eb6f8ca85c6f02fbedbe8b7ba40149d4 +# +# +# +# +# +# A spin polarizer. +# +# +# one of these values: "crystal", "supermirror", "3He" +# +# +# description of the composition of the polarizing material +# +# +# [hkl] values of nominal reflection +# +# +# +# +# +# polarizing efficiency +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a polarizer. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXpositioner.yaml b/base_classes/nyaml/NXpositioner.yaml new file mode 100644 index 0000000000..36178fda4e --- /dev/null +++ b/base_classes/nyaml/NXpositioner.yaml @@ -0,0 +1,200 @@ +category: base +doc: | + A generic positioner such as a motor or piezo-electric transducer. +type: group +NXpositioner(NXobject): + name: + doc: | + symbolic or mnemonic name (one word) + description: + doc: | + description of positioner + value(NX_NUMBER): + unit: NX_ANY + doc: | + best known value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + raw_value(NX_NUMBER): + unit: NX_ANY + doc: | + raw value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + target_value(NX_NUMBER): + unit: NX_ANY + doc: | + targeted (commanded) value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + tolerance(NX_NUMBER): + unit: NX_ANY + doc: | + maximum allowable difference between target_value and value + dimensions: + rank: 1 + dim: [[1, n]] + soft_limit_min(NX_NUMBER): + unit: NX_ANY + doc: | + minimum allowed limit to set value + soft_limit_max(NX_NUMBER): + unit: NX_ANY + doc: | + maximum allowed limit to set value + velocity(NX_NUMBER): + unit: NX_ANY + doc: | + velocity of the positioner (distance moved per unit time) + acceleration_time(NX_NUMBER): + unit: NX_ANY + doc: | + time to ramp the velocity up to full speed + + # TODO other parameters: settling time, backlash, link to readback channel + controller_record: + doc: | + Hardware device record, e.g. EPICS process variable, taco/tango ... + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a positioner. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9e3dc1962303ddef4d403e479bfde3b47cdd8a9fa15c57bf2fadfb6e55ff541f +# +# +# +# +# +# A generic positioner such as a motor or piezo-electric transducer. +# +# +# symbolic or mnemonic name (one word) +# +# +# description of positioner +# +# +# best known value of positioner - need [n] as may be scanned +# +# +# +# raw value of positioner - need [n] as may be scanned +# +# +# +# targeted (commanded) value of positioner - need [n] as may be scanned +# +# +# +# maximum allowable difference between target_value and value +# +# +# +# minimum allowed limit to set value +# +# +# maximum allowed limit to set value +# +# +# velocity of the positioner (distance moved per unit time) +# +# +# time to ramp the velocity up to full speed +# +# +# +# Hardware device record, e.g. EPICS process variable, taco/tango ... +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a positioner. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXprocess.yaml b/base_classes/nyaml/NXprocess.yaml new file mode 100644 index 0000000000..3dbc4ee78a --- /dev/null +++ b/base_classes/nyaml/NXprocess.yaml @@ -0,0 +1,138 @@ +category: base +doc: | + Document an event of data processing, reconstruction, or analysis for this data. +type: group +NXprocess(NXobject): + program(NX_CHAR): + doc: | + Name of the program used + sequence_index(NX_POSINT): + doc: | + Sequence index of processing, + for determining the order of multiple **NXprocess** steps. + Starts with 1. + version(NX_CHAR): + doc: | + Version of the program used + date(NX_DATE_TIME): + doc: | + Date and time of processing. + (NXregistration): + doc: | + Describes the operations of image registration + (NXdistortion): + doc: | + Describes the operations of image distortion correction + (NXcalibration): + doc: | + Describes the operations of calibration procedures, e.g. axis calibrations. + (NXnote): + doc: | + The note will contain information about how the data was processed + or anything about the data provenance. + The contents of the note can be anything that the processing code + can understand, or simple text. + + The name will be numbered to allow for ordering of steps. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# efb5f4cc611c1eb8c9de82497bd906c59a237a2ba2cc2bccaa74209af288d5ff +# +# +# +# +# +# Document an event of data processing, reconstruction, or analysis for this data. +# +# +# +# Name of the program used +# +# +# +# +# Sequence index of processing, +# for determining the order of multiple **NXprocess** steps. +# Starts with 1. +# +# +# +# +# Version of the program used +# +# +# +# +# Date and time of processing. +# +# +# +# +# Describes the operations of image registration +# +# +# +# +# Describes the operations of image distortion correction +# +# +# +# +# Describes the operations of calibration procedures, e.g. axis calibrations. +# +# +# +# +# The note will contain information about how the data was processed +# or anything about the data provenance. +# The contents of the note can be anything that the processing code +# can understand, or simple text. +# +# The name will be numbered to allow for ordering of steps. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXreflections.yaml b/base_classes/nyaml/NXreflections.yaml new file mode 100644 index 0000000000..83523acc75 --- /dev/null +++ b/base_classes/nyaml/NXreflections.yaml @@ -0,0 +1,1266 @@ +category: base +doc: | + Reflection data from diffraction experiments +symbols: + n: | + number of reflections + m: | + number of experiments +type: group +NXreflections(NXobject): + experiments: + exists: ['min', '1'] + doc: | + The experiments from which the reflection data derives + dimensions: + rank: 1 + dim: [[1, m]] + h(NX_NUMBER): + exists: ['min', '1'] + doc: | + The h component of the miller index + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + k(NX_NUMBER): + exists: ['min', '1'] + doc: | + The k component of the miller index + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + l(NX_NUMBER): + exists: ['min', '1'] + doc: | + The l component of the miller index + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + id(NX_INT): + exists: ['min', '1'] + doc: | + The id of the experiment which resulted in the reflection. If the value + is greater than 0, the experiments must link to a multi-experiment NXmx + group + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + reflection_id(NX_INT): + exists: ['min', '1'] + doc: | + The id of the reflection. Multiple partials from the same reflection + should all have the same id + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + entering(NX_BOOLEAN): + exists: ['min', '1'] + doc: | + Is the reflection entering or exiting the Ewald sphere + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + det_module(NX_INT): + exists: ['min', '1'] + doc: | + The detector module on which the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + flags(NX_INT): + exists: ['min', '1'] + doc: | + Status flags describing the reflection. + + This is a bit mask. The bits in the mask follow the convention + used by DIALS, and have the following names: + + === ========================================== + bit name + === ========================================== + 0 ``predicted`` + 1 ``observed`` + 2 ``indexed`` + 3 ``used_in_refinement`` + 4 ``strong`` + 5 ``reference_spot`` + 6 ``dont_integrate`` + 7 ``integrated_sum`` + 8 ``integrated_prf`` + 9 ``integrated`` + 10 ``overloaded`` + 11 ``overlapped`` + 12 ``overlapped_fg`` + 13 ``in_powder_ring`` + 14 ``foreground_includes_bad_pixels`` + 15 ``background_includes_bad_pixels`` + 16 ``includes_bad_pixels`` + 17 ``bad_shoebox`` + 18 ``bad_spot`` + 19 ``used_in_modelling`` + 20 ``centroid_outlier`` + 21 ``failed_during_background_modelling`` + 22 ``failed_during_summation`` + 23 ``failed_during_profile_fitting`` + 24 ``bad_reference`` + === ========================================== + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + d(NX_FLOAT): + exists: ['min', '1'] + doc: | + The resolution of the reflection + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + partiality(NX_FLOAT): + exists: ['min', '1'] + doc: | + The partiality of the reflection. + Dividing by this number will inflate the measured + intensity to the full reflection equivalent. + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_frame(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The frame on which the bragg peak of the reflection is predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_x(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The x position at which the bragg peak of the reflection + is predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_y(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The y position at which the bragg peak of the reflection + is predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_phi(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '1'] + doc: | + The phi angle at which the bragg peak of the reflection is predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_px_x(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The x pixel position at which the bragg peak of the reflection is + predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + predicted_px_y(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The y pixel position at which the bragg peak of the reflection is + predicted + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_frame(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The estimate of the frame at which the central impact of the + reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_frame_var(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The variance on the estimate of the frame at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_frame_errors(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the frame at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_x(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The estimate of the pixel x position at which the central impact of + the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_x_var(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The variance on the estimate of the pixel x position at which the + central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_x_errors(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the pixel x position at which the + central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_y(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The estimate of the pixel y position at which the central impact of + the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_y_var(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The variance on the estimate of the pixel y position at which the + central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_px_y_errors(NX_FLOAT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the pixel y position at which the + central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_phi(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '1'] + doc: | + The estimate of the phi angle at which the central impact of the + reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_phi_var(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '1'] + doc: | + The variance on the estimate of the phi angle at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_phi_errors(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the phi angle at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_x(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The estimate of the x position at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_x_var(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The variance on the estimate of the x position at which + the central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_x_errors(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the x position at which + the central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_y(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The estimate of the y position at which the central + impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_y_var(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The variance on the estimate of the y position at which + the central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + observed_y_errors(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the y position at which + the central impact of the reflection was recorded + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + bounding_box(NX_INT): + unit: NX_UNITLESS + exists: ['min', '1'] + doc: | + The bounding box around the recorded recorded reflection. + Should be an integer array of length 6, where the 6 values + are pixel positions or frame numbers, as follows: + + ===== =========================== + index meaning + ===== =========================== + 0 The lower pixel x position + 1 The upper pixel x position + 2 The lower pixel y position + 3 The upper pixel y position + 4 The lower frame number + 5 The upper frame number + ===== =========================== + dimensions: + rank: 2 + dim: [[1, n], [2, 6]] + \@description: + doc: | + Describes the dataset + background_mean(NX_FLOAT): + exists: ['min', '1'] + doc: | + The mean background under the reflection peak + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_prf(NX_FLOAT): + exists: ['min', '0'] + doc: | + The estimate of the reflection intensity by profile fitting + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_prf_var(NX_FLOAT): + exists: ['min', '0'] + doc: | + The variance on the estimate of the reflection intensity by profile + fitting + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_prf_errors(NX_FLOAT): + exists: ['min', '0'] + doc: | + The standard deviation of the estimate of the reflection intensity by profile + fitting + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_sum(NX_FLOAT): + exists: ['min', '1'] + doc: | + The estimate of the reflection intensity by summation + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_sum_var(NX_FLOAT): + exists: ['min', '1'] + doc: | + The variance on the estimate of the reflection intensity by + summation + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + int_sum_errors(NX_FLOAT): + exists: ['min', '1'] + doc: | + The standard deviation of the estimate of the reflection intensity by + summation + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + lp(NX_FLOAT): + exists: ['min', '1'] + doc: | + The LP correction factor to be applied to the reflection intensities + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + prf_cc(NX_FLOAT): + exists: ['min', '0'] + doc: | + The correlation of the reflection profile with the reference profile + used in profile fitting + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + overlaps(NX_INT): + exists: ['min', '0'] + doc: | + An adjacency list specifying the spatial overlaps of reflections. The + adjacency list is specified using an array data type where the elements + of the array are the indices of the adjacent overlapped reflection + \@description: + doc: | + Describes the dataset + polar_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + doc: | + Polar angle of reflection centroid, following the NeXus simple (spherical polar) coordinate system + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + exists: ['min', '0'] + doc: | + Azimuthal angle of reflection centroid, following the NeXus simple (spherical polar) coordinate system + dimensions: + rank: 1 + dim: [[1, n]] + \@description: + doc: | + Describes the dataset + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# f0dd5d59e2726272e3befd4fd88df46f824c4023d04a1a1775153f79260f5b7e +# +# +# +# +# +# number of reflections +# number of experiments +# +# Reflection data from diffraction experiments +# +# The experiments from which the reflection data derives +# +# +# +# +# +# +# The h component of the miller index +# +# +# +# +# Describes the dataset +# +# +# +# +# The k component of the miller index +# +# +# +# +# Describes the dataset +# +# +# +# +# The l component of the miller index +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The id of the experiment which resulted in the reflection. If the value +# is greater than 0, the experiments must link to a multi-experiment NXmx +# group +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The id of the reflection. Multiple partials from the same reflection +# should all have the same id +# +# +# +# +# +# Describes the dataset +# +# +# +# Is the reflection entering or exiting the Ewald sphere +# +# +# +# +# Describes the dataset +# +# +# +# +# The detector module on which the reflection was recorded +# +# +# +# +# Describes the dataset +# +# +# +# +# +# Status flags describing the reflection. +# +# This is a bit mask. The bits in the mask follow the convention +# used by DIALS, and have the following names: +# +# === ========================================== +# bit name +# === ========================================== +# 0 ``predicted`` +# 1 ``observed`` +# 2 ``indexed`` +# 3 ``used_in_refinement`` +# 4 ``strong`` +# 5 ``reference_spot`` +# 6 ``dont_integrate`` +# 7 ``integrated_sum`` +# 8 ``integrated_prf`` +# 9 ``integrated`` +# 10 ``overloaded`` +# 11 ``overlapped`` +# 12 ``overlapped_fg`` +# 13 ``in_powder_ring`` +# 14 ``foreground_includes_bad_pixels`` +# 15 ``background_includes_bad_pixels`` +# 16 ``includes_bad_pixels`` +# 17 ``bad_shoebox`` +# 18 ``bad_spot`` +# 19 ``used_in_modelling`` +# 20 ``centroid_outlier`` +# 21 ``failed_during_background_modelling`` +# 22 ``failed_during_summation`` +# 23 ``failed_during_profile_fitting`` +# 24 ``bad_reference`` +# === ========================================== +# +# +# +# +# +# Describes the dataset +# +# +# +# +# The resolution of the reflection +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The partiality of the reflection. +# Dividing by this number will inflate the measured +# intensity to the full reflection equivalent. +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The frame on which the bragg peak of the reflection is predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The x position at which the bragg peak of the reflection +# is predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The y position at which the bragg peak of the reflection +# is predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The phi angle at which the bragg peak of the reflection is predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The x pixel position at which the bragg peak of the reflection is +# predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The y pixel position at which the bragg peak of the reflection is +# predicted +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the frame at which the central impact of the +# reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the frame at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the frame at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the pixel x position at which the central impact of +# the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the pixel x position at which the +# central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the pixel x position at which the +# central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the pixel y position at which the central impact of +# the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the pixel y position at which the +# central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the pixel y position at which the +# central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the phi angle at which the central impact of the +# reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the phi angle at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the phi angle at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the x position at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the x position at which +# the central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the x position at which +# the central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the y position at which the central +# impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the y position at which +# the central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the y position at which +# the central impact of the reflection was recorded +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The bounding box around the recorded recorded reflection. +# Should be an integer array of length 6, where the 6 values +# are pixel positions or frame numbers, as follows: +# +# ===== =========================== +# index meaning +# ===== =========================== +# 0 The lower pixel x position +# 1 The upper pixel x position +# 2 The lower pixel y position +# 3 The upper pixel y position +# 4 The lower frame number +# 5 The upper frame number +# ===== =========================== +# +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The mean background under the reflection peak +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The estimate of the reflection intensity by profile fitting +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the reflection intensity by profile +# fitting +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the reflection intensity by profile +# fitting +# +# +# +# +# +# Describes the dataset +# +# +# +# The estimate of the reflection intensity by summation +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The variance on the estimate of the reflection intensity by +# summation +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The standard deviation of the estimate of the reflection intensity by +# summation +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The LP correction factor to be applied to the reflection intensities +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# The correlation of the reflection profile with the reference profile +# used in profile fitting +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# An adjacency list specifying the spatial overlaps of reflections. The +# adjacency list is specified using an array data type where the elements +# of the array are the indices of the adjacent overlapped reflection +# +# +# Describes the dataset +# +# +# +# +# +# Polar angle of reflection centroid, following the NeXus simple (spherical polar) coordinate system +# +# +# +# +# +# Describes the dataset +# +# +# +# +# +# Azimuthal angle of reflection centroid, following the NeXus simple (spherical polar) coordinate system +# +# +# +# +# +# +# Describes the dataset +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXroot.yaml b/base_classes/nyaml/NXroot.yaml new file mode 100644 index 0000000000..abba0910d6 --- /dev/null +++ b/base_classes/nyaml/NXroot.yaml @@ -0,0 +1,223 @@ +category: base +doc: | + Definition of the root NeXus group. +type: group +NXroot(NXobject): + \@NX_class: + doc: | + The root of any NeXus data file is an ``NXroot`` class + (no other choice is allowed for a valid NeXus data file). + This attribute cements that definition. + enumeration: [NXroot] + \@file_time: + type: NX_DATE_TIME + doc: | + Date and time file was originally created + \@file_name: + doc: | + File name of original NeXus file + \@file_update_time: + type: NX_DATE_TIME + doc: | + Date and time of last file change at close + \@NeXus_repository: + doc: | + A repository containing the application definitions + used for creating this file. + If the NeXus_version attribute contains a commit distance and hash + this should refer to this repository. + \@NeXus_version: + doc: | + Version of NeXus definitions used in writing the file. + This may either be a date based version tag of the form `vYYYY.MM` + or a version tag with a commit distance and source control (e.g., git) hash of + the form `vYYYY.MM.post1.dev.g`. + It may contain an additional `.dYYYYMMDD` timestamp appendix + for dirty repositories. + If the version contains a commit distance and hash the + NeXus_repository attribute should be written with the + repository url containing this version. + + Only used when the NAPI or pynxtools has written the file. + Note that this is different from the version of the + base class or application definition version number. + \@partial: + doc: | + A list of concepts in an application definition this file describes. + This is for partially filling an application definition. + If this attribute is not present the application definition is assumed + to be valid, if not only the specified concepts/paths are assumed to be valid. + \@HDF_version: + doc: | + Version of HDF (version 4) library used in writing the file + \@HDF5_Version: + doc: | + Version of HDF5 library used in writing the file. + + Note this attribute is spelled with uppercase "V", + different than other version attributes. + \@XML_version: + doc: | + Version of XML support library used in writing the XML file + \@h5py_version: + doc: | + Version of h5py Python package used in writing the file + \@creator: + doc: | + facility or program where file originated + \@creator_version: + doc: | + Version of facility or program used in writing the file + (NXentry): + exists: ['min', '1'] + doc: | + entries + \@default: + doc: | + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXentry` group contains + the data to be shown by default. + It is used to resolve ambiguity when + more than one :ref:`NXentry` group exists. + The value :ref:`names ` the default :ref:`NXentry` group. The + value must be the name of a child of the current group. The child must be a + NeXus group or a link to a NeXus group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 076e6c02e65767061d84e6f18bdef2d2caaf1c555f8ce414fd5744e68cc3685c +# +# +# +# +# +# Definition of the root NeXus group. +# +# +# +# The root of any NeXus data file is an ``NXroot`` class +# (no other choice is allowed for a valid NeXus data file). +# This attribute cements that definition. +# +# +# +# +# +# +# +# Date and time file was originally created +# +# +# +# +# File name of original NeXus file +# +# +# +# +# Date and time of last file change at close +# +# +# +# +# Version of NeXus API used in writing the file. +# +# Only used when the NAPI has written the file. +# Note that this is different from the version of the +# base class or application definition version number. +# +# +# +# +# A list of concepts in an application definition this file describes. +# This is for partially filling an application definition. +# If this attribute is not present the application definition is assumed +# to be valid, if not the specified concepts/paths are assumed to be valid. +# +# +# +# +# Version of HDF (version 4) library used in writing the file +# +# +# +# +# Version of HDF5 library used in writing the file. +# +# Note this attribute is spelled with uppercase "V", +# different than other version attributes. +# +# +# +# +# Version of XML support library used in writing the XML file +# +# +# +# +# Version of h5py Python package used in writing the file +# +# +# +# +# facility or program where file originated +# +# +# +# +# Version of facility or program used in writing the file +# +# +# +# +# entries +# +# +# +# +# .. index:: find the default plottable data +# .. index:: plotting +# .. index:: default attribute value +# +# Declares which :ref:`NXentry` group contains +# the data to be shown by default. +# It is used to resolve ambiguity when +# more than one :ref:`NXentry` group exists. +# The value :ref:`names <validItemName>` the default :ref:`NXentry` group. The +# value must be the name of a child of the current group. The child must be a +# NeXus group or a link to a NeXus group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXsample.yaml b/base_classes/nyaml/NXsample.yaml new file mode 100644 index 0000000000..10e80fc495 --- /dev/null +++ b/base_classes/nyaml/NXsample.yaml @@ -0,0 +1,948 @@ +category: base +doc: | + Any information on 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: + doc: | + 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 +type: group +NXsample(NXobject): + name: + doc: | + Descriptive name of sample + sample_id: + doc: | + Identification number or signatures of the sample used. + chemical_formula: + doc: | + 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. + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + Sample temperature. This could be a scanned variable + dimensions: + rank: anyRank + + # could be any length + dim: [[1, n_Temp]] + electric_field(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Applied electric field + dimensions: + + # could be any length + dim: [[1, n_eField]] + \@direction: + enumeration: [x, y, z] + magnetic_field(NX_FLOAT): + unit: NX_ANY + doc: | + Applied magnetic field + dimensions: + + # could be any length + dim: [[1, n_mField]] + \@direction: + enumeration: [x, y, z] + stress_field(NX_FLOAT): + unit: NX_ANY + doc: | + Applied external stress field + dimensions: + + # could be any length + dim: [[1, n_sField]] + \@direction: + enumeration: [x, y, z] + pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Applied pressure + dimensions: + + # could be any length + dim: [[1, n_pField]] + changer_position(NX_INT): + unit: NX_UNITLESS + doc: | + Sample changer position + unit_cell_abc(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell parameters a, b, and c + dimensions: + dim: [[1, 3]] + unit_cell_alphabetagamma(NX_FLOAT): + unit: NX_ANGLE + doc: | + Crystallography unit cell parameters alpha, beta, and gamma + dimensions: + dim: [[1, 3]] + unit_cell(NX_FLOAT): + unit: NX_LENGTH + doc: | + Unit cell parameters (lengths and angles) + dimensions: + rank: 2 + dim: [[1, n_comp], [2, 6]] + unit_cell_volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Volume of the unit cell + dimensions: + rank: 1 + dim: [[1, n_comp]] + sample_orientation(NX_FLOAT): + unit: NX_ANGLE + doc: | + This will follow the Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 1 + dim: [[1, 3]] + orientation_matrix(NX_FLOAT): + doc: | + Orientation matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 3 + dim: [[1, n_comp], [2, 3], [3, 3]] + ub_matrix(NX_FLOAT): + doc: | + UB matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is + the multiplication of the orientation_matrix, given above, + with the :math:`B` matrix which + can be derived from the lattice constants. + dimensions: + rank: 3 + dim: [[1, n_comp], [2, 3], [3, 3]] + mass(NX_FLOAT): + unit: NX_MASS + doc: | + Mass of sample + dimensions: + rank: 1 + dim: [[1, n_comp]] + density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + Density of sample + dimensions: + rank: 1 + dim: [[1, n_comp]] + relative_molecular_mass(NX_FLOAT): + unit: NX_MASS + doc: | + Relative Molecular Mass of sample + dimensions: + rank: 1 + dim: [[1, n_comp]] + type: + enumeration: [sample, sample+can, can, sample+buffer, buffer, calibration sample, normalisation sample, simulated data, none, sample environment] + situation: + doc: | + 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. + enumeration: [air, vacuum, inert atmosphere, oxidising atmosphere, reducing atmosphere, sealed can, other] + description: + doc: | + Description of the sample + preparation_date(NX_DATE_TIME): + doc: | + Date of preparation of the sample + geometry(NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the sample and NXoff_geometry to describe its shape instead + doc: | + The position and orientation of the center of mass of the sample + (NXbeam): + doc: | + Details of beam incident on sample - used to calculate sample/beam interaction + point + (NXsample_component): + doc: | + One group per sample component + This is the perferred way of recording per component information over the n_comp arrays + component: + doc: | + Details of the component of the sample and/or can + dimensions: + rank: 1 + dim: [[1, n_comp]] + sample_component: + doc: | + Type of component + dimensions: + rank: 1 + dim: [[1, n_comp]] + enumeration: [sample, can, atmosphere, kit] + concentration(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + Concentration of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + volume_fraction(NX_FLOAT): + doc: | + Volume fraction of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + scattering_length_density(NX_FLOAT): + unit: NX_SCATTERING_LENGTH_DENSITY + doc: | + Scattering length density of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + unit_cell_class: + doc: | + In case it is all we know and we want to record/document it + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + space_group: + doc: | + Crystallographic space group + dimensions: + dim: [[1, n_comp]] + point_group: + doc: | + Crystallographic point group, deprecated if space_group present + dimensions: + dim: [[1, n_comp]] + path_length(NX_FLOAT): + unit: NX_LENGTH + doc: | + Path length through sample/can for simple case when + it does not vary with scattering direction + path_length_window(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of a beam entry/exit window on the can (mm) + - assumed same for entry and exit + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + sample thickness + transmission(NXdata): + doc: | + As a function of Wavelength + temperature_log(NXlog): + deprecated: | + use ``temperature``, see: https://github.com/nexusformat/definitions/issues/816 + doc: | + temperature_log.value is a link to e.g. temperature_env.sensor1.value_log.value + temperature_env(NXenvironment): + doc: | + Additional sample temperature environment information + magnetic_field(NXlog): + doc: | + magnetic_field.value is a link to e.g. magnetic_field_env.sensor1.value + magnetic_field_log(NXlog): + deprecated: | + use ``magnetic_field``, see: https://github.com/nexusformat/definitions/issues/816 + doc: | + magnetic_field_log.value is a link to e.g. + magnetic_field_env.sensor1.value_log.value + magnetic_field_env(NXenvironment): + doc: | + Additional sample magnetic environment information + external_DAC(NX_FLOAT): + unit: NX_ANY + doc: | + value sent to user's sample setup + external_ADC(NXlog): + doc: | + logged value (or logic state) read from user's setup + short_title: + doc: | + 20 character fixed length sample description for legends + + # How is the string length limitation imposed by the XSD? + rotation_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + 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. + Note, it is recommended to use NXtransformations instead. + x_translation(NX_FLOAT): + unit: NX_LENGTH + doc: | + Translation of the sample along the X-direction of the laboratory coordinate system + Note, it is recommended to use NXtransformations instead. + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Translation of the sample along the Z-direction of the laboratory coordinate system. + Note, it is recommended to use NXtransformations instead. + (NXpositioner): + doc: | + Any positioner (motor, PZT, ...) used to locate the sample + (NXoff_geometry): + + # exists: ['min', '0'] + doc: | + This group describes the shape of the sample + physical_form: + doc: | + Physical form of the sample material. + Examples include single crystal, foil, pellet, powder, thin film, disc, foam, gas, liquid, amorphous. + (NXsingle_crystal): + doc: | + If the sample is a single crystal, add description of single crystal and unit + cell. + (NXsample_component_set): + doc: | + Set of sample components and their configuration. + There can only be one NXsample_component_set in one component. + + # exists: [max, 1] + (NXsubstance): + doc: | + If the sample is made from a pure substance and cannot be further divided using + NXsample_component. + + # exists: [max, 1] + (NXfabrication): + doc: | + Details about the sample vendor (company or research group) + (NXenvironment): + + # eventually, this should be stored in the application definitions + doc: | + Any environmental or external stimuli/measurements. + These can include, among others: + applied pressure, surrounding gas phase and gas pressure, + external electric/magnetic/mechanical fields, temperature, ... + (NXsample_history): + doc: | + A set of physical processes that occurred to the sample prior/during experiment. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on: + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ac20245dbd19e3a8e9c8a002a60f8cb13541fe586265ecf52a72e691b1f28fe2 +# +# +# +# +# +# +# symbolic array lengths to be coordinated between various fields +# +# +# +# number of compositions +# +# +# +# +# number of temperatures +# +# +# +# +# number of values in applied electric field +# +# +# +# +# number of values in applied magnetic field +# +# +# +# +# number of values in applied pressure field +# +# +# +# +# number of values in applied stress field +# +# +# +# +# Any information on 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. +# +# +# +# Descriptive name of sample +# +# +# +# +# Identification number or signatures of the sample used. +# +# +# +# +# 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. +# +# +# +# +# Sample temperature. This could be a scanned variable +# +# +# +# +# +# +# +# +# Applied electric field +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Applied magnetic field +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Applied external stress field +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Applied pressure +# +# +# +# +# +# +# +# +# Sample changer position +# +# +# +# +# Crystallography unit cell parameters a, b, and c +# +# +# +# +# +# +# +# Crystallography unit cell parameters alpha, beta, and gamma +# +# +# +# +# +# +# +# Unit cell parameters (lengths and angles) +# +# +# +# +# +# +# +# +# Volume of the unit cell +# +# +# +# +# +# +# +# This will follow the Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# Orientation matrix of single crystal sample using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# +# +# UB matrix of single crystal sample using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is +# the multiplication of the orientation_matrix, given above, +# with the :math:`B` matrix which +# can be derived from the lattice constants. +# +# +# +# +# +# +# +# +# +# Mass of sample +# +# +# +# +# +# +# +# Density of sample +# +# +# +# +# +# +# +# Relative Molecular Mass of sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Description of the sample +# +# +# +# +# Date of preparation of the sample +# +# +# +# +# The position and orientation of the center of mass of the sample +# +# +# +# +# Details of beam incident on sample - used to calculate sample/beam interaction +# point +# +# +# +# +# One group per sample component +# This is the perferred way of recording per component information over the n_comp arrays +# +# +# +# +# Details of the component of the sample and/or can +# +# +# +# +# +# +# +# Type of component +# +# +# +# +# +# +# +# +# +# +# +# +# +# Concentration of each component +# +# +# +# +# +# +# +# Volume fraction of each component +# +# +# +# +# +# +# +# Scattering length density of each component +# +# +# +# +# +# +# +# In case it is all we know and we want to record/document it +# +# +# +# +# +# +# +# +# +# +# +# +# +# Crystallographic space group +# +# +# +# +# +# +# +# Crystallographic point group, deprecated if space_group present +# +# +# +# +# +# +# +# Path length through sample/can for simple case when +# it does not vary with scattering direction +# +# +# +# +# Thickness of a beam entry/exit window on the can (mm) +# - assumed same for entry and exit +# +# +# +# +# sample thickness +# +# +# +# +# As a function of Wavelength +# +# +# +# +# temperature_log.value is a link to e.g. temperature_env.sensor1.value_log.value +# +# +# +# +# Additional sample temperature environment information +# +# +# +# +# magnetic_field.value is a link to e.g. magnetic_field_env.sensor1.value +# +# +# +# +# magnetic_field_log.value is a link to e.g. +# magnetic_field_env.sensor1.value_log.value +# +# +# +# +# Additional sample magnetic environment information +# +# +# +# +# value sent to user's sample setup +# +# +# +# +# logged value (or logic state) read from user's setup +# +# +# +# +# 20 character fixed length sample description for legends +# +# +# +# +# +# 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. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# Translation of the sample along the X-direction of the laboratory coordinate system +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# Translation of the sample along the Z-direction of the laboratory coordinate system. +# Note, it is recommended to use NXtransformations instead. +# +# +# +# +# Any positioner (motor, PZT, ...) used to locate the sample +# +# +# +# +# +# This group describes the shape of the sample +# +# +# +# +# Physical form of the sample material. +# Examples include single crystal, foil, pellet, powder, thin film, disc, foam, gas, liquid, amorphous. +# +# +# +# +# If the sample is a single crystal, add description of single crystal and unit +# cell. +# +# +# +# +# Set of sample components and their configuration. +# There can only be one NXsample_component_set in one component. +# +# +# +# +# +# If the sample is made from a pure substance and cannot be further divided using +# NXsample_component. +# +# +# +# +# +# Details about the sample vendor (company or research group) +# +# +# +# +# +# Any environmental or external stimuli/measurements. +# These can include, among others: +# applied pressure, surrounding gas phase and gas pressure, +# external electric/magnetic/mechanical fields, temperature, ... +# +# +# +# +# A set of physical processes that occurred to the sample prior/during experiment. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXsample_component.yaml b/base_classes/nyaml/NXsample_component.yaml new file mode 100644 index 0000000000..15dc89ad20 --- /dev/null +++ b/base_classes/nyaml/NXsample_component.yaml @@ -0,0 +1,392 @@ +category: base +doc: | + One group like this per component can be recorded For a sample consisting of + multiple components. +symbols: + doc: | + symbolic array lengths to be coordinated between various fields + 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 +type: group +NXsample_component(NXobject): + name: + doc: | + Descriptive name of sample component + sample_id: + doc: | + Identification number or signatures of the sample component used. + chemical_formula: + doc: | + 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. + unit_cell_abc(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell parameters a, b, and c + dimensions: + dim: [[1, 3]] + unit_cell_alphabetagamma(NX_FLOAT): + unit: NX_ANGLE + doc: | + Crystallography unit cell parameters alpha, beta, and gamma + dimensions: + dim: [[1, 3]] + unit_cell_volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Volume of the unit cell + sample_orientation(NX_FLOAT): + unit: NX_ANGLE + doc: | + This will follow the Busing and Levy convention from Acta.Crysta v22, p457 + (1967) + dimensions: + rank: 1 + dim: [[1, 3]] + orientation_matrix(NX_FLOAT): + doc: | + Orientation matrix of single crystal sample component. + This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967) + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + mass(NX_FLOAT): + unit: NX_MASS + doc: | + Mass of sample component + density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + Density of sample component + relative_molecular_mass(NX_FLOAT): + unit: NX_MASS + doc: | + Relative Molecular Mass of sample component + description: + doc: | + Description of the sample component + volume_fraction(NX_FLOAT): + doc: | + Volume fraction of component + scattering_length_density(NX_FLOAT): + unit: NX_SCATTERING_LENGTH_DENSITY + doc: | + Scattering length density of component + unit_cell_class: + doc: | + In case it is all we know and we want to record/document it + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + space_group: + doc: | + Crystallographic space group + point_group: + doc: | + Crystallographic point group, deprecated if space_group present + transmission(NXdata): + doc: | + As a function of Wavelength + (NXsingle_crystal): + doc: | + If the component is a single crystal, add description of single crystal and unit + cell. + (NXsample_component_set): + doc: | + Set of sub-components and their configuration. + There can only be one NXsample_component_set in one component. + + # exists: [max, 1] + (NXsubstance): + doc: | + If the component is made from a pure substance and cannot be further divided + using NXsample_component. + + # exists: [max, 1] + (NXfabrication): + doc: | + Details about the sample component vendor (company or research group) + (NXsample_history): + doc: | + A set of physical processes that occurred to the sample component prior/during + experiment. + depends_on: + doc: | + Any NXsample_component depends on the instance of NXsample_component_set, at the same level of + description granularity where the component is located. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 07c4e31c308138182eef1cdddefda26ba6c879da8df45c3f0b03213996fc8fcb +# +# +# +# +# +# +# symbolic array lengths to be coordinated between various fields +# +# +# +# number of temperatures +# +# +# +# +# number of values in applied electric field +# +# +# +# +# number of values in applied magnetic field +# +# +# +# +# number of values in applied pressure field +# +# +# +# +# number of values in applied stress field +# +# +# +# +# One group like this per component can be recorded For a sample consisting of +# multiple components. +# +# +# +# Descriptive name of sample component +# +# +# +# +# Identification number or signatures of the sample component used. +# +# +# +# +# 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. +# +# +# +# +# Crystallography unit cell parameters a, b, and c +# +# +# +# +# +# +# +# Crystallography unit cell parameters alpha, beta, and gamma +# +# +# +# +# +# +# +# Volume of the unit cell +# +# +# +# +# This will follow the Busing and Levy convention from Acta.Crysta v22, p457 +# (1967) +# +# +# +# +# +# +# +# Orientation matrix of single crystal sample component. +# This will follow the Busing and Levy convention from Acta.Crysta v22, p457 (1967) +# +# +# +# +# +# +# +# +# Mass of sample component +# +# +# +# +# Density of sample component +# +# +# +# +# Relative Molecular Mass of sample component +# +# +# +# +# Description of the sample component +# +# +# +# +# Volume fraction of component +# +# +# +# +# Scattering length density of component +# +# +# +# +# In case it is all we know and we want to record/document it +# +# +# +# +# +# +# +# +# +# +# +# +# +# Crystallographic space group +# +# +# +# +# Crystallographic point group, deprecated if space_group present +# +# +# +# +# As a function of Wavelength +# +# +# +# +# If the component is a single crystal, add description of single crystal and unit +# cell. +# +# +# +# +# Set of sub-components and their configuration. +# There can only be one NXsample_component_set in one component. +# +# +# +# +# +# If the component is made from a pure substance and cannot be further divided +# using NXsample_component. +# +# +# +# +# +# Details about the sample component vendor (company or research group) +# +# +# +# +# A set of physical processes that occurred to the sample component prior/during +# experiment. +# +# +# +# +# Any NXsample_component depends on the instance of NXsample_component_set, at the same level of +# description granularity where the component is located. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/base_classes/nyaml/NXsensor.yaml b/base_classes/nyaml/NXsensor.yaml new file mode 100644 index 0000000000..fa5fcafbcd --- /dev/null +++ b/base_classes/nyaml/NXsensor.yaml @@ -0,0 +1,340 @@ +category: base +doc: | + A sensor used to monitor an external condition + + The condition itself is described in :ref:`NXenvironment`. +type: group +NXsensor(NXobject): + model: + doc: | + Sensor identification code/model number + name: + doc: | + Name for the sensor + short_name: + doc: | + Short name of sensor used e.g. on monitor display program + attached_to: + doc: | + where sensor is attached to ("sample" | "can") + geometry(NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the beamstop and NXoff_geometry to describe its shape instead + doc: | + Defines the axes for logged vector quantities if they are not the global + instrument axes. + measurement: + doc: | + name for measured signal + enumeration: [temperature, pH, magnetic_field, electric_field, current, conductivity, resistance, voltage, pressure, flow, stress, strain, shear, surface_pressure] + type: + doc: | + The type of hardware used for the measurement. + Examples (suggestions but not restrictions): + + :Temperature: + J | K | T | E | R | S | Pt100 | Rh/Fe + :pH: + Hg/Hg2Cl2 | Ag/AgCl | ISFET + :Ion selective electrode: + specify species; e.g. Ca2+ + :Magnetic field: + Hall + :Surface pressure: + wilhelmy plate + run_control(NX_BOOLEAN): + doc: | + Is data collection controlled or synchronised to this quantity: + 1=no, 0=to "value", 1=to "value_deriv1", etc. + high_trip_value(NX_FLOAT): + unit: NX_ANY + doc: | + Upper control bound of sensor reading if using run_control + low_trip_value(NX_FLOAT): + unit: NX_ANY + doc: | + Lower control bound of sensor reading if using run_control + value(NX_FLOAT): + unit: NX_ANY + doc: | + nominal setpoint or average value + - need [n] as may be a vector + dimensions: + dim: [[1, n]] + value_deriv1(NX_FLOAT): + unit: NX_ANY + doc: | + Nominal/average first derivative of value + e.g. strain rate + - same dimensions as "value" (may be a vector) + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['value'] + value_deriv2(NX_FLOAT): + unit: NX_ANY + doc: | + Nominal/average second derivative of value + - same dimensions as "value" (may be a vector) + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['value'] + value_log(NXlog): + doc: | + Time history of sensor readings + value_deriv1_log(NXlog): + doc: | + Time history of first derivative of sensor readings + value_deriv2_log(NXlog): + doc: | + Time history of second derivative of sensor readings + external_field_brief: + enumeration: [along beam, across beam, transverse, solenoidal, flow shear gradient, flow vorticity] + external_field_full(NXorientation): + doc: | + For complex external fields not satisfied by External_field_brief + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the sensor when necessary. + (NXfabrication): + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a sensor. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6d710cebca8ca188bc40cc8ca1c26df9636e44cac48b28289cc2228e8876828c +# +# +# +# +# +# A sensor used to monitor an external condition +# +# The condition itself is described in :ref:`NXenvironment`. +# +# +# +# Sensor identification code/model number +# +# +# +# +# Name for the sensor +# +# +# +# +# Short name of sensor used e.g. on monitor display program +# +# +# +# +# where sensor is attached to ("sample" | "can") +# +# +# +# +# Defines the axes for logged vector quantities if they are not the global +# instrument axes. +# +# +# +# +# name for measured signal +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The type of hardware used for the measurement. +# Examples (suggestions but not restrictions): +# +# :Temperature: +# J | K | T | E | R | S | Pt100 | Rh/Fe +# :pH: +# Hg/Hg2Cl2 | Ag/AgCl | ISFET +# :Ion selective electrode: +# specify species; e.g. Ca2+ +# :Magnetic field: +# Hall +# :Surface pressure: +# wilhelmy plate +# +# +# +# +# Is data collection controlled or synchronised to this quantity: +# 1=no, 0=to "value", 1=to "value_deriv1", etc. +# +# +# +# +# Upper control bound of sensor reading if using run_control +# +# +# +# +# Lower control bound of sensor reading if using run_control +# +# +# +# +# nominal setpoint or average value +# - need [n] as may be a vector +# +# +# +# +# +# +# +# Nominal/average first derivative of value +# e.g. strain rate +# - same dimensions as "value" (may be a vector) +# +# +# +# +# +# +# +# Nominal/average second derivative of value +# - same dimensions as "value" (may be a vector) +# +# +# +# +# +# +# +# Time history of sensor readings +# +# +# +# +# Time history of first derivative of sensor readings +# +# +# +# +# Time history of second derivative of sensor readings +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# For complex external fields not satisfied by External_field_brief +# +# +# +# +# This group describes the shape of the sensor when necessary. +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a sensor. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXshape.yaml b/base_classes/nyaml/NXshape.yaml new file mode 100644 index 0000000000..f5222b30de --- /dev/null +++ b/base_classes/nyaml/NXshape.yaml @@ -0,0 +1,143 @@ +category: base +doc: | + legacy class - (used by :ref:`NXgeometry`) - the shape and size of a component. + + This is the description of the general shape and size of a + component, which may be made up of ``numobj`` separate + elements - it is used by the :ref:`NXgeometry` class +type: group +NXshape(NXobject): + shape: + doc: | + general shape of a component + enumeration: [nxflat, nxcylinder, nxbox, nxsphere, nxcone, nxelliptical, nxtoroidal, nxparabolic, nxpolynomial] + size(NX_FLOAT): + unit: NX_LENGTH + doc: | + physical extent of the object along its local axes (after NXorientation) + with the center of mass at the local origin (after NXtranslation). + The meaning and location of these axes will vary according to the value + of the "shape" variable. + ``nshapepar`` defines how many parameters: + + - For "nxcylinder" type the parameters are (diameter,height) and a three value orientation vector of the cylinder. + - For the "nxbox" type the parameters are (length,width,height). + - For the "nxsphere" type the parameters are (diameter). + - For nxcone cone half aperture + - For nxelliptical, semi-major axis, semi-minor-axis, angle of major axis and pole + - For nxtoroidal, major radius, minor radius + - For nxparabolic, parabolic parameter a + - For nxpolynomial, an array of polynom coefficients, the dimension of the array + encodes the degree of the polynom + dimensions: + dim: [[1, numobj], [2, nshapepar]] + direction: + enumeration: [concave, convex] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c273b2f18be61f791d2fc4da9ecefbb880d180a9f83536ad161f2f685127f209 +# +# +# +# +# +# legacy class - (used by :ref:`NXgeometry`) - the shape and size of a component. +# +# This is the description of the general shape and size of a +# component, which may be made up of ``numobj`` separate +# elements - it is used by the :ref:`NXgeometry` class +# +# +# general shape of a component +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# physical extent of the object along its local axes (after NXorientation) +# with the center of mass at the local origin (after NXtranslation). +# The meaning and location of these axes will vary according to the value +# of the "shape" variable. +# ``nshapepar`` defines how many parameters: +# +# - For "nxcylinder" type the parameters are (diameter,height) and a three value orientation vector of the cylinder. +# - For the "nxbox" type the parameters are (length,width,height). +# - For the "nxsphere" type the parameters are (diameter). +# - For nxcone cone half aperture +# - For nxelliptical, semi-major axis, semi-minor-axis, angle of major axis and pole +# - For nxtoroidal, major radius, minor radius +# - For nxparabolic, parabolic parameter a +# - For nxpolynomial, an array of polynom coefficients, the dimension of the array +# encodes the degree of the polynom +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXslit.yaml b/base_classes/nyaml/NXslit.yaml new file mode 100644 index 0000000000..364a1c539c --- /dev/null +++ b/base_classes/nyaml/NXslit.yaml @@ -0,0 +1,141 @@ +category: base +doc: | + A simple slit. + + For more complex geometries, :ref:`NXaperture` should be used. +type: group +NXslit(NXobject): + depends_on(NX_CHAR): + doc: | + Points to the path of the last element in the geometry chain that places + this object in space. + When followed through that chain is supposed to end at an element depending + on "." i.e. the origin of the coordinate system. + If desired the location of the slit can also be described relative to + an NXbeam, which will allow a simple description of a non-centred slit. + + The reference plane of the slit is orthogonal to the z axis and includes the + surface that is the entry surface of the slit. The reference point of the slit + is the centre of the slit opening in the x and y axis on the reference plane. + The reference point on the z axis is the reference plane. + + .. image:: slit/slit.png + :width: 40% + x_gap(NX_NUMBER): + unit: NX_LENGTH + doc: | + Size of the gap opening in the first dimension of the local + coordinate system. + y_gap(NX_NUMBER): + unit: NX_LENGTH + doc: | + Size of the gap opening in the second dimension of the local + coordinate system. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 417ccad73271f355d1d59bfad75b0a0622636749a18b54e8d6f71ec54a968203 +# +# +# +# +# +# A simple slit. +# +# For more complex geometries, :ref:`NXaperture` should be used. +# +# +# +# Points to the path of the last element in the geometry chain that places +# this object in space. +# When followed through that chain is supposed to end at an element depending +# on "." i.e. the origin of the coordinate system. +# If desired the location of the slit can also be described relative to +# an NXbeam, which will allow a simple description of a non-centred slit. +# +# The reference plane of the slit is orthogonal to the z axis and includes the +# surface that is the entry surface of the slit. The reference point of the slit +# is the centre of the slit opening in the x and y axis on the reference plane. +# The reference point on the z axis is the reference plane. +# +# .. image:: slit/slit.png +# :width: 40% +# +# +# +# +# +# Size of the gap opening in the first dimension of the local +# coordinate system. +# +# +# +# +# Size of the gap opening in the second dimension of the local +# coordinate system. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXsource.yaml b/base_classes/nyaml/NXsource.yaml new file mode 100644 index 0000000000..96788835f7 --- /dev/null +++ b/base_classes/nyaml/NXsource.yaml @@ -0,0 +1,529 @@ +category: base +doc: | + Radiation source emitting a beam. + + Examples include particle sources (electrons, neutrons, protons) or sources for electromagnetic radiation (photons). + This base class can also be used to describe neutron or x-ray storage ring/facilities. +type: group +NXsource(NXobject): + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Effective distance from sample + Distance as seen by radiation from sample. This number should be negative + to signify that it is upstream of the sample. + name: + doc: | + Name of source + \@short_name: + doc: | + short name for source, perhaps the acronym + type: + doc: | + type of radiation source (pick one from the enumerated list and spell exactly) + enumeration: [Spallation Neutron Source, Pulsed Reactor Neutron Source, Reactor Neutron Source, Synchrotron X-ray Source, Pulsed Muon Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Free-Electron Laser, Optical Laser, Ion Source, UV Plasma Source, Metal Jet X-ray] + probe: + doc: | + type of radiation probe (pick one from the enumerated list and spell exactly) + enumeration: [neutron, photon, x-ray, muon, electron, ultraviolet, visible light, positron, proton] + power(NX_FLOAT): + unit: NX_POWER + doc: | + Source power + emittance_x(NX_FLOAT): + unit: NX_EMITTANCE + doc: | + Source emittance (nm-rad) in X (horizontal) direction. + emittance_y(NX_FLOAT): + unit: NX_EMITTANCE + doc: | + Source emittance (nm-rad) in Y (horizontal) direction. + sigma_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + particle beam size in x + sigma_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + particle beam size in y + flux(NX_FLOAT): + unit: NX_FLUX + doc: | + Source intensity/area (example: s-1 cm-2) + energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Source energy. + For storage rings, this would be the particle beam energy. + For X-ray tubes, this would be the excitation voltage. + current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Accelerator, X-ray tube, or storage ring current + voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Accelerator voltage + frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Frequency of pulsed source + period(NX_FLOAT): + unit: NX_PERIOD + doc: | + Period of pulsed source + target_material: + doc: | + Pulsed source target material + enumeration: [Ta, W, depleted_U, enriched_U, Hg, Pb, C] + notes(NXnote): + doc: | + any source/facility related messages/events that + occurred during the experiment + bunch_pattern(NXdata): + doc: | + For storage rings, description of the bunch pattern. + This is useful to describe irregular bunch patterns. + title: + doc: | + name of the bunch pattern + number_of_bunches(NX_INT): + doc: | + For storage rings, the number of bunches in use. + bunch_length(NX_FLOAT): + unit: NX_TIME + doc: | + For storage rings, temporal length of the bunch + bunch_distance(NX_FLOAT): + unit: NX_TIME + doc: | + For storage rings, time between bunches + pulse_width(NX_FLOAT): + unit: NX_TIME + doc: | + temporal width of source pulse + + # pulsed sources or storage rings could use this + pulse_shape(NXdata): + doc: | + source pulse shape + + # pulsed sources or storage rings could use this + mode: + doc: | + source operating mode + enumeration: + Single Bunch: + doc: | + for storage rings + Multi Bunch: + doc: | + for storage rings + + # other sources could add to this + + # other sources could add to this + top_up(NX_BOOLEAN): + doc: | + Is the synchrotron operating in top_up mode? + last_fill(NX_NUMBER): + unit: NX_CURRENT + doc: | + For storage rings, the current at the end of the most recent injection. + \@time: + type: NX_DATE_TIME + doc: | + date and time of the most recent injection. + photon_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + The center photon energy of the source, before it is + monochromatized or converted + center_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + The center wavelength of the source, before it is + monochromatized or converted + pulse_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + For pulsed sources, the energy of a single pulse + peak_power(NX_FLOAT): + unit: NX_POWER + doc: | + For pulsed sources, the pulse energy divided + by the pulse duration + bunch_number_start(NX_INT): + doc: | + Some facilities tag each bunch. + First bunch of the measurement + bunch_number_end(NX_INT): + doc: | + Last bunch of the measurement + geometry(NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the source and NXoff_geometry to describe its shape instead + doc: | + "Engineering" location of source. + (NXfabrication): + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + distribution(NXdata): + doc: | + The wavelength or energy distribution of the source + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the + z axis. + + .. image:: source/source.png + :width: 40% + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0a6a307ccc9631e05a65861861127ee26e09fdb3e8b72eaa99bcc24fb0572d39 +# +# +# +# +# +# Radiation source emitting a beam. +# +# Examples include particle sources (electrons, neutrons, protons) or sources for electromagnetic radiation (photons). +# This base class can also be used to describe neutron or x-ray storage ring/facilities. +# +# +# +# Effective distance from sample +# Distance as seen by radiation from sample. This number should be negative +# to signify that it is upstream of the sample. +# +# +# +# +# Name of source +# +# +# +# short name for source, perhaps the acronym +# +# +# +# +# +# type of radiation source (pick one from the enumerated list and spell exactly) +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# type of radiation probe (pick one from the enumerated list and spell exactly) +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Source power +# +# +# +# +# Source emittance (nm-rad) in X (horizontal) direction. +# +# +# +# +# Source emittance (nm-rad) in Y (horizontal) direction. +# +# +# +# +# particle beam size in x +# +# +# +# +# particle beam size in y +# +# +# +# +# Source intensity/area (example: s-1 cm-2) +# +# +# +# +# Source energy. +# For storage rings, this would be the particle beam energy. +# For X-ray tubes, this would be the excitation voltage. +# +# +# +# +# Accelerator, X-ray tube, or storage ring current +# +# +# +# +# Accelerator voltage +# +# +# +# +# Frequency of pulsed source +# +# +# +# +# Period of pulsed source +# +# +# +# +# Pulsed source target material +# +# +# +# +# +# +# +# +# +# +# +# +# +# any source/facility related messages/events that +# occurred during the experiment +# +# +# +# +# For storage rings, description of the bunch pattern. +# This is useful to describe irregular bunch patterns. +# +# +# +# name of the bunch pattern +# +# +# +# +# +# For storage rings, the number of bunches in use. +# +# +# +# +# For storage rings, temporal length of the bunch +# +# +# +# +# For storage rings, time between bunches +# +# +# +# +# temporal width of source pulse +# +# +# +# +# +# source pulse shape +# +# +# +# +# +# source operating mode +# +# +# +# +# for storage rings +# +# +# +# +# for storage rings +# +# +# +# +# +# +# +# +# Is the synchrotron operating in top_up mode? +# +# +# +# +# For storage rings, the current at the end of the most recent injection. +# +# +# +# date and time of the most recent injection. +# +# +# +# +# +# The center photon energy of the source, before it is +# monochromatized or converted +# +# +# +# +# The center wavelength of the source, before it is +# monochromatized or converted +# +# +# +# +# For pulsed sources, the energy of a single pulse +# +# +# +# +# For pulsed sources, the pulse energy divided +# by the pulse duration +# +# +# +# +# Some facilities tag each bunch. +# First bunch of the measurement +# +# +# +# +# Last bunch of the measurement +# +# +# +# +# "Engineering" location of source. +# +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# The wavelength or energy distribution of the source +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the +# z axis. +# +# .. image:: source/source.png +# :width: 40% +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/base_classes/nyaml/NXsubentry.yaml b/base_classes/nyaml/NXsubentry.yaml new file mode 100644 index 0000000000..248111e211 --- /dev/null +++ b/base_classes/nyaml/NXsubentry.yaml @@ -0,0 +1,344 @@ +category: base +doc: | + Group of multiple application definitions for "multi-modal" (e.g. SAXS/WAXS) measurements. + + ``NXsubentry`` is a base class virtually identical to :ref:`NXentry` + and is used as the (overlay) location for application definitions. + Use a separate ``NXsubentry`` for each application definition. + + To use ``NXsubentry`` with a hypothetical application definition + called ``NXmyappdef``: + + * Create a group with attribute ``NX_class="NXsubentry"`` + * Within that group, create a field called ``definition="NXmyappdef"``. + * There are two optional attributes of definition: ``version`` and ``URL`` + + The intended use is to define application definitions for a + multi-modal (a.k.a. multi-technique) :ref:`NXentry`. + Previously, an application definition + replaced :ref:`NXentry` with its own definition. + With the increasing popularity of instruments combining + multiple techniques for data collection (such as SAXS/WAXS instruments), + it was recognized the application definitions must be entered in the NeXus + data file tree as children of :ref:`NXentry`. +type: group +NXsubentry(NXobject): + \@default: + doc: | + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXdata` group contains the data + to be shown by default. + It is used to resolve ambiguity when + one :ref:`NXdata` group exists. + The value :ref:`names ` the default :ref:`NXentry` group. The + value must be the name of a child of the current group. The child must be a + NeXus group or a link to a NeXus group. + + For more information about how NeXus identifies the default + plottable data, see the + :ref:`Find Plottable Data, v3 ` + section. + \@IDF_Version: + + # as ratified at NIAC2010 + doc: | + ISIS Muon IDF_Version + title: + doc: | + Extended title for entry + experiment_identifier: + doc: | + Unique identifier for the experiment, defined by + the facility, possibly linked to the proposals + experiment_description: + doc: | + Brief summary of the experiment, including key objectives. + (NXnote)experiment_documentation: + doc: | + Description of the full experiment (document in pdf, latex, ...) + collection_identifier: + doc: | + User or Data Acquisition defined group of NeXus files or :ref:`NXentry` + collection_description: + doc: | + Brief summary of the collection, including grouping criteria. + entry_identifier: + doc: | + unique identifier for the measurement, defined by the facility. + definition: + doc: | + Official NeXus NXDL schema to which this subentry conforms + \@version: + doc: | + NXDL version number + \@URL: + doc: | + URL of NXDL file + definition_local: + doc: | + Local NXDL schema extended from the subentry + specified in the ``definition`` field. + This contains any locally-defined, + additional fields in the subentry. + \@version: + doc: | + NXDL version number + \@URL: + doc: | + URL of NXDL file + start_time(NX_DATE_TIME): + doc: | + Starting time of measurement + end_time(NX_DATE_TIME): + doc: | + Ending time of measurement + duration(NX_INT): + unit: NX_TIME + doc: | + Duration of measurement + collection_time(NX_FLOAT): + unit: NX_TIME + doc: | + Time transpired actually collecting data i.e. taking out time when collection was + suspended due to e.g. temperature out of range + run_cycle: + doc: | + Such as "2007-3". Some user facilities organize their beam time into run cycles. + program_name: + doc: | + Name of program used to generate this file + \@version: + doc: | + Program version number + \@configuration: + doc: | + configuration of the program + revision: + doc: | + Revision id of the file due to re-calibration, reprocessing, new analysis, new + instrument definition format, ... + \@comment: + pre_sample_flightpath(NX_FLOAT): + unit: NX_LENGTH + doc: | + This is the flightpath before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + notes(NXnote): + doc: | + Notes describing entry + thumbnail(NXnote): + doc: | + A small image that is representative of the entry. An example of this is a 640x480 + jpeg image automatically produced by a low resolution plot of the NXdata. + \@mime_type: + doc: | + The value should be an ``image/*`` + + # This is not perfect. + # How do we set a default value for the mime_type attribute? + enumeration: [image/*] + (NXuser): + (NXsample): + (NXinstrument): + (NXcollection): + (NXmonitor): + (NXdata): + (NXparameters): + (NXprocess): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 73d58acb9360e8891346fefd2018fc630e5216eb27617d7dc5aec05808025224 +# +# +# +# +# +# +# +# .. index:: find the default plottable data +# .. index:: plotting +# .. index:: default attribute value +# +# Declares which :ref:`NXdata` group contains the data +# to be shown by default. +# It is used to resolve ambiguity when +# one :ref:`NXdata` group exists. +# The value :ref:`names <validItemName>` the default :ref:`NXentry` group. The +# value must be the name of a child of the current group. The child must be a +# NeXus group or a link to a NeXus group. +# +# For more information about how NeXus identifies the default +# plottable data, see the +# :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` +# section. +# +# +# +# +# Group of multiple application definitions for "multi-modal" (e.g. SAXS/WAXS) measurements. +# +# ``NXsubentry`` is a base class virtually identical to :ref:`NXentry` +# and is used as the (overlay) location for application definitions. +# Use a separate ``NXsubentry`` for each application definition. +# +# To use ``NXsubentry`` with a hypothetical application definition +# called ``NXmyappdef``: +# +# * Create a group with attribute ``NX_class="NXsubentry"`` +# * Within that group, create a field called ``definition="NXmyappdef"``. +# * There are two optional attributes of definition: ``version`` and ``URL`` +# +# The intended use is to define application definitions for a +# multi-modal (a.k.a. multi-technique) :ref:`NXentry`. +# Previously, an application definition +# replaced :ref:`NXentry` with its own definition. +# With the increasing popularity of instruments combining +# multiple techniques for data collection (such as SAXS/WAXS instruments), +# it was recognized the application definitions must be entered in the NeXus +# data file tree as children of :ref:`NXentry`. +# +# +# +# +# ISIS Muon IDF_Version +# +# +# +# Extended title for entry +# +# +# +# Unique identifier for the experiment, defined by +# the facility, possibly linked to the proposals +# +# +# +# Brief summary of the experiment, including key objectives. +# +# +# Description of the full experiment (document in pdf, latex, ...) +# +# +# User or Data Acquisition defined group of NeXus files or :ref:`NXentry` +# +# +# Brief summary of the collection, including grouping criteria. +# +# +# unique identifier for the measurement, defined by the facility. +# +# +# Official NeXus NXDL schema to which this subentry conforms +# NXDL version number +# URL of NXDL file +# +# +# +# Local NXDL schema extended from the subentry +# specified in the ``definition`` field. +# This contains any locally-defined, +# additional fields in the subentry. +# +# NXDL version number +# URL of NXDL file +# +# +# Starting time of measurement +# +# +# Ending time of measurement +# +# +# Duration of measurement +# +# +# +# Time transpired actually collecting data i.e. taking out time when collection was +# suspended due to e.g. temperature out of range +# +# +# +# Such as "2007-3". Some user facilities organize their beam time into run cycles. +# +# +# Name of program used to generate this file +# Program version number +# configuration of the program +# +# +# +# Revision id of the file due to re-calibration, reprocessing, new analysis, new +# instrument definition format, ... +# +# +# +# +# +# This is the flightpath before the sample position. This can be determined by a chopper, +# by the moderator or the source itself. In other words: it the distance to the component +# which gives the T0 signal to the detector electronics. If another component in the +# NXinstrument hierarchy provides this information, this should be a link. +# +# +# +# Notes describing entry +# +# +# +# A small image that is representative of the entry. An example of this is a 640x480 +# jpeg image automatically produced by a low resolution plot of the NXdata. +# +# +# The value should be an ``image/*`` +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXtransformations.yaml b/base_classes/nyaml/NXtransformations.yaml new file mode 100644 index 0000000000..501633cb7d --- /dev/null +++ b/base_classes/nyaml/NXtransformations.yaml @@ -0,0 +1,715 @@ +category: base +doc: | + 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 + type specified, but are useful in understanding coordinate frames within which + transformations are done, or in documenting important directions, such as the + direction of gravity. + + A nested sequence of transformations lists the translation 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. Transformations can also be described by NXlog groups when + the values change with time. 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 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 :ref:`McSTAS coordinate frame` + is assumed, but additional useful coordinate axes may be defined by using axes for which + no transformation type has been specified. + + **Transformation chain** + + The entry point of a chain of transformations is a field called ``depends_on`` + will be outside of this class and points 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` + which in turn depends on :math:`T_3`, the final *active* transformation + matrix :math:`T_f` is + + .. math:: T_f = T_3 . T_2 . T_1 + + For example when positioning a flat detector, its pixel positions in the laboratory + reference frame (:ref:`McSTAS coordinate frame` by default) + can be calculated by + + .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} + + Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first + to the pixel coordinates. + + When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that + the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. + So the activate coordinate transformation :math:`A` needs to be applied to a coordinate + before applying :math:`B`. In other words :math:`X' = B . A . X`. + + **Transformation matrix** + + In explicit terms, the transformations are a subset of affine transformations expressed as + 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. + + For rotation and translation, + + .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} + + 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 by 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. + + **Usage** + + One possible use of ``NXtransformations`` is to define the motors and + transformations for a diffractometer (goniometer). Such use is mentioned + in the ``NXinstrument`` base class. Use one ``NXtransformations`` group + for each diffractometer and name the group appropriate to the device. + Collecting the motors of a sample table or xyz-stage in an NXtransformations + group is equally possible. + + Following the section on the general description of axis in NXtransformations is a section which + documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever + there is a need for positioning a beam line component please use the existing names. Use as many fields + as needed in order to position the component. Feel free to add more axis if required. In the description + given below, only those atttributes which are defined through the name are spcified. Add the other attributes + of the full set: + + * vector + * offset + * transformation_type + * depends_on + + as needed. + + **Example 1: goniometer** + + Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame`. + + The sample is oriented as follows + + .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . + T(\vec{v}_z, \text{sam}_z) . + T(\vec{v}_y, \text{sam}_y) . + T(\vec{v}_x, \text{sam}_x) . + R(\vec{v}_\chi, \chi) . + R(\vec{v}_\varphi, \varphi) . X_s + + where + + * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` + * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` + * :math:`X_s` a coordinate in the sample reference frame. + + .. code-block:: + + entry:NXentry + sample:NXsample + depends_on=transformations/phi + transformations:NXtransformations + phi=0 + @depends_on=chi + @transformation_type=rotation + @vector=[-1 -0.0037 -0.002] + @units=degrees + chi=0 + @depends_on=sam_x + @transformation_type=rotation + @vector=[0.0046 0.0372 0.9993] + @units=degrees + sam_x=0 + @depends_on=sam_y + @transformation_type=translation + @vector=[1 0 0] + @units=mm + sam_y=0 + @depends_on=sam_z + @transformation_type=translation + @vector=[0 1 0] + @units=mm + sam_z=0 + @depends_on=omega + @transformation_type=translation + @vector=[0 0 1] + @units=mm + omega=174 + @depends_on=. + @transformation_type=rotation + @vector=[-1 0 0] + @units=degrees + + **Example 2: different coordinate system** + + Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. + Three point detectors are positioned in this reference: + + * *transmission*: + * point detector in the beam + * 20 cm downstream from the sample (the origin of the reference frame) + * *vertical*: + * point detector 10 cm downstream from the sample + * making an angle of 5 degrees with the beam w.r.t. the sample + * positioned in the XZ-plane above the XY-plane + * *horizontal*: + * point detector 11 cm downstream from the sample + * making an angle of 6 degrees with the beam w.r.t. the sample + * positioned in the XY-plane above the XZ-plane + + The coordinates of the point detectors in the laboratory reference frame are + + * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` + * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` + * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` + + where + + * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes + * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes + * :math:`X_d` is a coordinate in the detector reference frame. + + Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. + + .. code-block:: + + entry:NXentry + instrument:NXinstrument + vertical:NXdetector + depends_on=position/distance + position:NXtransformations + distance=10 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=5 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=0 # stay in the vertical plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + horizontal:NXdetector + depends_on=position/distance + position:NXtransformations + distance=11 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=6 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=90 # rotate to the horizontal plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + transmission:NXdetector + depends_on=position/distance + position:NXtransformations + distance=20 # move downstream from the sample + @depends_on=/entry/coordinate_system/beam + @units=cm + @vector=[1 0 0] + coordinate_system:NXtransformations + beam=NaN # value is never used + @depends_on=gravity + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up +type: group +ignoreExtraGroups: true +ignoreExtraFields: true +ignoreExtraAttributes: true +NXtransformations(NXobject): + AXISNAME(NX_NUMBER): + nameType: any + unit: NX_TRANSFORMATION + exists: ['max', 'unbounded'] + doc: | + Units need to be appropriate for translation or rotation + + The name of this field is not forced. The user is free to use any name + 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``. + \@transformation_type: + exists: optional + doc: | + 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 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. + + # + enumeration: [translation, rotation] + \@vector: + exists: optional + type: NX_NUMBER + doc: | + Three values that define the axis for this transformation. + The axis should be normalized to unit length, making it + dimensionless. For ``rotation`` axes, the direction should be + chosen for a right-handed rotation with increasing angle. + For ``translation`` axes the direction should be chosen for + increasing displacement. For general axes, an appropriate direction + should be chosen. + dimensions: + rank: 1 + dim: [[1, 3]] + \@offset: + type: NX_NUMBER + doc: | + A fixed offset applied before the transformation (three vector components). + This is not intended to be a substitute for a fixed ``translation`` axis but, for example, + as the mechanical offset from mounting the axis to its dependency. + dimensions: + rank: 1 + dim: [[1, 3]] + \@offset_units: + type: NX_CHAR + doc: | + Units of the offset. Values should be consistent with NX_LENGTH. + \@depends_on: + type: NX_CHAR + doc: | + Points to the path to a field defining the axis on which this + depends or the string "." when at the end of the chain. + \@equipment_component: + type: NX_CHAR + doc: | + An arbitrary identifier of a component of the equipment to which + the transformation belongs, such as 'detector_arm' or 'detector_module'. + NXtransformations with the same equipment_component label form a logical + grouping which can be combined together into a single change-of-basis + operation. + AXISNAME_end(NX_NUMBER): + unit: NX_TRANSFORMATION + nameType: any + exists: ['min', '0'] + doc: | + ``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(NX_NUMBER): + unit: NX_TRANSFORMATION + nameType: any + exists: ['min', '0'] + doc: | + ``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 + corresponding values of ``AXISNAME_end``, but there is a possibility of significant + differences. Use of ``AXISNAME_end`` is recommended. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6a1dc796e67a81292ff555a4e73fd6d2e67769d83ddb0686e193f8f7b1ccfef0 +# +# +# +# +# +# +# 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 +# type specified, but are useful in understanding coordinate frames within which +# transformations are done, or in documenting important directions, such as the +# direction of gravity. +# +# A nested sequence of transformations lists the translation 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. Transformations can also be described by NXlog groups when +# the values change with time. 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 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 :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` +# is assumed, but additional useful coordinate axes may be defined by using axes for which +# no transformation type has been specified. +# +# **Transformation chain** +# +# The entry point of a chain of transformations is a field called ``depends_on`` +# will be outside of this class and points 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` +# which in turn depends on :math:`T_3`, the final *active* transformation +# matrix :math:`T_f` is +# +# .. math:: T_f = T_3 . T_2 . T_1 +# +# For example when positioning a flat detector, its pixel positions in the laboratory +# reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) +# can be calculated by +# +# .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} +# +# Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first +# to the pixel coordinates. +# +# When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that +# the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. +# So the activate coordinate transformation :math:`A` needs to be applied to a coordinate +# before applying :math:`B`. In other words :math:`X' = B . A . X`. +# +# **Transformation matrix** +# +# In explicit terms, the transformations are a subset of affine transformations expressed as +# 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. +# +# For rotation and translation, +# +# .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} +# +# 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 by 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. +# +# **Usage** +# +# One possible use of ``NXtransformations`` is to define the motors and +# transformations for a diffractometer (goniometer). Such use is mentioned +# in the ``NXinstrument`` base class. Use one ``NXtransformations`` group +# for each diffractometer and name the group appropriate to the device. +# Collecting the motors of a sample table or xyz-stage in an NXtransformations +# group is equally possible. +# +# Following the section on the general description of axis in NXtransformations is a section which +# documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever +# there is a need for positioning a beam line component please use the existing names. Use as many fields +# as needed in order to position the component. Feel free to add more axis if required. In the description +# given below, only those atttributes which are defined through the name are spcified. Add the other attributes +# of the full set: +# +# * vector +# * offset +# * transformation_type +# * depends_on +# +# as needed. +# +# **Example 1: goniometer** +# +# Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. +# +# The sample is oriented as follows +# +# .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . +# T(\vec{v}_z, \text{sam}_z) . +# T(\vec{v}_y, \text{sam}_y) . +# T(\vec{v}_x, \text{sam}_x) . +# R(\vec{v}_\chi, \chi) . +# R(\vec{v}_\varphi, \varphi) . X_s +# +# where +# +# * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` +# * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` +# * :math:`X_s` a coordinate in the sample reference frame. +# +# .. code-block:: +# +# entry:NXentry +# sample:NXsample +# depends_on=transformations/phi +# transformations:NXtransformations +# phi=0 +# @depends_on=chi +# @transformation_type=rotation +# @vector=[-1 -0.0037 -0.002] +# @units=degrees +# chi=0 +# @depends_on=sam_x +# @transformation_type=rotation +# @vector=[0.0046 0.0372 0.9993] +# @units=degrees +# sam_x=0 +# @depends_on=sam_y +# @transformation_type=translation +# @vector=[1 0 0] +# @units=mm +# sam_y=0 +# @depends_on=sam_z +# @transformation_type=translation +# @vector=[0 1 0] +# @units=mm +# sam_z=0 +# @depends_on=omega +# @transformation_type=translation +# @vector=[0 0 1] +# @units=mm +# omega=174 +# @depends_on=. +# @transformation_type=rotation +# @vector=[-1 0 0] +# @units=degrees +# +# **Example 2: different coordinate system** +# +# Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. +# Three point detectors are positioned in this reference: +# +# * *transmission*: +# * point detector in the beam +# * 20 cm downstream from the sample (the origin of the reference frame) +# * *vertical*: +# * point detector 10 cm downstream from the sample +# * making an angle of 5 degrees with the beam w.r.t. the sample +# * positioned in the XZ-plane above the XY-plane +# * *horizontal*: +# * point detector 11 cm downstream from the sample +# * making an angle of 6 degrees with the beam w.r.t. the sample +# * positioned in the XY-plane above the XZ-plane +# +# The coordinates of the point detectors in the laboratory reference frame are +# +# * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` +# * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` +# * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` +# +# where +# +# * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes +# * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes +# * :math:`X_d` is a coordinate in the detector reference frame. +# +# Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. +# +# .. code-block:: +# +# entry:NXentry +# instrument:NXinstrument +# vertical:NXdetector +# depends_on=position/distance +# position:NXtransformations +# distance=10 # move downstream from the sample +# @depends_on=polar +# @units=cm +# @vector=[1 0 0] +# polar=5 # title above the horizontal plane +# @depends_on=azimuth +# @units=degrees +# @vector=[0 -1 0] +# azimuth=0 # stay in the vertical plane +# @depends_on=/entry/coordinate_system/beam +# @units=degrees +# @vector=[-1 0 0] +# horizontal:NXdetector +# depends_on=position/distance +# position:NXtransformations +# distance=11 # move downstream from the sample +# @depends_on=polar +# @units=cm +# @vector=[1 0 0] +# polar=6 # title above the horizontal plane +# @depends_on=azimuth +# @units=degrees +# @vector=[0 -1 0] +# azimuth=90 # rotate to the horizontal plane +# @depends_on=/entry/coordinate_system/beam +# @units=degrees +# @vector=[-1 0 0] +# transmission:NXdetector +# depends_on=position/distance +# position:NXtransformations +# distance=20 # move downstream from the sample +# @depends_on=/entry/coordinate_system/beam +# @units=cm +# @vector=[1 0 0] +# coordinate_system:NXtransformations +# beam=NaN # value is never used +# @depends_on=gravity +# @vector=[1 0 0] # X-axis points in the beam direction +# gravity=NaN # value is never used +# @depends_on=. # end of the chain +# @vector=[0 0 -1] # Z-axis points up +# +# +# +# +# Units need to be appropriate for translation or rotation +# +# The name of this field is not forced. The user is free to use any name +# 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``. +# +# +# +# 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 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. +# +# +# +# +# +# +# +# +# +# Three values that define the axis for this transformation. +# The axis should be normalized to unit length, making it +# dimensionless. For ``rotation`` axes, the direction should be +# chosen for a right-handed rotation with increasing angle. +# For ``translation`` axes the direction should be chosen for +# increasing displacement. For general axes, an appropriate direction +# should be chosen. +# +# +# +# +# +# +# +# A fixed offset applied before the transformation (three vector components). +# This is not intended to be a substitute for a fixed ``translation`` axis but, for example, +# as the mechanical offset from mounting the axis to its dependency. +# +# +# +# +# +# +# +# Units of the offset. Values should be consistent with NX_LENGTH. +# +# +# +# +# Points to the path to a field defining the axis on which this +# depends or the string "." when at the end of the chain. +# +# +# +# +# An arbitrary identifier of a component of the equipment to which +# the transformation belongs, such as 'detector_arm' or 'detector_module'. +# NXtransformations with the same equipment_component label form a logical +# grouping which can be combined together into a single change-of-basis +# operation. +# +# +# +# +# +# ``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 +# corresponding values of ``AXISNAME_end``, but there is a possibility of significant +# differences. Use of ``AXISNAME_end`` is recommended. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# \ No newline at end of file diff --git a/base_classes/nyaml/NXtranslation.yaml b/base_classes/nyaml/NXtranslation.yaml new file mode 100644 index 0000000000..99b08fc4fe --- /dev/null +++ b/base_classes/nyaml/NXtranslation.yaml @@ -0,0 +1,102 @@ +category: base +doc: | + legacy class - (used by :ref:`NXgeometry`) - general spatial location of a component. +type: group +NXtranslation(NXobject): + geometry(NXgeometry): + doc: | + Link to other object if we are relative, else absent + distances(NX_FLOAT): + unit: NX_LENGTH + doc: | + (x,y,z) + This field describes the lateral movement of a component. + The pair of groups NXtranslation and NXorientation together + describe the position of a component. + For absolute position, the origin is the scattering center (where a perfectly + aligned sample would be) with the z-axis pointing downstream and the y-axis + pointing gravitationally up. For a relative position the NXtranslation is + taken into account before the NXorientation. The axes are right-handed and + orthonormal. + dimensions: + dim: [[1, numobj], [2, 3]] + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3d64610ba1f1776cf277b5aca7e63bf3e504ed9a3f558bf28241565df29d6cc1 +# +# +# +# +# +# legacy class - (used by :ref:`NXgeometry`) - general spatial location of a component. +# +# +# Link to other object if we are relative, else absent +# +# +# +# (x,y,z) +# This field describes the lateral movement of a component. +# The pair of groups NXtranslation and NXorientation together +# describe the position of a component. +# For absolute position, the origin is the scattering center (where a perfectly +# aligned sample would be) with the z-axis pointing downstream and the y-axis +# pointing gravitationally up. For a relative position the NXtranslation is +# taken into account before the NXorientation. The axes are right-handed and +# orthonormal. +# +# +# +# +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXuser.yaml b/base_classes/nyaml/NXuser.yaml new file mode 100644 index 0000000000..383a8e9d17 --- /dev/null +++ b/base_classes/nyaml/NXuser.yaml @@ -0,0 +1,145 @@ +category: base +doc: | + Contact information for a user. + + The format allows more + than one user with the same affiliation and contact information, + but a second :ref:`NXuser` group should be used if they have different + affiliations, etc. +type: group +NXuser(NXobject): + name: + doc: | + Name of user responsible for this entry + role: + doc: | + Role of user responsible for this entry. + Suggested roles are "local_contact", + "principal_investigator", and "proposer" + affiliation: + doc: | + Affiliation of user + address: + doc: | + Address of user + telephone_number: + doc: | + Telephone number of user + fax_number: + doc: | + Fax number of user + email: + doc: | + Email of user + facility_user_id: + doc: | + facility based unique identifier for this person + e.g. their identification code on the facility + address/contact database + ORCID: + doc: | + an author code, Open Researcher and Contributor ID, + defined by https://orcid.org and expressed as a URI + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 095127b2420c5cc3523306d64ff34d05b413ff6c5aa8b3fcb470cba610d93e6a +# +# +# +# +# +# Contact information for a user. +# +# The format allows more +# than one user with the same affiliation and contact information, +# but a second :ref:`NXuser` group should be used if they have different +# affiliations, etc. +# +# +# Name of user responsible for this entry +# +# +# +# Role of user responsible for this entry. +# Suggested roles are "local_contact", +# "principal_investigator", and "proposer" +# +# +# +# Affiliation of user +# +# +# Address of user +# +# +# Telephone number of user +# +# +# Fax number of user +# +# +# Email of user +# +# +# +# facility based unique identifier for this person +# e.g. their identification code on the facility +# address/contact database +# +# +# +# +# an author code, Open Researcher and Contributor ID, +# defined by https://orcid.org and expressed as a URI +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# diff --git a/base_classes/nyaml/NXvelocity_selector.yaml b/base_classes/nyaml/NXvelocity_selector.yaml new file mode 100644 index 0000000000..fdfa162b96 --- /dev/null +++ b/base_classes/nyaml/NXvelocity_selector.yaml @@ -0,0 +1,198 @@ +category: base +doc: | + A neutron velocity selector +type: group +NXvelocity_selector(NXobject): + type: + doc: | + velocity selector type + rotation_speed(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + velocity selector rotation speed + radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + radius at beam centre + spwidth(NX_FLOAT): + unit: NX_LENGTH + doc: | + spoke width at beam centre + length(NX_FLOAT): + unit: NX_LENGTH + doc: | + rotor length + num(NX_INT): + unit: NX_UNITLESS + doc: | + number of spokes/lamella + twist(NX_FLOAT): + unit: NX_ANGLE + doc: | + twist angle along axis + table(NX_FLOAT): + unit: NX_ANGLE + doc: | + offset vertical angle + height(NX_FLOAT): + unit: NX_LENGTH + doc: | + input beam height + width(NX_FLOAT): + unit: NX_LENGTH + doc: | + input beam width + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + wavelength + wavelength_spread(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + deviation FWHM /Wavelength + (NXgeometry)geometry: + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the velocity selector and NXoff_geometry to describe its shape instead + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a velocity selector. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 61472a40691792e17964faecd4c6ebba73b460c2519fe2b0a97f7d46e51d6c08 +# +# +# +# +# A neutron velocity selector +# +# velocity selector type +# +# +# velocity selector rotation speed +# +# +# radius at beam centre +# +# +# spoke width at beam centre +# +# +# rotor length +# +# +# number of spokes/lamella +# +# +# twist angle along axis +# +# +# offset vertical angle +# +# +# input beam height +# +# +# input beam width +# +# +# wavelength +# +# +# deviation FWHM /Wavelength +# +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a velocity selector. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/base_classes/nyaml/NXxraylens.yaml b/base_classes/nyaml/NXxraylens.yaml new file mode 100644 index 0000000000..f08f4867fc --- /dev/null +++ b/base_classes/nyaml/NXxraylens.yaml @@ -0,0 +1,220 @@ +category: base +doc: | + An X-ray lens, typically at a synchrotron X-ray beam line. + + Based on information provided by Gerd Wellenreuther (DESY). +type: group +NXxraylens(NXobject): + lens_geometry(NX_CHAR): + doc: | + Geometry of the lens + enumeration: [paraboloid, spherical, elliptical, hyperbolical] + symmetric(NX_BOOLEAN): + doc: | + Is the device symmetric? + cylindrical(NX_BOOLEAN): + doc: | + Is the device cylindrical? + cylinder_orientation(NXnote): + doc: | + Orientation of the cylinder axis. + focus_type(NX_CHAR): + doc: | + The type of focus of the lens + enumeration: [line, point] + lens_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the lens + lens_length(NX_FLOAT): + unit: NX_LENGTH + doc: | + Length of the lens + curvature(NX_FLOAT): + unit: NX_LENGTH + doc: | + Radius of the curvature as measured in the middle of the lens + aperture(NX_FLOAT): + unit: NX_LENGTH + doc: | + Diameter of the lens. + number_of_lenses(NX_INT): + doc: | + Number of lenses that make up the compound lens. + lens_material(NX_CHAR): + doc: | + Material used to make the lens. + gas(NX_CHAR): + doc: | + Gas used to fill the lens + gas_pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Gas pressure in the lens + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the beam line component + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a x-ray lens. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 289923b77926b2d3ad18298238dbafdbb5bb6f038e6d25947224cd1e39a0c04d +# +# +# +# +# +# +# An X-ray lens, typically at a synchrotron X-ray beam line. +# +# Based on information provided by Gerd Wellenreuther (DESY). +# +# +# Geometry of the lens +# +# +# +# +# +# +# +# +# +# Is the device symmetric? +# +# +# +# +# Is the device cylindrical? +# +# +# +# +# Orientation of the cylinder axis. +# +# +# +# +# The type of focus of the lens +# +# +# +# +# +# +# +# Thickness of the lens +# +# +# Length of the lens +# +# +# Radius of the curvature as measured in the middle of the lens +# +# +# Diameter of the lens. +# +# +# Number of lenses that make up the compound lens. +# +# +# Material used to make the lens. +# +# +# Gas used to fill the lens +# +# +# Gas pressure in the lens +# +# +# +# This group describes the shape of the beam line component +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a x-ray lens. +# +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# diff --git a/common/favicon.ico b/common/favicon.ico new file mode 100644 index 0000000000..20fba88d3b Binary files /dev/null and b/common/favicon.ico differ diff --git a/contributed_definitions/NXaberration.nxdl.xml b/contributed_definitions/NXaberration.nxdl.xml index 0b3a8a5632..da4ea10dee 100644 --- a/contributed_definitions/NXaberration.nxdl.xml +++ b/contributed_definitions/NXaberration.nxdl.xml @@ -1,79 +1,69 @@ - + - + + - Models for aberrations of electro-magnetic lenses in electron microscopy. - - The notation follows `O. Krivanek et al. (1999) <https://doi.org/10.1016/S0304-3991(99)00013-3>`_ - and `O. Krivanek et al. (2003) <https://doi.org/10.1016/S0304-3991(03)00090-1>`_ - See also `S. J. Pennycock and P. D. Nellist <https://doi.org/10.1007/978-1-4419-7200-2>`_ (page 44ff, and page 118ff) - for further details, additional literature, and the unit of the coefficients. - Consult Table 7-2 of Ibid. publication on how to convert between - conventions of different groups/vendors. + Quantified aberration coefficient in an aberration_model. - + - Defocus + Value of the aberration coefficient. - + - Two-fold astigmatism + Uncertainty of the value of the aberration coefficient + according to uncertainty_model. - + - Two-fold astigmatism + How was the uncertainty quantified e.g. via the 95% confidence interval + and using which algorithm or statistical model. - + - Second-order axial coma + Time elapsed since the last measurement. - + - Second-order axial coma + For the CEOS definitions the C aberrations are radial-symmetric and have + no angle entry, while the A, B, D, S, or R aberrations are n-fold + symmetric and have an angle entry. + For the NION definitions the coordinate system differs to the one + used in CEOS and instead two aberration coefficients a and b are used. - + - Threefold astigmatism + Given name to this aberration. - + - Threefold astigmatism - - - - - Spherical aberration - - - - - Star aberration - - - - - Star aberration - - - - - Fourfold astigmatism - - - - - Fourfold astigmatism - - - - - Fifth-order spherical aberration + Alias also used to name and refer to this specific type of aberration. diff --git a/contributed_definitions/NXaberration_model.nxdl.xml b/contributed_definitions/NXaberration_model.nxdl.xml new file mode 100644 index 0000000000..67a975cc6b --- /dev/null +++ b/contributed_definitions/NXaberration_model.nxdl.xml @@ -0,0 +1,40 @@ + + + + + + Models for aberrations of electro-magnetic lenses in electron microscopy. + + See `S. J. Pennycock and P. D. Nellist <https://doi.org/10.1007/978-1-4419-7200-2>`_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the Nion to the + CEOS definitions. + + + + + + + + + diff --git a/contributed_definitions/NXaberration_model_ceos.nxdl.xml b/contributed_definitions/NXaberration_model_ceos.nxdl.xml new file mode 100644 index 0000000000..3325e1569a --- /dev/null +++ b/contributed_definitions/NXaberration_model_ceos.nxdl.xml @@ -0,0 +1,92 @@ + + + + + + CEOS definitions/model for aberrations of electro-magnetic lenses. + + See `S. J. Pennycock and P. D. Nellist <https://doi.org/10.1007/978-1-4419-7200-2>`_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the NION to the + CEOS definitions. + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXaberration_model_nion.nxdl.xml b/contributed_definitions/NXaberration_model_nion.nxdl.xml new file mode 100644 index 0000000000..8903c73db2 --- /dev/null +++ b/contributed_definitions/NXaberration_model_nion.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + Nion definitions/model for aberrations of electro-magnetic lenses. + + See `S. J. Pennycock and P. D. Nellist <https://doi.org/10.1007/978-1-4419-7200-2>`_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the Nion to the + CEOS definitions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXactivity.nxdl.xml b/contributed_definitions/NXactivity.nxdl.xml new file mode 100644 index 0000000000..5125bebf3b --- /dev/null +++ b/contributed_definitions/NXactivity.nxdl.xml @@ -0,0 +1,56 @@ + + + + + + A planned or unplanned action that has a temporal extension and for some time depends on some entity. + + This class is planned be used in the future as the super class for all other activities if inheritance + in base classes is supported in NeXus. + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this activity started. + + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this activity ended. + + + + + Short description of the activity. + + + + + This can be any data or other descriptor acquired during the activity + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + + + diff --git a/contributed_definitions/NXactuator.nxdl.xml b/contributed_definitions/NXactuator.nxdl.xml new file mode 100644 index 0000000000..e647a7fb82 --- /dev/null +++ b/contributed_definitions/NXactuator.nxdl.xml @@ -0,0 +1,114 @@ + + + + + + An actuator used to control an external condition. + + The condition itself is described in :ref:`NXenvironment`. + + + + Actuator identification code/model number + + + + + Name of the actuator + + + + + Short name of actuator used e.g. on monitor display program + + + + + Describe where the actuator is attached to. + This could be an instance of NXsample or a device on NXinstrument. + + + + + Name for the physical quantity effected by the actuation + + Examples: + temperature | pH | magnetic_field | electric_field | current | conductivity | resistance | voltage | + pressure | flow | stress | strain | shear | surface_pressure + + + + + The type of hardware used for the actuation. + + Examples (suggestions, but not restrictions): + + :Temperature: laser | gas lamp | filament | resistive + :Pressure: anvil cell + :Voltage: potentiostat + + + + + Any output that the actuator produces. + For example, a heater can have the field heater_power(NX_FLOAT). + + + + + Time history of actuator outputs. + + + + + If the actuator is PID-controlled, the settings of the PID controller can be + stored here. + + + + Nominal actuator setpoint. + Can be a scalar or a vector (of [n] actuations). + + + + + Time history of actuator setpoints. + + + + + + Refers to the last transformation specifying the position of the actuator + in the NXtransformations chain. + + + + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the actuator within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + + + diff --git a/contributed_definitions/NXadc.nxdl.xml b/contributed_definitions/NXadc.nxdl.xml new file mode 100644 index 0000000000..498c27dbaf --- /dev/null +++ b/contributed_definitions/NXadc.nxdl.xml @@ -0,0 +1,38 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Analog-to-digital converter component/integrated circuit. + + + + TBD. + + + diff --git a/contributed_definitions/NXamplifier.nxdl.xml b/contributed_definitions/NXamplifier.nxdl.xml new file mode 100644 index 0000000000..c9b719a7b1 --- /dev/null +++ b/contributed_definitions/NXamplifier.nxdl.xml @@ -0,0 +1,91 @@ + + + + + + Base classed definition for amplifier devices. + + + + (IC, device) (NXmanufacturer?) + + + + + The number of preamplifier channels are assgined. + + + + + The number of preamplifier channels are ready tp to be used. (array for active + channels) + + + + + The output signal does not go through a feedback loop to adjust the + amplification of the amplifier. (array for active channels) + + + + + + The ratio of the amplitue of the useful signal to the amplitude of the noise in + the output signal of the amplifier. S/N=V_signal/V_noise. (array for active + channels) + + + + + (if active >1) + + + + + for reducing interferences between different signalling pathways + + + + + The spectrum of frequency it can amplify, from its lowest to highest frequency + limits. + + + + + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) + + + + + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) + + + + diff --git a/contributed_definitions/NXaperture_em.nxdl.xml b/contributed_definitions/NXaperture_em.nxdl.xml index 5fbae08d4d..d30e059a58 100644 --- a/contributed_definitions/NXaperture_em.nxdl.xml +++ b/contributed_definitions/NXaperture_em.nxdl.xml @@ -1,37 +1,52 @@ - + - + + - Details of an individual aperture for electron beams. + Base class for an individual aperture for beams in electron microscopy. - - - Given name/alias of the aperture. - - - Relevant value from the control software. - This is not always just the diameter of (not even in the case) - of a circular aperture. Usually it is a mode setting value which - is selected in the control software. - Which settings are behind the value should be defined - for now in the description field, if these are known - in more detail. + This is not always just the diameter of the aperture (not even in the case) + of a circular aperture. Usually, it is a value that is set in the control + software whereby a specific configuration of an aperture is selected by the + software. + + The control software of commercial microscope typically offers the user + access at a high abstraction level because of which many details about + the actual settings of the electrical components are typically unknown. + + However, if more details are known or should be documented one should + use the description field for this. Ideally, a (globally) unique persistent identifier, link, or text to a - resource which gives further details. Alternatively a free-text field. + resource which gives further details. Alternatively a free-text field to + store details noteworthy for contextualization or more detail. - - - Affine transformation which detail the arrangement in the - microscope relative to the optical axis and beam path. - - diff --git a/contributed_definitions/NXapm.nxdl.xml b/contributed_definitions/NXapm.nxdl.xml index 53c790b417..8b1f74433c 100644 --- a/contributed_definitions/NXapm.nxdl.xml +++ b/contributed_definitions/NXapm.nxdl.xml @@ -1,13 +1,48 @@ - + - + + + - The symbols used in the schema to specify e.g. dimensions of arrays + The symbols used in the schema to specify e.g. dimensions of arrays. - Total number of ions collected + Total number of ions collected. @@ -22,14 +57,13 @@ - Maximum number of allowed atoms per (molecular) ion (fragment). Needs - to match maximum_number_of_atoms_per_molecular_ion. + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. - Number of mass-to-charge-state-ratio range intervals mapped on this - ion type. + Number of mass-to-charge-state-ratio intervals of this ion type. @@ -52,18 +86,84 @@ Number of bins. + + + Total number of integers in the supplementary XDMF topology array. + + - Application definition for atom probe microscopy experiments. + Application definition for atom probe and field ion microscopy experiments. + + This application definition provides a place to document data and metadata to + an atom probe experiment. Primarily the measurement itself is documented. + However, as most atom probe experiments are controlled with commercial software + which does not allow to access the raw detector hits, this application definition + also includes two key groups of processing steps (reconstruction and ranging). + + During tomographic reconstruction measured data are processed into a point cloud + of reconstructed positions of certain ions. During ranging time-of-flight data + are identified as representing specific ions to annotate each ion with a label. + + Commercial software used in atom probe research is designed as an integrated + acquisition and instrument control software. For AMETEK/Cameca local electrode + atom probe (LEAP) instruments the least processed (rawest) numerical results + and metadata are stored in so-called STR, RRAW, RHIT, and HITS files, which + are proprietary and their file format specifications not publicly documented. + + Supplementary metadata are kept in a database (formerly known as the ISDb) + which is connected to the instrument control software and synced with the + experiment while ions are detected. In effect, RHIT and HITS files + store the (rawest) experiment data in a closed manner that is + practically useless for users unless they have access to the + commercial software. + + To arrive at a state that atom probe microscopy (APM) with LEAP instruments + delivers a dataset with which users can study reconstructed atomic + position and do e.g. composition analyses or other post-processing + analysis tasks, these raw data have to be processed. Therefore, it is + necessary that for an application definition to be useful, details about + the physical acquisition of the raw data and all its + processing steps have to be stored. + + With this a user can create derived quantities like ion hit positions + (on the detector) and calibrated time-of-flight data. These derived + quantities are also needed to obtain calibrated mass-to-charge-state + ratios, and finally the tomographic reconstruction of the ion positions. + + In most cases, an APM dataset is useful only if it gets post-processed + via so-called ranging. Ranging defines rules for mapping time-of-flight + and mass-to-charge-state ratio values on ion species. This is post-processing + even though in practice it is performed sometimes already (as preview) + already while data are still being collected. + + The ion types decode molecular identities which can very often be + mapped to elemental identities, and also be used to distinguish isotopes. + All these steps are in most cases performed using commercial software. + + Frequently, though, ranging and post-processing is also performed with + (open-source) research software. Therefore, there is strictly speaking + not a single program used throughout an atom probe analysis not even + for the early stage of data acquisition and processing stages to obtain + a useful reconstructed and ranged dataset. + + This application definition documents not only the measurement but also the + key post-processing steps which transform the proprietary data into a + tomographic reconstruction with ranging definitions. + + Future guidance by the technology partners like AMETEK/Cameca could improve + this description to cover a substantial larger number of eventually metadata + that so far are neither publicly documented nor accessible. - + An at least as strong as SHA256 hashvalue of the file that specifies the application definition. - + + NeXus NXDL schema to which this file conforms. @@ -71,24 +171,27 @@ - + - Ideally, a (globally) unique persistent identifier + Ideally, a (globally) unique persistent identifier for referring to this experiment. The identifier is usually defined/issued by the facility, laboratory, - or the principle investigator. The identifier enables to link + or the principle investigator. The identifier enables to link experiments to e.g. proposals. - + Free-text description about the experiment. - Users are strongly advised to detail the sample history in the + Users are strongly advised to detail the sample history in the respective field and fill rather as completely as possible the fields - of this application definition rather than write details about the - experiment into this free-text description field. + of the application definition behind instead of filling in these + details into the experiment_description free-text description field. + + Users are encouraged to add in this field eventual DOIs to papers + which yield further details to the experiment. @@ -98,135 +201,103 @@ If the application demands that time codes in this section of the application definition should only be used for specifying when the experiment was performed - and the exact duration is not relevant - - this start time field should be used. + - this start_time field should be used. Often though it is useful to specify a time interval with specifying both start_time and end_time to allow for more detailed bookkeeping and interpretation of the experiment. The user should be aware that - even with having both time instances specified, it may not be possible - to infer how long the experiment took or for how long data - were acquired. + even with having both dates specified, it may not be possible + to infer how long the experiment took or for how long data + were collected. More detailed timing data over the course of the experiment have to be - collected to compute this. These computations can take advantage of - individual time stamps in NXevent_em instances to provide - additional pieces of information. + collected to compute this event chain during the experiment. - + + ISO 8601 time code with local time zone offset to UTC included when the microscope session ended. - - - Commercial or otherwise given name to the program which was used - to create the file. Atom probe microscopy experiments are nowadays - in most cases controlled via commercial software. These are often - designed as integrated acquisition and instrument control software - solutions. - For AMETEK/Cameca local electrode atom probe (LEAP) instruments the - least processed (rawest) numerical results and metadata are stored - in so-called RHIT and HITS files, which are proprietary and the - specifications of which are not publicly documented. - - Supplementary metadata are kept in a database which is connected - to the instrument control software. RHIT and HITS are proprietary - binary file formats whose content must not be accessed with software - other than of AMETEK (IVAS/AP Suite). In effect, RHIT and HITS files - store the experiment in a closed manner that is practically useless - for users unless they have access to the commercial software. - - To arrive at a state that atom probe microscopy with LEAP instruments - delivers a dataset with which users can study reconstructed atomic - position and do e.g. composition analyses or other post-processing - analysis tasks, these raw data have to be processed. Therefore, it is - necessary that for an application definition to be useful, details about - the physical acquisition of the raw data and all its - processing steps have to be stored. - - With this a user can create derived quantities like ion hit positions - (on the detector), calibrated time-of-flight data. These derived - quantities are also needed to obtain calibrated mass-to-charge-state - ratios, and finally the tomographic reconstruction of the ion positions. - - In most cases, an APM dataset is useful only if it gets post-processed - via so-called ranging. Ranging defines rules for mapping time-of-flight - and mass-to-charge-state ratio values on ion species. In turn, these - labels decode elemental identities and can often also be used to - resolve isotopes. All these steps are in most cases performed using - commercial software. - - Frequently, though, ranging and post-processing is also performed with - (open-source) research software. Therefore, there is strictly speaking - not a single program used throughout an atom probe analysis not even - for the early data acquisition and processing stages to obtain a useful - reconstructed and ranged dataset. - - Therefore, the application definition documents not only the measurement - but also the key post-processing steps which transform the proprietary - data into a tomographic reconstruction with ranging definitions. - - - - Program version plus build number, commit hash, or description of an - ever persistent resource where the source code of the program and - build instructions can be found so that the program can be configured - in such a manner that the result file is ideally recreatable - yielding the same results. - - - - + + + + + + + - Not the specimen name or the experiment identifier but the identifier + Neither the specimen_name nor the experiment_identifier but the identifier through which the experiment is referred to in the control software. - For LEAP instruments it is recommended to use the IVAS/AP Suite + For LEAP instruments it is recommended to use the IVAS/APSuite run_number. For other instruments, such as the one from Stuttgart or - Oxcart from Erlangen, or the instruments in Rouen, use the + Oxcart from Erlangen, or the instruments at GPM in Rouen, use the identifier which is closest in meaning to the LEAP run number. + The field does not have to be required if the information is recoverable + in the dataset which for LEAP instruments is the case when RHIT or HITS + files are also stored alongside a data artifact instance which is + generated according to this NXapm application definition. - As a destructive microscopy method, a run can be performed only once. + As a destructive microscopy technique, a run can be performed only once. It is possible, however, to interrupt a run and restart data acquisition while still using the same specimen. In this case, each evaporation run - needs to be distinguished with - different run numbers. We follow this habit of most atom probe groups. + needs to be distinguished with different run numbers. + We follow this habit of most atom probe groups. + + This application definition does currently not allow storing the + entire set of such interrupted runs. Not because of a technical limitation + within NeXus but because we have not seen a covering use case based + on which we could have designed and implemented this case. + Atom probers are invited to contact the respective people in the + FAIRmat team to fix this. - + - Binary container for a file or a compressed collection of files which + Binary container for a file or a compressed collection of files which can be used to add further descriptions and details to the experiment. The container can hold a compressed archive. Required for operation_mode apt_fim or other to give further details. Users should not abuse this field to provide free-text information. - Instead, these should be mapped to respective groups and sections. + Instead, these pieces of information should be mapped to + respective groups and sections. - + A small image that is representative of the entry; this can be an image taken from the dataset like a thumbnail of a spectrum. - A 640 x 480 pixel jpeg image is recommended. + A 640 x 480 pixel jpeg image is recommended. Adding a scale bar to that image is recommended but not required as the main purpose of the thumbnail is to provide e.g. thumbnail images for displaying them in data repositories. - + - What type of atom probe microscope experiment is performed. - This field can be used e.g. by materials database systems to - qualitatively filter experiments. - APT are experiments where the analysis_chamber has no imaging gas. - For FIM analyses an imaging gas is used, which should be specified - with the atmosphere in the analysis_chamber group. - Combinations of the two imaging modes are possible. For these apt_fim - or other operation_mode the user should specify details in the - experiment_documentation field. + What type of atom probe microscopy experiment is performed. + This field is primarily meant to inform materials database systems + to qualitatively filter experiments: + + * apt are experiments where the analysis_chamber has no imaging gas. + experiment with LEAP instruments are typically performed as apt. + * fim are experiments where the analysis_chamber has an imaging gas, + which should be specified with the atmosphere in the analysis_chamber group. + * apt_fim should be used for combinations of the two imaging modes. + * other should be used in combination with the user specifying details in the + experiment_documentation field. @@ -235,114 +306,272 @@ - + + - Contact information and eventually details of at least one person - involved in the taking of the microscope session. This can be the - principle investigator who performed this experiment. - Adding multiple users if relevant is recommended. + Contact information and eventually details person(s) involved in the + microscope session. This can be the principle investigator who performed + this experiment. Adding multiple users if relevant is recommended. - + Given (first) name and surname of the user. - + - Name of the affiliation of the user at the point in time when the experiment was - performed. + Name of the affiliation of the user at the point in time + when the experiment was performed. - + Postal address of the affiliation. - + - Email address of the user at the point in time when the experiment was - performed. Writing the most permanently used email is recommended. + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. - + - Globally unique identifier of the user as offered by services like ORCID or - ResearcherID. + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific + service should also be written in orcid_platform - + - (Business) (tele)phone number of the user at the point in time when the - experiment was performed. + Name of the OrcID or ResearcherID where the account + under orcid is registered. - + - Which role does the user have in the place and at the point + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + + + + + Which role does the user have in the place and at the point in time when the experiment was performed? Technician operating the microscope. Student, postdoc, principle investigator, guest are common examples. - + + + Account name that is associated with the user + in social media platforms. + + + + + Name of the social media platform where the account + under social_media_name is registered. + + + + + + Description of the sample from which the specimen was prepared or + site-specifically cut out using e.g. a focused-ion beam instrument. + + The sample group is currently a place for storing suggestions from + atom probers about other knowledge they have gained about the sample + from which they cut the specimen which is field-evaporated during the + experiment. Typically this is possible because the atom probe specimen + is usually not heat treated as is but one assumes that one has the sample + prepared as needed (i.e. with a specific grain diameter) and can thus + just cut out the specimen from that material. + + There are cases though where the specimen is processed further, i.e. the + specimen is machined further or exposed to external stimuli during the + experiment. In this case, these details should not be stored in the + sample group but atom probers should make suggestions how this application + definition can be improved to find a better place and compromise + how to improve this application definition. + + In the future also details like how the grain_diameter was characterized, + how the sample was prepared, how the material was heat-treated etc., + should be stored as using specific application definitions/schemas + which are then arranged and documented with a description of the workflow + so that actionable graphs become instantiatable. + + + + Qualitative information about the grain size, here specifically + described as the equivalent spherical diameter of an assumed + average grain size for the crystal ensemble. + Users of this information should be aware that although the grain + diameter or radius is often referred to as grain size and used in + e.g. Hall-Petch-type materials models this is if at all an ensemble + average whose reporting may be very informative or not if the specimen + contains a few grains only. In atom probe the latter is often the case + because grains are measured partially as their diameter can be in the + order of magnitude of the physical diameter of the specimen. + + Reporting a grain size is useful though as it allows judging if + specific features are expected to be found in the detector hit map. + + + + + Magnitude of the standard deviation of the grain_diameter. + + + + + The temperature of the last heat treatment step before quenching. + Knowledge about this value can give an idea how the sample + was heat treated, however if available a documentation of the + annealing treatment should be delivered by adding additional files + which are uploaded alongside an NXapm instance. + In the future there should better be an own schema used for the + heat treatment. + + + - Account name that is associated with the user in social media platforms. + Magnitude of the standard deviation of the heat_treatment_temperature. - + - Name of the social media platform where the account under social_media_name is - registered. + Rate of the last quenching step. + Knowledge about this value can give an idea how the specimen + was heat treated, however there are many situations where one + can imagine that the scalar value for just the quenching rate, + i.e. the first derivative of the measured time-temperature profile + is itself time-dependant. An example is when the specimen was + left in the furnace after the furnace was switched off. In this case + the specimen cools down with a specific rate of how this furnace + cools down in the lab. Processes which in practice are often not + documented with measuring the time-temperature profile. + + This can be problematic because when the furnace door was left open + or the ambient temperature in the lab changes, i.e. for a series of + experiments where one is conducted on a hot summer + day and the next during winter as might have an effect on the + evolution of the microstructure. There are many cases where this + has been reported to be an issue in industry, e.g. think about aging + aluminium samples left on the factory parking lot on a hot summer + day. + + + Magnitude of the standard deviation of the heat_treatment_quenching_rate. + + + + + + The chemical composition of the sample. Typically it is assumed that + this more macroscopic composition is representative for the material + so that the composition of the typically substantially less voluminous + specimen probes from the more voluminous sample. + + + + Reporting compositions as atom and weight percent yields both + dimensionless quantities but their conceptual interpretation + differs. A normalization based on atom_percent counts relative to the + total number of atoms are of a particular type. By contrast, weight_percent + normalization factorizes in the respective mass of the elements. + Python libraries like pint are challenged by these differences as + at.-% and wt.-% both yield fractional quantities. + + + + + + + + + + Human-readable name of the element/ion (e.g. Fe). + Name has to be a symbol of an element from the periodic table. + All symbols in the set of NXion instances inside the group + chemical_composition need to be disjoint. + + + + + Composition value for the element/ion referred to under name. + The value is normalized based on normalization, i.e. composition + is either an atom or weight percent quantity. + + + + + Magnitude of the standard deviation of the composition (value). + + + + - + + Descriptive name or ideally (globally) unique persistent identifier. The name distinguishes the specimen from all others and especially the - predecessor/origin from where the specimen was cut. - In cases where the specimen was e.g. site-specifically cut from - samples or in cases of an instrument session during which multiple - specimens are loaded, the name has to be descriptive enough to resolve - which specimen on e.g. the microtip array was taken. + predecessor/origin (see the sample group) from where this specimen was cut. + In cases where the specimen was e.g. site-specifically cut from the + sample referred to in the sample group or in cases of an instrument session + during which multiple specimens are loaded, the name has to be descriptive + enough to resolve which specimen on e.g. the microtip array was taken. - The user is advised to store the details how specimens were - cut/prepared from samples in the sample history. - This field must not be used for an alias of the specimen. - Instead, use short_title. + The user is advised to store the details how a specimen was cut/prepared + from a specific sample in the sample_history. The sample_history field + must not be used for writing an alias of the specimen. Instead, + use the field alias for this. As an example there may be a specimen/sample + monitoring system in a lab with bar codes. The bar code is a good + specimen/sample name. A shorter and more human readable alias like + A0 can be an example for something to write in the alias field. In cases where multiple specimens have been loaded into the microscope the name has to be the specific one, whose results are stored - by this NXentry, because a single NXentry should be used only for - the characterization of a single specimen. + by this NXentry, because a single NXentry is to be used for the + characterization of a single specimen in a single continuous run. - Details about the specimen preparation should be stored in the - sample history. + Details about the specimen preparation should be stored in the + sample_history or if this is not possible in the sample group. - + Ideally, a reference to the location of or a (globally) unique - persistent identifier of e.g. another file which should document - ideally as many details as possible of the material, its - microstructure, and its thermo-chemo-mechanical processing/preparation - history. + persistent identifier of e.g. another file which should document + ideally as many details as possible of the material, its + microstructure, and its thermo-chemo-mechanical processing/ + preparation history. In the case that such a detailed history of the sample/specimen is not available, use this field as a free-text description to specify a sub-set of the entire sample history, i.e. what you would consider - being the key steps and relevant information about the specimen, + as being the key steps and relevant information about the specimen, its material, microstructure, thermo-chemo-mechanical processing state and details of the preparation. - + ISO 8601 time code with local time zone offset to UTC information when the specimen was prepared. - Ideally report the end of the preparation, i.e. the last known time + Ideally, report the end of the preparation, i.e. the last known time the measured specimen surface was actively prepared. Usually this should be a part of the sample history, i.e. the sample is imagined handed over for the analysis. At the point it enters the microscope @@ -355,63 +584,81 @@ better be placed in resources which describe the sample_history. - + - Possibility to give an abbreviation of the specimen name field. + Short_name or abbreviation of the specimen name field. - + - Use Hill's system for listing elements of the periodic table which - are inside or attached to the surface of the specimen and thus - relevant from a scientific point of view. + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. The purpose of the field is to offer materials database systems an opportunity to parse the relevant elements without having to interpret - these from the sample history. + these from the sample history or from other data sources. + + + + + Discouraged free-text field in case properly designed records + for the sample_history or sample section are not available. - + - Discouraged free-text field in case properly designed records for the - sample_history are not available. + Report if the specimen is polycrystalline, in which case it + contains a grain or phase boundary, or if the specimen is a + single crystal. - + + Hard link to a location in the hierarchy of the NeXus file where the data for default plotting are stored. - + Container to hold different coordinate systems conventions. For the specific idea and conventions to use with the NXcoordinate_system_set inspect the description of the - NXcoordinate_system_set base class. + NXcoordinate_system_set base class. Specific details for application + in atom probe microscopy follow. - Specific details for application in atom probe microscopy follow. In this research field scientists distinguish usually several Euclidean coordinate systems (CS): - * The laboratory space; - a CS specifying the room where the instrument is located in or - a physical landmark on the instrument, e.g. the direction of the - transfer rod where positive is the direction how the rod - pushes into the instrument. - * The specimen space; - a CS affixed to either the base or the initial apex of the specimen, - whose z axis points towards the detector. - * The detector space; - a CS affixed whose xy plane is usually in the detector and whose - z axis points towards the specimen. - * The reconstruction space; - a CS associated with the tomographic reconstruction. - Its orientation depends on the commercial software used. - * Eventually further coordinate systems attached to the - flight path of individual ions might be defined. + * World space; + a CS specifying a local coordinate system of the planet earth which + identifies into which direction gravity is pointing such that + the laboratory space CS can be rotated into this world CS. + * The laboratory space; + a CS specifying the room where the instrument is located in or + a physical landmark on the instrument, e.g. the direction of the + transfer rod where positive is the direction how the rod + has to be pushed during loading a specimen into the instrument. + In summary, this CS is defined by the chassis of the instrument. + * The specimen space; + a CS affixed to either the base or the initial apex of the specimen, + whose z axis points towards the detector. + * The detector space; + a CS affixed to the detector plane whose xy plane is usually in the + detector and whose z axis points towards the specimen. + This is a distorted space with respect to the reconstructed ion + positions. + * The reconstruction space; + a CS in which the reconstructed ion positions are defined. + The orientation depends on the analysis software used. + * Eventually further coordinate systems attached to the + flight path of individual ions might be defined. Coordinate systems should be right-handed ones. Clockwise rotations should be considered positive rotations. @@ -431,75 +678,137 @@ Consult the work of A. J. Breen and B. Gault and team for further details. + + - + + + - Metadata and numerical data of the atom probe and the lab in which it + Metadata and numerical data of the atom probe and the lab in which it stands. An atom probe microscope (experiment) is different compared to a large- scale facility or electron accelerator experiments in at least two ways: - * First, ionized atoms and molecular ion(s fragments) - (in the case of atom probe tomography) - and (primarily) imaging gas ions (in the case of field ion - microscopy) are accelerated towards a position-sensitive - and time-of-flight taking detector system. - Hence, there is no real probe/beam. - * Second, the specimen is the lens of an atom probe microscope. + * First, ionized atoms and molecular ion(s fragments) + (in the case of atom probe tomography) + and (primarily) imaging gas ions (in the case of field ion + microscopy) are accelerated towards a position-sensitive + and time-of-flight taking detector system. + Hence, there is no real probe/beam. + * Second, the specimen is the lens of the microscope. - + + - Given name of the atom probe at the hosting institution. This is an + Given name of the atom probe at the hosting institution. This is an alias. Examples could be LEAP5000, Raptor, Oxcart, one atom at a time, etc. - + Location of the lab or place where the instrument is installed. Using GEOREF is preferred. - + + + + + + - The space inside the atom probe that ions pass through nominally when they leave - the specimen and travel to the detector. + The space inside the atom probe along which ions pass nominally + when they leave the specimen and travel to the detector. + + THIS DOCSTRING NEEDS CLARIFICATION. + + + + + + The nominal diameter of the specimen ROI which is measured in the + experiment. It is important to mention that the physical specimen + cannot be measured completely because ions may launch but not be + detected or hit elsewhere in the analysis_chamber. - - - - - - - - + + - Was the reflectron used? + Is a reflectron installed and was it used? + + + + + + + + + + - A local electrode guiding the ion flight path. + A local electrode guiding the ion flight path. Also called + counter or extraction electrode. - + Identifier of the local_electrode in an e.g. database. - + + + + + + + + + + Detector for taking raw time-of-flight and ion/hit impact positions data. - + Description of the detector type. Specify if the detector is not the usual type, i.e. not a delay-line detector. @@ -509,27 +818,30 @@ the detector type via free-text. - + + Given name/alias. - + + Given brand or model name by the manufacturer. - + - Given hardware name/serial number or hash identifier issued by the manufacturer. + Given hardware name/serial number or hash identifier + issued by the manufacturer. - + Given name of the manufacturer. - + Amplitude of the signal detected on the multi-channel plate (MCP). @@ -541,22 +853,228 @@ + - - - - + + + + + + + + + + + Atom probe microscopes use controlled laser, voltage, or a + combination of pulsing strategies to trigger the excitation + and eventual field evaporation/emission of an ion during + an experiment. + If pulse_mode is set to laser or laser_and_voltage (e.g. for + LEAP6000-type instruments) having the group/section laser_gun + is required and the following of its fields have to be filled: + + * name + * wavelength + * energy + + + + + + + + + + + + + + + + - + + - Average temperature at the specimen base, i.e. base temperature, during the - measurement. + Average temperature at the specimen base, i.e. + base_temperature during the measurement. + + + + + The best estimate, at experiment time, for the temperature at the + sample base (furthest point along sample apex and holding assembly + that is removable from the sample stage). + + + + + + + + + + + + + + + + + + + + Average pressure in the analysis chamber. + - + + + + + + + + + + + + Average pressure in the buffer chamber. + + + + + + + + + + + + + + + + Average pressure in the load_lock_chamber. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A possible place, which has to be discussed with the atom probe + community more though, where quantitative details about the calibration + of the counter electrode could be stored. Work in this direction was + e.g. reported by the `Erlangen group <https://www.youtube.com/watch?v=99hNEkqdj78t=1876s>`_ + (see `P. Felfer et al. <http://dx.doi.org/10.1016/j.ultramic.2016.07.008>`_ ) + + + + + + + A place where details about the initial shape of the specimen + can be stored. Ideally, here also data about the shape evolution + of the specimen can be stored. There are currently very few + techniques which can measure the shape evolution: + + * Correlative electron microscopy coupled with modeling + but this usually takes an interrupted experiment + in which the specimen is transferred, an image taken, + and a new evaporation sequence initiated. + Examples are `I. Mouton et al. <https://doi.org/10.1017/S1431927618016161>`_ + and `C. Fletcher <https://doi.org/10.1088/1361-6463/abaaa6>`_. + * Another method, which is less accurate though, is to monitor + the specimen evolution via the in-built camera system + (if available) in the instrument. + * Another method is to use correlated scanning force microscopy + methods like reported in `C. Fleischmann <https://doi.org/10.1016/j.ultramic.2018.08.010>`_. + * A continuous monitoring of the specimen in a + correlative electron microscopy/atom probe experiment + is planned to be developed by `T. Kelly et al. <https://doi.org/10.1017/S1431927620022205>`_ + Nothing can be said about the outcome of this research yet but + here is where such spatiotemporally data could be stored. + + + + + Ideally measured or best elaborated guess of the + initial radius of the specimen. + + + + + Ideally measured or best elaborated guess of the shank angle. + This is a measure of the specimen taper. Define it in such a way + that the base of the specimen is modelled as a conical frustrum so + that the shank angle is the (shortest) angle between the specimen + space z-axis and a vector on the lateral surface of the cone. + + + + + Average detection rate over the course of the experiment. + + + + + + Estimated field at the apex along the evaporation sequence. + + + + + + + The majority of atom probe microscopes come from a single commercial manufacturer `AMETEK (formerly Cameca) <https://www.atomprobe.com>`_. @@ -586,55 +1104,57 @@ groups to begin with. Holding heterogeneous, not yet standardized but relevant pieces of information is the purpose of this collection. - + + + + + + + - Track time-dependent settings over the course of the measurement about the - environment in the analysis chamber such as gas pressure values etc. + Track time-dependent details over the course of the measurement about the + buffer_chamber. - - - Average pressure in the analysis chamber. - - - - - - A place where details about the initial shape of the specimen - can be stored. Ideally, here also data about the shape evolution - of the specimen can be stored. There are currently very few - techniques which can measure the shape evolution: - - * Correlative electron microscopy coupled with modeling - but this usually takes an interrupted experiment - in which the specimen is transferred, an image taken, - and a new evaporation sequence initiated. - Examples are `I. Mouton et al. <https://doi.org/10.1017/S1431927618016161>`_ and `C. Fletcher <https://doi.org/10.1088/1361-6463/abaaa6>`_. - * Another, less accurate method, though, is to monitor - the specimen evolution via the in-built camera system - (if available) in the instrument. - * Another method is to use correlated scanning force microscopy - methods like reported in `C. Fleischmann <https://doi.org/10.1016/j.ultramic.2018.08.010>`_. - * A continuous monitoring of the specimen in a - correlative electron microscopy/atom probe experiment - is planned to be developed by `T. Kelly et al. <https://doi.org/10.1017/S1431927620022205>`_ - - + - Ideally measured or best elaborated guess of the initial radius of the specimen. + Track time-dependent details over the course of the measurement about the + load_lock_chamber. - - + + - Ideally measured or best elaborated guess of the shank angle. - This is a measure of the specimen taper. Define it in such a way - that the base of the specimen is modelled as a conical frustrum so - that the shank angle is the (shortest) angle between the specimen - space z-axis and a vector on the lateral surface of the cone. + Track time-dependent details over the course of the measurement about the + analysis_chamber. - + - + + + + + A statement whether the measurement was successful or failed prematurely. + + + + + + + + + + + Details about where ions hit the ion_detector and data processing steps related to analog-to-digital conversion of detector signals @@ -647,23 +1167,15 @@ like the Oxcart instrument, individual timing data from the delay-line detector are openly accessible. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + + Raw readings from the analog-to-digital-converter timing circuits of the detector wires. @@ -679,50 +1191,53 @@ Evaluated ion impact coordinates at the detector (either as computed from the arrival time data or as reported by the control software). + If the acquisition software enables it one can also store in this + field the hit_positions, as measured by the detector, without any + corrections. - - - Average detection rate over the course of the experiment. - - - + + - Data post-processing step which is, like the impact position analyses, - also usually executed in the integrated control software. - This processing yields how many ions were detected with each pulse. + This could be a place where currently the publicly undocumented + algorithmic steps are stored how detected hits are judged for their + quality. In CamecaRoot this there is something mentioned like + golden and partial hits, here is where this could be documented. + + + + + + + Data post-processing step which is, like the impact position analyses, + usually executed in the integrated control software. This processing + yields how many ions were detected with each pulse. - It is possible that multiple ions evaporate and hit the same or - different pixels of the detector on the same pulse. + It is possible that multiple ions evaporate and hit the same or + different pixels of the detector on the same pulse. These data form the basis to analyses of the so-called - (hit) multiplicity of an ion. - Multiplicity must not be confused with how many - atoms of the same element or isotope, respectively, - a molecular ion contains (which is encoded with the - isotope_vector field of each NXion instance. + (hit) multiplicity of an ion. + + Multiplicity must not be confused with how many atoms + f the same element or isotope, respectively, a molecular + ion contains (which is instead encoded with the + isotope_vector field of each NXion instance). - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + Number of pulses since the last detected ion pulse. For multi-hit records, after the first record, this is zero. @@ -731,90 +1246,88 @@ - + + - Hit multiplicity. + Number of pulses since the start of the atom probe + run/evaporation sequence. - + + - Number of pulses since the start of the atom probe run/evaporation sequence. + Hit multiplicity. - + - Like impact position and hit multiplicity computations, + Like impact position and hit multiplicity computations, ion filtering is a data post-processing step with which users identify which of the detected ions should be included in the voltage-and-bowl correction. This post-processing is usually performed via GUI interaction in the reconstruction pipeline of IVAS/APSuite. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - + + + + + + - Bitmask which is set to true if the ion is considered and false otherwise. + Bitmask which is set to true if the ion + is considered and false otherwise. - + + - Data post-processing step to correct for ion impact - position flight path differences, detector biases, + Data post-processing step to correct for ion impact + position flight path differences, detector biases, and nonlinearities. This step is usually performed with commercial software. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + + - Raw time-of-flight data as read out from the acquisition software if these data - are available and accessible. + Raw time-of-flight data as read out from the acquisition software + if these data are available and accessible. + Calibrated time-of-flight. @@ -822,68 +1335,63 @@ - + - The key idea and algorithm of the voltage-and-bowl correction - is qualitatively similar for instruments of different manufacturers + The key idea and algorithm of the voltage-and-bowl correction is + qualitatively similar for instruments of different manufacturers or research groups. Specific differences exists though in the form of different - calibration models. For now we do not wish to resolve or + calibration models. For now we do not wish to resolve or generalize these differences. Rather the purpose of this collection is to provide a container where model-specific parameters and calibration models can be stored if users know these for sure. - For AMETEK LEAP atom probes this should be the place for + For AMETEK LEAP instruments this should be the place for storing initial calibration values. These values are accessible normally only by AMETEK service engineers. They use these for calibrating the detector and instrument. Users can also use this NXcollection for storing the iteratively identified calibrations which scientists - will get displayed in e.g. AP Suite while they execute + will see displayed in e.g. APSuite while they execute the voltage-and-bowl correction as a part of the reconstruction pipeline in APSuite. - + + Data post-processing step in which calibrated time-of-flight data (ToF) are interpreted into mass-to-charge-state ratios. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + Store vendor-specific calibration models here (if available). - Mass-to-charge-state ratios + Mass-to-charge-state ratio values. + - + + Data post-processing step to create a tomographic reconstruction of the specimen based on selected calibrated ion hit positions, @@ -893,35 +1401,61 @@ i.e. numerical recipes how to compute x, y, z atomic positions from the input data. - - - Given name of the program that was used to perform this computation. - Similar comments as voltage_and_bowl_correction apply. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + Qualitative statement about which reconstruction protocol was used. - - + - - + + + + + Different reconstruction protocols exist. Although these approaches + are qualitatively similar, each protocol uses different parameters + (and interprets these differently). The source code to IVAS/APSuite + is not open. For now users should store reconstruction parameter + in a collection. + + + + + + Different strategies for crystallographic calibration of the + reconstruction are possible. The field is required and details + should be specified in free-text at least. If the not crystallographic + calibration was performed the field should be filled with the n/a, + meaning not applied. + + Three-dimensional reconstructed positions of the ions. @@ -932,15 +1466,33 @@ - + + + + An array of triplets of integers which can serve as a supplementary + array for Paraview to display the reconstructed dataset. + The XDMF primitive type is here 1, the number of primitives 1 per + triplet, the last integer in each triplet is the identifier of + each point starting from zero. + + + + + + + + - Different reconstruction protocols exist. Although these approaches - are qualitatively similar, each protocol uses different parameters - (and interprets these differently). The source code to IVAS/APSuite - is not open. For now users should store reconstruction parameter - in a collection. + Six equally formatted sextets chained together. For each + sextett the first entry is an XDMF primitive topology + key (here 5 for polygon), the second entry the XDMF primitive + count value (here 4 because each face is a quad). + The remaining four values are the vertex indices. - + + + + To get a first overview of the reconstructed dataset, @@ -948,27 +1500,23 @@ of the ion density using one nanometer cubic bins without applying smoothening algorithms on this histogram. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - + + + + + - A default three-dimensional histogram of the total number of ions in each bin. + A default three-dimensional histogram of the total + number of ions in each bin obtained via using a rectangular + transfer function. - + + + + + + Array of counts for each bin. @@ -978,206 +1526,181 @@ - + - Bin positions along the z axis. + Bin center of mass position along the z axis. + + + + - + - Bin positions along the y axis. + Bin center of mass position along the y axis. + + + + - + - Bin positions along the x axis. + Bin center of mass position along the x axis. + + + + - - - Naive point cloud density map. - - - + + Data post-processing step in which elemental, isotopic, and/or molecular identities are assigned to the ions. The documentation of these steps is based on ideas described in the literature: - * `M. K. Miller <https://doi.org/10.1002/sia.1719>`_ - * `D. Haley et al. <https://doi.org/10.1017/S1431927620024290>`_ - * `M. Kühbach et al. <https://doi.org/10.1017/S1431927621012241>`_ + * `M. K. Miller <https://doi.org/10.1002/sia.1719>`_ + * `D. Haley et al. <https://doi.org/10.1017/S1431927620024290>`_ + * `M. Kühbach et al. <https://doi.org/10.1017/S1431927621012241>`_ - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - + + + + + + + How many ion types are distinguished. If no ranging was performed each ion is of the special unknown type. + The iontype ID of this unknown type is 0 which is a reserve value. + Consequently, iontypes start counting from 1. Assumed maximum value that suffices to store all relevant - molecular ions, even the most complicated ones. + molecular ions, even the most complicated ones. Currently a value of 32 is used. - + Specifies the computation of the mass-to-charge histogram. Usually mass-to-charge values are studied as an ensemble quantity, specifically these values are binned. - The (NXprocess) stores the settings of this binning. + This (NXprocess) stores the settings of this binning. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - + + + + + - Smallest and largest mass-to-charge value. + Smallest and largest mass-to-charge-state ratio value. + - Binning width + Binning width of the mass-to-charge-state ratio values. + A default histogram aka mass spectrum of the mass-to-charge-state ratio values. - + + + + + + Array of counts for each bin. + - + - End of mass-to-charge-state ratio bin. + Right boundary of each mass-to-charge-state ratio value bin. + + + + + - - - Mass-to-charge-state histogram. - - - + Details of the background model which was used to correct the total counts per bin into counts. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - + + + + + - + + - How where peaks in the background-corrected - mass-to-charge histogram identified? + How where peaks in the background-corrected in the histogram + of mass-to-charge-state ratio values identified? - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - + + + + + + + + - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. + THIS DOCSTRING NEEDS CLARIFICATION. - - - + + - + Details about how peaks, with taking into account error models, were interpreted as ion types or not. - - - Given name of the program that was used to perform this computation. - Apart from the classical approach to use AMETEK software for this - processing step, a number of open-source alternative tools exists. - - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - - - - - - - - + + + + + + + + + + diff --git a/contributed_definitions/NXapm_composition_space_results.nxdl.xml b/contributed_definitions/NXapm_composition_space_results.nxdl.xml new file mode 100644 index 0000000000..72dbb28419 --- /dev/null +++ b/contributed_definitions/NXapm_composition_space_results.nxdl.xml @@ -0,0 +1,488 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of voxel of discretized domain for analyzed part of the dataset. + + + + + The dimensionality of the grid. + + + + + The cardinality or total number of cells/grid points. + + + + + Number of terms in the composition clustering dictionary + + + + + Number of terms in the position clustering dictionary + + + + + Results of a run with Alaukik Saxena's composition space tool. + + This is an initial draft application definition for the common NFDI-MatWerk, + FAIRmat infrastructure use case IUC09 how to improve the organization and + results storage of the composition space tool and make these data at the same + time directly understandable for NOMAD. + + This draft does no contain yet the annotations for how to also store + in the HDF5 file a default visualization whereby the composition grid + could directly be explored using H5Web. I am happy to add this ones the + data have been mapped on this schema, i.e. more discussion needed. + + Also iso-surfaces can be described, for paraprobe, this is a solved problem, + check the respective group in the NXapm_paraprobe_results_nanochem data + schema/application definition. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + + + + + + TBD, maybe how to link between pyiron state tracking and app state tracking + + + + + Disencouraged place for free-text for e.g. comments. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. when composition space tool was started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and composition space tool exited as a process. + + + + + The path and name of the config file for this analysis. + TBD, this can be e.g. Alaukik's YAML file for composition space. + + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + + The path and name of the file (technology partner or community format) + from which reconstructed ion positions were loaded. + + + + + + + + The path and name of the file (technology partner or community format + from which ranging definitions, i.e. how to map mass-to- + charge-state ratios on iontypes were loaded. + + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the executable managed to process the analysis + or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Some suggestions follow, e.g. that field names should be prefixed + with the following controlled terms indicating which individual + coordinate system is described: + + * world + * composition_space + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Reference to or definition of a coordinate system with + which the positions and directions are interpretable. + + + + + + + + + + Position of each cell in Euclidean space. + + + + + + + + + + + + + + + + For each ion, the identifier of the voxel in which the ion is located. + + + + + + + + + + + + + + + + + + In Alaukik's tool the GMM step. + + + + + + + + + The keywords of the dictionary of distinguished compositionally- + defined cluster, e.g. the phases. Examples for keywords could be + phase1, phase2, and so one and so forth. + + + + + + + + Resolves for each keyword in cluster_dict which integer is used to + label something that it belongs or is assumed to represent this + cluster. + + + + + + + + + For example if the voxel grid is used to report that there + are voxels which are assumed to represent volume of either phase1 + or phase2, the cluster_dict_keyword would be a list with two names + phase1 and phase2, respectively. The cluster_dict_value would be a + list of e.g. integers 1 and 2. These could be used to build an + array with as many entries as there are voxel and store in this array + the respective value to encode which phase is assumed for each voxel. + + + + + + + + + + In Alaukik's tool the DBScan step after the GMM step. + + + + + + + + + The keywords of the dictionary of distinguished spatially-contiguous + clusters. Examples for keywords could be precipitate1, precipitate2, + and so one and so forth. + + + + + + + + Resolves for each keyword in cluster_dict which integer is used to + label something that it belongs or is assumed to represent this + cluster. + + + + + + + + + For example if the voxel grid is used to report that there + are voxels which are assumed to represent volume of certain precipitates, + say we found ten precipitates and consider the rest as matrix. + We could make a list of say matrix, precipitate1, precipitate2, ..., + precipitate10. With cluster_dict_value then running from 0 to 10, + i.e. matrix is flagged special as 0 and the remaining particles + are indexed conveniently as 1, 2, ..., 10 like end users expect. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_input_ranging.nxdl.xml b/contributed_definitions/NXapm_input_ranging.nxdl.xml new file mode 100644 index 0000000000..b8561c5589 --- /dev/null +++ b/contributed_definitions/NXapm_input_ranging.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + + Metadata to ranging definitions made for a dataset in atom probe microscopy. + + Ranging is the process of labeling time-of-flight data with so-called iontypes + which ideally specify the most likely ion/molecular ion evaporated within a + given mass-to-charge-state-ratio value interval. + + The paraprobe-toolbox uses the convention that the so-called UNKNOWNTYPE + iontype (or unranged ions) represents the default iontype. + The ID of this special iontype is always reserved as 0. Each ion + is assigned to the UNKNOWNTYPE by default. Iontypes are assigned + by checking if the mass-to-charge-state-ratio values of an ion matches + to any of the defined mass-to-charge-state-ratio intervals. + + + + Path and name of the NeXus/HDF5 file which stores ranging definitions. + + + + Version identifier of the file (representing an at least SHA256 strong) + hash. Such hashes serve reproducibility as they can be used for tracking + provenance metadata in a workflow. + + + + + + Name of the group (prefix to the individual ranging definitions) inside + the file referred to by filename which points to the specific ranging + definition to use. + An HDF5 file can store multiple ranging definitions. Using an ID is + the mechanism to distinguish which specific ranging (version) will + be processed. Reconstruction and ranging IDs can differ. + They specify different IDs. + + + diff --git a/contributed_definitions/NXapm_input_reconstruction.nxdl.xml b/contributed_definitions/NXapm_input_reconstruction.nxdl.xml new file mode 100644 index 0000000000..07275cd254 --- /dev/null +++ b/contributed_definitions/NXapm_input_reconstruction.nxdl.xml @@ -0,0 +1,58 @@ + + + + + + + Metadata of a dataset (tomographic reconstruction) in atom probe microscopy. + + + + Name of the (NeXus)/HDF5 file which stores reconstructed ion position + and mass-to-charge-state ratios. Such an HDF5 file can store multiple + reconstructions. Using the information within the dataset_name fields + is the mechanism whereby paraprobe decides which reconstruction to + process. With this design it is possible that the same HDF5 + file can store multiple versions of a reconstruction. + + + + Version identifier of the file (representing an at least SHA256 strong) + hash. Such hashes serve reproducibility as they can be used for tracking + provenance metadata in a workflow. + + + + + + Name of the dataset inside the HDF5 file which refers to the + specific reconstructed ion positions to use for this analysis. + + + + + Name of the dataset inside the HDF5 file which refers to the + specific mass-to-charge-state-ratio values to use for this analysis. + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_clusterer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_clusterer.nxdl.xml new file mode 100644 index 0000000000..c1a766d5a3 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_clusterer.nxdl.xml @@ -0,0 +1,477 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + + Maximum number of atoms per molecular ion. Should be 32 for paraprobe. + + + + + Number of clustering algorithms used. + + + + + Number of different iontypes to distinguish during clustering. + + + + + Configuration of a paraprobe-clusterer tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + How many tasks to perform? + + + + + This process maps results from cluster analyses performed with IVAS/APSuite + into an interoperable representation. Specifically in this process + paraprobe-clusterer takes results from clustering methods from other tools + of the APM community, like IVAS/APSuite. These results are usually reported + in two ways. Either as an explicit list of reconstructed ion positions. + In the case of IVAS these positions are reported through a text file + with a cluster label for each position. + + Alternatively, the list of positions is reported, as it is the case for + AMETEK (IVAS/AP Suite) but the cluster labels are specified implicitly + only in the following way: The mass-to-charge-state ratio column of a + what is effectively a file formatted like POS is used to assign a hypothetical + mass-to-charge value which resolves a floating point representation + of the cluster ID. + + Another case can occur where all disjoint floating point values, + i.e. here cluster labels, are reported and then a dictionary is created + how each value matches to a cluster ID. + + In general the cluster ID zero is reserved for marking the dataset + as to not be assigned to any cluster. Therefore, indices of disjoint + clusters start at 1. + + + + + + + + + AMETEK/Cameca results of cluster analyses, like with the maximum- + separation (MS) method clustering algorithm `J. Hyde et al. <https://doi.org/10.1557/PROC-650-R6.6>`_ + are stored as an improper POS file: This is a matrix of floating + point quadruplets, one for each ion and as many quadruplets as + ions were investigated. The first three values encode the position + of the ion. The fourth value is an improper mass-to-charge-state-ratio + value which encodes the integer identifier of the cluster as a floating + point number. + + + + + + + Specifies if the tool should try to recover for each position the closest + matching position from dataset/dataset_name_reconstruction (within + floating point accuracy). This can be useful for instance when users + wish to recover the original evaporation ID, which IVAS/AP Suite drops + for instance when writing their *.indexed.* cluster results POS files. + + + + + + + This process performs a cluster analysis on a reconstructed dataset + or a portion of the reconstruction. + + + + + + + + + + + + + + + + + The tool enables to inject precomputed distance information for each + point/ion which can be used for further post-processing and analysis. + + + + Name of an HDF5 file which contains the ion distances. + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + Absolute HDF5 path to the dataset with distance values for each ion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + How should iontypes be interpreted/considered during the cluster analysis. + Different options exist how iontypes are interpreted (if considered at all) + given an iontype represents in general a (molecular) ion with different isotopes + that have individually different multiplicity. + + The value resolve_all will set an ion active in the analysis + regardless of which iontype it is. + The value resolve_unknown will set an ion active when it is of the + UNKNOWNTYPE. + The value resolve_ion will set an ion active if it is of the + specific iontype, irregardless of its elemental or isotopic details. + The value resolve_element will set an ion active, and most importantly, + account as many times for it, as the (molecular) ion contains + atoms of elements in the whitelist ion_query_isotope_vector. + The value resolve_isotope will set an ion active, and most importantly, + account as many times for it, as the (molecular) ion contains isotopes + in the whitelist ion_query_isotope_vector. + + In effect, ion_query_isotope_vector acts as a whitelist to filter + which ions are considered as source ions of the correlation statistics + and how the multiplicity of each ion will be factorized. + + This is relevant as in atom probe we have the situation that a ion + of a molecular ion with more than one nuclid, say Ti O for example + is counted such that although there is a single TiO molecular ion + at a position that the cluster has two members. This multiplicity + affects the size of the feature and chemical composition. + + + + + + + + + Matrix of isotope vectors, as many as rows as different candidates + for iontypes should be distinguished as possible source iontypes. + In the simplest case, the matrix contains only the proton number + of the element in the row, all other values set to zero. + Combined with ion_query_type_source set to resolve_element this will + recover usual spatial correlation statistics like the 1NN C-C + spatial statistics. + + + + + + + + + Settings for DBScan clustering algorithm. For original details about the + algorithms and (performance-relevant) details consider: + + * `M. Ester et al. <https://dx.doi.org/10.5555/3001460.3001507>`_ + * `M. Götz et al. <https://dx.doi.org/10.1145/2834892.2834894>`_ + + For details about how the DBScan algorithms is the key behind the + specific modification known as the maximum-separation method in the + atom probe community consider `E. Jägle et al. <https://dx.doi.org/10.1017/S1431927614013294>`_ + + + + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + As an example we may define eps with ten entries and min_pts with + three entries. If high_throughput_method is tuple the analysis is + invalid as we have an insufficient number of min_pts for the ten + eps values. + By contrast, for combinatorics paraprobe-clusterer will run three + individual min_pts runs for each eps value, resulting in a total + of 30 analyses. + As an example the DBScan analysis reported in `M. Kühbach et al. <https://dx.doi.org/10.1038/s41524-020-00486-1>`_ + would have defined an array of values np.linspace(0.2, 5.0, nums=241, endpoint=True) + eps values, min_pts one, and high_throughput_method set to combinatorics. + + + + + + + + + Array of epsilon (eps) parameter values. + + + + + + + + Array of minimum points (min_pts) parameter values. + + + + + + + + + + Settings for the OPTICS clustering algorithm. + + * `M. Ankerest et al. <https://dx.doi.org/10.1145/304181.304187>`_ + + + + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + See the explanation for the corresponding parameter for dbscan + processes above-mentioned for further details. + + + + + + + + + Array of minimum points (min_pts) parameter values. + + + + + + + + Array of maximum epsilon (eps) parameter values. + + + + + + + + + Settings for the HPDBScan clustering algorithm. + + * L. McInnes et al. <https://dx.doi.org/10.21105/joss.00205>`_ + * scikit-learn hdbscan library `<https://hdbscan.readthedocs.io/en/latest/how_hdbscan_works.html>`_ + + See also this documentation for details about the parameter. + Here we use the terminology of the hdbscan documentation. + + + + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + See the explanation for the corresponding parameter for dbscan + processes above-mentioned for further details. + + + + + + + + + Array of min_cluster_size parameter values. + + + + + + + + Array of min_samples parameter values. + + + + + + + + Array of cluster_selection parameter values. + + + + + + + + Array of alpha parameter values. + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_distancer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_distancer.nxdl.xml new file mode 100644 index 0000000000..1d7b252085 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_distancer.nxdl.xml @@ -0,0 +1,257 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Configuration/settings of a paraprobe-distancer software tool run. + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + How many individual analyses should the tool execute. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Compute for all filtered points, e.g. ions of the point set + the shortest Euclidean distance to the closest triangle of the + set of triangles. The triangles can formed a closed surface mesh. + Distances are not simple distances based on normal projections but + giving an exact solution. + + + + + Paraprobe-distancer enables the computation of the Euclidean shortest + distance for each member of a set of points against a set of triangles. + In contrast to comparable methods used in atom probe the here computed + distance is not simply the projected distance to one of the triangles + but the more costly but robust computation of the distance between + a point and a triangle. + + The triangles can represent for instance the facets of a triangulated + surface mesh of a model for the edge of the dataset. Such a model can + be computed with paraprobe-surfacer. Alternatively, the triangles can + be those from the set of all facets for a set of convex hulls, alpha-shapes, + or alpha wrappings about three-dimensional objects like precipitates + (computed with e.g. paraprobe-nanochem). + + Currently, the tool does not check if the respectively specified + triangle sets are consistent, what their topology is, or whether or + not they are consistently oriented. + Each dataset that is referred to in the list_of _dataset_names_vertices + should be an (Nvertices, 3) array of NX_FLOAT. Each dataset referred + to in the list_of_dataset_names_facet_indices should be an + (Nfacets, 3) array of NX_UINT. + Facet indices refer to vertex indices. These need to start at zero + and must not exceed Nvertices - 1, i.e. the identifier_offset is 0 + and vertices are indexed thus implicitly. + Facet normal vectors have to be also an array + of shape (Nfacets, 3) of NX_FLOAT. + + + + How many triangle sets to consider. + + + + + List of triangle sets. This design allows users to combine + multiple triangle sets. + + + + Name of the HDF5 file(s) which contain(s) vertex coordinates + and facet indices to describe the desired set of triangles. + + + + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility. + + + + + + Absolute HDF5 path to the dataset which + specifies the array of vertex positions. + + + + + Absolute HDF5 path to the dataset which + specifies the array of facet indices. + + + + + Absolute HDF5 path to the dataset which + specifies the array of facet normal vectors. + + + + + + + Specifies for which ions/points the tool will compute distances. + The purpose of this setting is to avoid unnecessary computations + when the user requests to only compute distances of ions within a + threshold distance to the triangle soup. + + By default the distances are computed for all ions; however + the setting skin enables to compute distances only for those + ions which are not farther away located to a triangle + than threshold_distance. + + + + + + + + + + Maximum distance for which distances are computed when method is skin. + + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_intersector.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_intersector.nxdl.xml new file mode 100644 index 0000000000..f8de608ff4 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_intersector.nxdl.xml @@ -0,0 +1,348 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Configuration of a paraprobe-intersector tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to + UTC information included when this configuration file was created. + + + + + For now a support field for the tool to identify how many individual + analyses the tool should execute as part of the analysis. + + + + + Tracking volume_volume_spatial_correlation is the process of building logical + relations between volumetric features based on meshes, their proximity and + eventual intersections. Volumetric overlap and proximity of volumetric + features is identified for members of sets of features to members of + other sets of volumetric features. + Specifically, for each time step k pairs of sets are compared: + Members of a so-called current_set to members of a so-called next_set. + Members can be different types of volumetric features. + In the analysis of M. Kuehbach et al. specifically features can be + so-called objects (closed non-degnerated polyhedra representing watertight + parts of an e.g. iso-surface) and/or proxies. Proxies are computed + doppelganger/replacement meshes for parts of an iso-surface which initially + were not resulting in watertight meshes because objects at the edge + of the dataset or incompletely measured or truncated objects. + + + + Specifies the method whereby to decide if two objects intersect volumetrically. + For reasons which are detailed in the supplementary material of + `M. Kühbach et al. <https://arxiv.org/abs/2205.13510>`_, the tool by + default assumes that two objects intersect if they share at least one + ion with the same evaporation ID (shared_ion). + Alternatively, with specifying tetrahedra_intersections, + the tool can perform an intersection analysis which attempts to + tetrahedralize first each polyhedron. If successful, the tool then checks + for at least one pair of intersecting tetrahedra to identify if two objects + intersect or not. + + However, we found that these geometrical analyses can result in corner + cases which the currently used library (TetGen) was not unable to + tetrahedralize successfully. These cases were virtually always + associated with complicated non-convex polyhedra which had portions + of the mesh that were connected by almost point like tubes of triangles. + Finding more robust methods for computing intersections between + not necessarily convex polyhedra might improve the situation in the future. + + + + + + + + Specifies if the tool evaluates if for each pair the two objects + (and proxies if used) intersect volumetrically. + + + + + Specifies if the tool evaluates if for each pair the two objects + (and proxies if used) lie closer to one another than the + threshold_proximity. + + + + + Specifies if the tool evaluates, ones all tracking tasks were + successfully completed, how intersecting or proximity related + objects build sub-graphs. This is the feature which enabled + M. Kühbach et al. 2022 the high-throughput analyses of how many + objects are coprecipitates in the sense that they are single, + duplet, triplet, or high-order. For these analyses to work + has_object_volume needs to be activated. + + + + + The maximum Euclidean distance between two objects below which + both objects are still considered within proximity. + + + + + + Specifies if the tool stores the so-called forward relations between + nodes representing members of the current_set to nodes representing + members of the next_set. + + + + + Specifies if the tool stores the so-called backward relations between + nodes representing members of the next_set to nodes representing + members of the current_set. + + + + + Current set stores a set of members, meshes of volumetric features, + which will be checked for proximity and/or volumetric intersection, + to members of the current_set. + The meshes were generated as a result of some other meshing process. + + + + This identifier can be used to label the current set. The label + effectively represents (can be interpreted as) the time/iteration + step when the current set was taken. As it is detailed in `M. Kühbach + et al. 2022 <https://arxiv.org/abs/2205.13510>`_, this identifier + takes the role of the time variable :math:`k`. + + + + + + The total number of distinguished feature sets FEATURE. + It is assumed that the members within all these FEATURE sets + are representing a set together. As an example this set might represent + all volumetric_features. However, users might have formed + a subset of this set where individuals were regrouped. + For paraprobe-nanochem this is the case for objects and proxies. + Specifically, objects are distinguished further into those far + from and those close to the edge of the dataset. + Similarly, proxies are distinguished further into those far + from and those close to the edge of the dataset. + So while these four sub-sets contain different so-called types of + features key is that they were all generated for one set, here the + current_set. + + + + + + Descriptive category explaining what these features are. + + + + + + + + + + + Name of the (NeXus)/HDF5 file which contains triangulated + surface meshes of the members of the set as instances of + NXcg_polyhedron_set. + + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + String whereby the path to the geometry data can be interferred automatically. + Currently groupname_geometry_prefix/object<ID>/polyhedron. + + + + + Array of identifier whereby the path to the geometry data + can be interferred automatically. + + + + + + + + + + Next set stores a set of members, meshes of volumetric features, + which will be checked for proximity and/or volumetric intersection, + to members of the next_set. + The meshes were generated as a result of some other meshing process. + + + + This identifier can be used to label the next_set. The label + effectively represents (can be interpreted as) the time/iteration + step when the current set was taken. As it is detailed in `M. Kühbach + et al. 2022 <https://arxiv.org/abs/2205.13510>`_, this identifier + takes the role of the time variable :math:`k + 1`. + + + + + + The total number of distinguished feature sets FEATURE. + It is assumed that the members within all these FEATURE sets + are representing a set together. As an example this set might represent + all volumetric_features. However, users might have formed + a subset of this set where individuals were regrouped. + For paraprobe-nanochem this is the case for objects and proxies. + Specifically, objects are distinguished further into those far + from and those close to the edge of the dataset. + Similarly, proxies are distinguished further into those far + from and those close to the edge of the dataset. + So while these four sub-sets contain different so-called types of + features key is that they were all generated for one set, here the + next_set. + + + + + + Descriptive category explaining what these features are. + + + + + + + + + + + Name of the (NeXus)/HDF5 file which contains triangulated + surface meshes of the members of the set as instances of + NXcg_polyhedron_set. + + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + String whereby the path to the geometry data can be interferred automatically. + Currently groupname_geometry_prefix/object<ID>/polyhedron. + + + + + Array of identifier whereby the path to the geometry data + can be interferred automatically. + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_nanochem.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_nanochem.nxdl.xml new file mode 100644 index 0000000000..9b2564cf71 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_nanochem.nxdl.xml @@ -0,0 +1,1114 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + How many iontypes does the delocalization filter specify. + + + + + How many disjoint control points are defined. + + + + + How many iontypes does the interface meshing iontype filter specify. + + + + + How many DCOM iterations. + + + + + Maximum number of atoms per molecular ion. + + + + + Configuration of a paraprobe-nanochem tool run in atom probe microscopy. + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to + UTC information included when this configuration file was created. + + + + + How many individual analyses should the tool execute as part of the analysis. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The tool enables to inject a previously computed triangle soup or + triangulated surface mesh representing a model (of the surface) of + the edge of the dataset. This model can be used to detect and control + various sources of bias in the analyses. + + + + + Name of the HDF5 file which contains vertex coordinates and facet + indices to describe the desired set of triangles which represents + the edge of the dataset. + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + Absolute path to the HDF5 dataset in the respectively specified HDF5 + file under filename which details the array of vertex positions. + + + + + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details the array of facet indices. + + + + + + The tool enables to inject precomputed distance information for each + point/ion which can be used for further post-processing and analysis. + + + + + Name of an HDF5 file which contains the ion distances. + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + Absolute HDF5 path to the dataset with distance values for each ion. + + + + + + + + Discretization of the ion point cloud on a three-dimensional grid. + + + + Delocalization in the field of atom probe microscopy is the process + of discretizing a point cloud. By default the tool computes a full + kernel density estimation of decomposed ions to create one discretized + field for each element. + + Although, this uses an efficient multithreaded algorithm, + the computation is costly. Therefore, it can be advantageous for users + to load an already computed delocalization. This can be achieved with + the load_existent option. + When using this option the user is responsible to assure that the + settings which were used for computing this already existent delocalization + are specified in the same manner as they were. + + + + + + + + + + + Matrix of isotope vectors representing iontypes. + The filter specifies a matrix of isotope_vectors which is the most + general approach to define if and how many times an ion is counted. + Currently, paraprobe_nanochem performs a so-called atomic decomposition + of all iontypes. Specifically, the tool interprets of how many + elements/atoms a molecular ion is composed; and thus determines the + atoms multiplicity with respect to the iontype. + + Let's take the hydroxonium H3O+ molecular ion as an example: + It contains hydrogen and oxygen as atoms. The multiplicity of hydrogen + is three whereas that of oxygen is one. Therefore in an atomic + decomposition computation of the iso-surface each H3O+ ion adds + three hydrogen counts. This is a practical solution which accepts + the situation that during an atom probe experiment not each bond + of each ion/a group of neighboring atoms is broken but molecular + ions get detected. The exact ab-initio details depend on the local + field conditions and thus also the detailed spatial arrangement + of the atoms and their own electronic state and that of the neighbors + before and upon launch. + Being able to measure the information for such sites only as + molecular ions causes an inherent information loss with respect to the + detailed spatial arrangement. This information loss is more relevant + for local electrode atom probe than for field ion microscopy setting + how precisely the atomic positions can be reconstructed. + Accounting for multiplicities assures that at least the + compositional information is analyzed. + + + + + + + + + List of individual grid resolutions to analyse. + Paraprobe discretizes on a cuboidal 3D grid with cubic cells, with + an edge length of values in gridresolutions. + + + + + + Half the width of a :math:`{(2 \cdot n + 1)}^3` cubic kernel of voxel + beyond which the Gaussian Ansatz function will be truncated. + Intensity beyond the kernel is refactored into the kernel via + a normalization procedure. + + + + + Variance of the Gaussian Ansatz kernel :math:`\sigma_x = \sigma_y = 2 \cdot + \sigma_z`. + + + + + + How should the results of the kernel-density estimation be computed + into quantities. By default the tool computes the total number + (intensity) of ions or elements. Alternatively the tool can compute + the total intensity, the composition, or the concentration of the + ions/elements specified by the white list of elements in each voxel. + + + + + + + + + + + Specifies if the tool should report the delocalization 3D field values. + + + + + + + Optional computation of iso-surfaces after each computed delocalization + to identify for instance objects in the microstructure + (line features, interfaces, precipitates). + + + + As it is detailed in M. Kühbach et al. 2022 npj Comp. Mat., + the handling of triangles at the edge of the dataset requires + special attention. Especially for composition-normalized + delocalization it is possible that the composition increases + towards the edge of the dataset because the quotient of two numbers + which are both smaller than one is larger instead of smaller than + the counter. By default, the tool uses a modified marching cubes + algorithm of Lewiner et al. which detects if voxels face such a + situation. In this case, no triangles are generated for such voxels. + Alternatively, (via setting keep_edge_triangles) the user can + instruct the tool to not remove these triangles at the cost of bias. + + Specifically, in this case the user should understand that all + objects/microstructural features in contact with the edge of the + dataset get usually artificial enlarged and their surface mesh + often closed during the marching. This closure however is artificial! + It can result in biased shape analyses for those objects. + The reason why this should in general be avoided is a similar + argument as when one analyzes grain shapes in orientation microscopy + via e.g. SEM/EBSD. Namely, these grains, here the objects at the + edge of the dataset, were not fully captured during e.g. limited + field of view. + Therefore, it is questionable if one would like to make + substantiated quantitative statements about them. + + Thanks to collaboration with the V. V. Rielli and S. Primig, though, + paraprobe-nanochem implements a complete pipeline to + process even these objects at the edge of the dataset. Specifically, + the objects are replaced by so-called proxies, i.e. replacement + objects whose holes on the surface mesh have been closed if possible + via iterative mesh and hole-filling procedures with fairing operations. + In the results of each paraprobe-nanochem run, these proxy objects + are listed separately to allow users to quantify and analyze in + detail the differences when accounting for these objects or not. + Especially this is relevant in atom probe microscopy as objects + can contain a few dozen atoms only. + Users should be aware that results from fairing operations should + be compared to results from analyses where all objects at the edge + of the dataset have been removed. + + Also users should be careful with overestimating the statistical + significance of their dataset especially when using atom probe + to compare multiple descriptors: Even though a dataset may give + statistically significant results for compositions, this does not + necessarily mean it will yield also statistically significant + and unbiased results for three-dimensional object analyses. + Being able to quantify these effects and making atom probers + aware of these subtleties was one of the main reasons why the + paraprobe-nanochem tool was implemented. + + + + + + + + + The ion-to-edge-distance that is used in the analyses of objects + (and proxies) to identify whether these are inside the dataset or + close to the edge of the dataset. If an object has at least one ion + with an ion-to-edge-distance below this threshold, the object is + considered as one which lies close to the edge of the dataset. + This implements essentially a distance-based approach to solve + the in general complicated and involved treatment of computing + volumetric intersections between not-necessarily convex + closed 2-manifolds. In fact, such computational geometry analyses + can face numerical robustness issues as a consequence of which a + mesh can be detected as lying completely inside a dataset although + in reality it is epsilon-close only, i.e. almost touching only + the edge (e.g. from inside). + Practically, humans would state in such case that the object is + close to the edge of the dataset; however mathematically the object + is indeed completely inside. + In short, a distance-based approach is rigorous and more flexible. + + + + + + Array of iso-contour values. For each value the tool computes + an iso-surface and performs subsequent analyses. + The unit depends on the choice for the normalization of the + accumulated ion intensity values per voxel: + + * total, total number of ions, irrespective their iontype + * candidates, total number of ions with type in the isotope_whitelist. + * composition, candidates but normalized by composition, i.e. at.-% + * concentration, candidates but normalized by voxel volume, i.e. ions/nm^3 + + + + + + Specifies if the tool should report the triangle soup which represents + each triangle of the iso-surface complex. + Each triangle is reported with an ID specifying to which triangle + cluster (with IDs starting at zero) the triangle belongs. + The clustering is performed with a modified DBScan algorithm. + + + + + Specifies if the tool should analyze for each cluster of triangles + how they can be combinatorially processed to describe a closed + polyhedron. Such a closed polyhedron (not-necessarily convex!) + can be used to describe objects with relevance in the microstructure. + Users should be aware that the resulting mesh does not necessarily + represent the original precipitate. In fact, inaccuracies in the + reconstructed positions cause inaccuracies in all downstream + processing operations. Especially the effect on one-dimensional + spatial statistics like nearest neighbor correlation functions these + effects were discussed in the literature + `B. Gault et al. <https://doi.org/10.1017/S1431927621012952>`_ + In continuation of these thoughts this applies also to reconstructed + objects. A well-known example is the discussion of shape deviations + of Al3Sc precipitates in aluminium alloys which in reconstructions + can appear as ellipsoids although they should be almost spherical, + depending on their size. + + + + + Specifies if the tool should report a triangulated surface mesh + for each identified closed polyhedron. It is common that a + marching cubes algorithm creates iso-surfaces with a fraction of very + small sub-complexes (e.g. small isolated tetrahedra). + + These can be for instance be small tetrahedra/polyhedra about the + center of a voxel of the support grid on which marching cubes operates. + When these objects are small, it is possible that they contain no ion; + especially when considering that delocalization procedures smoothen + the positions of the ions. Although these small objects are interesting + from a numerical point of view, scientists may argue they are not worth + to be reported: + Physically a microstructural feature should contain at least a few + atoms to become relevant. Therefore, paraprobe-nanochem by default + does not report closed objects which bound not at least one ion. + + + + + Specifies if the tool should report properties of each closed + polyhedron, such as volume and other details. + + + + + Specifies if the tool should report for each closed polyhedron an + approximately optimal bounding box fitted to all triangles of the + surface mesh of the object and ion positions inside or on the + surface of the mesh. + This bounding box informs about the closed object's shape + (aspect ratios). + + + + + + Specifies if the tool should report for each closed polyhedron + all evaporation IDs of those ions which lie inside or on the + boundary of the polyhedron. This information can be used e.g. + in the paraprobe-intersector tool to infer if two objects share + common ions, which can be interpreted as an argument to assume + that the two objects intersect. + + Users should be aware that two arbitrarily closed polyhedra + in three-dimensional space can intersect but not share a common ion. + In fact, the volume bounded by the polyhedron has sharp edges. + When taking two objects, an edge of one object may for instance + pierce into the surface of another object. In this case the + objects partially overlap / intersect volumetrically; + however this piercing might be so small or happening in the volume + between two ion positions and thus sharing ions is a sufficient + but not a necessary condition for object intersections. + + Paraprobe-intersector implements a rigorous alternative to handle + such intersections using a tetrahedralization of closed objects. + However, in many practical cases, we found through examples that there + are polyhedra (especially when they are non-convex and have almost + point-like) connected channels, where tetrahedralization libraries + have challenges dealing with. In this case checking intersections + via shared_ions is a more practical alternative. + + + + + Specifies if the tool should report if a (closed) object has + contact with the edge of the dataset. For this the tool currently + inspects if the shortest distance between the set of triangles of the + surface mesh and the triangles of the edge model is larger than the + edge_threshold. If this is the case, the object is assumed to be + deeply embedded in the interior of the dataset. Otherwise, the object + is considered to have an edge contact, i.e. it is likely affected + by the fact that the dataset is finite. + + + + + + Specifies if the tool should analyze a doppelganger/proxy mesh for + each cluster of triangles whose combinatorial analysis according + to has_object showed that the object is not a closed polyhedron. + Such proxies are closed via iterative hole-filling, mesh refinement, + and fairing operations. + Users should be aware that the resulting mesh does not necessarily + represent the original precipitate. In most cases objects, + like precipitates in atom probe end up as open objects because + they have been clipped by the edge of the dataset. Using a proxy is + then a strategy to still be able to account for these objects. + Nevertheless users should make themselves familiar with the + potential consequences and biases which this can introduce + into the analysis. + + + + + Like has_object_geometry but for the proxies. + + + + + Like has_object_properties but for the proxies. + + + + + Like has_object_obb but for the proxies. + + + + + Like has_object_ions but for the proxies. + + + + + Like has_object_edge_contact but for the proxies. + + + + + Specifies if the tool should report for each closed object a + (cylindrical) region of interest placed, centered, and align + with the local normal for each triangle of the object. + + + + + Specifies if the tool should report for each ROI that was placed + at a triangle of each object if this ROI intersects the edge of + the dataset. Currently paraprobe-nanochem supports cylindrical + ROIs. A possible intersection of these with the edge of the + dataset, i.e. the triangulated surface mesh model for the edge + is performed. This test checks if the cylinder intersects with + a triangle of the surface mesh. If this is the case, the ROI is + assumed to make edge contact, else, the ROI is assumed to have + no edge contact. + + This approach does not work if the ROI would be completely + outside the dataset. Also in this case there would be + no intersection. For atom probe this case is practically + irrelevant because for such a ROI there would also be no ion + laying inside the ROI. Clearly it has thus to be assumed that + the edge model culls the entire dataset. Instead, if one would + cut a portion of the dataset, compute an edge model for this + point cloud, it might make sense to place a ROI but in this + case the edge contact detection is not expected to work properly. + + + + + + + Analyses of interfacial excess. + + + + Interfacial excess computations are performed for local regions-of-interests + (ROIs) at selected facets or interface patch. + For instance many scientist compute the interfacial excess for + selected triangle facets of a created iso-surface. In this case, + computed iso-surfaces of paraprobe could be used. An example are triangle + facet sets about closed polyhedra, for instance to compute interfacial + excess related to phase boundaries of second-phase precipitates. + + Another example are free-standing triangle patches of the iso- + surfaces which paraprobe creates. These could be characterized + for interfacial excess. The sub-routines during iso-surface + computations already include a procedure to automatically align + local triangle normals based on the gradients of e.g. composition + fields. In this case, these triangulated surface patches + could also be used as a source for computing interfacial + excess. + + Often scientists face situations, though, in which there is no + immediately evident composition gradient across the interface + (grain or phase boundary) and orientation information about the + adjoining crystal is neither available nor reliable enough. + + In this case `P. Felfer et al. <https://doi.org/10.1016/j.ultramic.2015.06.002>`_ proposed a method + to manually place control points and run an automated tessellation-based + algorithm to create a triangulated surface patch, i.e. a model of the + location of the interface. In a post-processing step this triangle + set can then be used to compute again interfacial excess in an + automated manner by placing ROIs and aligning them with + consistently precomputed triangle normals. + + A similar use case is conceptually the one proposed by `X. Zhou et al. <https://doi.org/10.1016/j.actamat.2022.117633>`_ + They used first a deep-learning method to locate planar triangulated + grain boundary patches. These are eventually processed further + with manual editing of the mesh via tools like Blender. + Once the user is satisfied with the mesh, the computations of interfacial + excess reduce again to an automated placing of ROIs, computations + of the distributing of ions to respective ROIs and + reporting the findings via plotting. + + Yet another approach for constructing an triangulated surface patch + of an interface is to use point cloud processing methods which have + been proposed in the laser-scanning, geoinformatics, and CAD community. + Different computational geometry methods are available for fitting + a parameterized surface to a set of points, using e.g. non-uniform + rational B-splines (NURBS) and triangulating these according + to prescribed mesh quality demands. + + The advantage of these methods is that they can be automated and + pick up curved interface segments. The disadvantage is their often + strong sensitivity to parameterization. As a result also such methods + can be post-processed to yield a triangulated surface patch, + and thus enable to run again automated ROI placement methods. + For example like these which were explored for the use case of + iso-surfaces with closed objects and free-standing + surface patches that delineate regions of the dataset with a + pronounced composition gradient normal to the interface. + + This summary of the situations which atom probers can face when + requesting for interfacial excess computations, substantiates there + exists a common set of settings which can describe all of these methods + and, specifically, as here exemplified, the automated placing + and alignment functionalities for ROIs that is an important + step all these workflows. + + Specifically, paraprobe-nanochem operates on an already existent + triangle set. + + + + + + + + + + The interface model is the result of a previous (set of) processing + steps as a result of which the user has created a triangulated + surface mesh (or a set of, eventually connected such meshes). + These interface models are useful, if not required, in cases when + there is no other independent approach to locate an interface. + + These are cases when insufficient crystallographic latent + information is available and also no consistent concentration + gradient detectable across the interface. It is then the users' + responsibility to deliver a triangle mesh of the interface model. + + + + Filename to HDF5 file which contain vertex coordinates, facet indices, + facet unit normals. The user is responsible for the triangle + and winding order to be consistent. + Input is expected as a matrix of the coordinates for all disjoint + vertices, a (Nvertices, 3)-shaped array of NX_FLOAT. + Input is expected to include also a matrix of facet indices + referring to these disjoint vertices. This matrix should be a + (Nfacets, 3)-shaped array of NX_UINT. Further required input + is a (Nfacets, 3)-shaped array of NX_FLOAT signed facet unit + normals and a (Nvertices, 3)-shaped array of NX_FLOAT signed + vertex unit normals. Vertex indices need to start at zero and + must not exceed Nvertices - 1, i.e. the identifier_offset is 0 + and facet indices are indexed implicitly, i.e. [0, Nvertices-1]. + + + + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically + contains these data. + + + + + + Absolute HDF5 path to the dataset which specifies the + array of vertex positions. + + + + + Absolute HDF5 path to the dataset which specifies the + array of facet indices. + + + + + Absolute HDF5 path to the dataset which specifies the + array of facet signed unit normals. + + + + + Absolute HDF5 path to the dataset which specifies the + array of vertex signed unit normals. + + Users should be aware that triangulated surface meshes are + only approximations to a given complex, eventually curved shape. + Consequently, computations of normals show differences between + the vertex and facet normals. Vertex normals have to be + interpolated from normals of neighboring facets. Consequently, + these normals are affected by the underlying parameterization + and curvature estimation algorithms, irrespective of how + contributions from neighboring facets are weighted. By contrast, + facet normals are clearly defined by the associated triangle. + Their disadvantage is that they the normal field has discontinuities + at the edges. In general the coarser an object is triangulated + the more significant the difference becomes between computations + based on facet or vertex normals. + Paraprobe-nanochem works with facet normals as it can use + parts of the numerical performance gained by using cutting + edge libraries to work rather with finer meshes. + + + + + + + + Create a simple principle component analysis (PCA) to mesh a + free-standing interface patch through a point cloud of decorating solutes. + These models can be useful for quantification of Gibbsian + interfacial excess for interfaces where iso-surface based methods + may fail or closed objects from iso-surfaces are not desired or + when e.g. there are no substantial or consistently oriented + concentration gradients across the interface patch. + + The interface_meshing functionality of paraprobe-nanochem can be useful + when there is also insufficient latent crystallographic information + available that could otherwise support modelling the interface, + via e.g. ion density traces in field-desorption maps, as were used and + discussed by `Y. Wei et al. <https://doi.org/10.1371/journal.pone.0225041>`_ + or are discussed by `A. Breen et al. <https://github.com/breen-aj/detector>`_ + + It is noteworthy that the method here used is conceptually very similar + in implementation to the work by `Z. Peng et al. <https://doi.org/10.1017/S1431927618016112>`_ + Noteworthy, her team uses the DCOM approach originally proposed by P. Felfer et al. + However, both of these previous works neither discuss in detail + nor implement inspection functionalities which enable a detection of + potential geometric inconsistencies or self-interactions of the + resulting DCOM mesh. This is what paraprobe-nanochem implements + via the Computational Geometry Algorithms Library. + + + + Method how to initialize the PCA: + + * default, means based on segregated solutes in the ROI + * control_point_file, means based on reading an external list of + control points, currently coming from the Leoben APT_Analyzer. + + The control_point_file is currently expected with a specific format. + The Leoben group lead by L. Romaner has developed a GUI tool `A. Reichmann et al. <https://github.com/areichm/APT_analyzer>`_ + to create a control_point_file which can be parsed by paraprobe-parmsetup + to match the here required formatting in control_points. + + + + + + + + + The name of the control point file to use. + + + + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically + contains these data. + + + + + + X, Y, Z coordinates of disjoint control point read from + an HDF5 file named according to control_point_file. + + + + + + + + + + Method used for identifying and refining the location of the + interface. Currently, paraprobe-nanochem implements a PCA followed + by an iterative loop of isotropic mesh refinement and DCOM step(s), + paired with self-intersection detection in a more robust + implementation. + + + + + + + + Specify the types of those ions which decorate the interface and + can thus be assumed as markers for locating the interface and + refining its local curvature. + + + + Array of iontypes to filter. The list is interpreted as a whitelist, + i.e. ions of these types are considered the decorating species (solutes). + + + + + + + + + How many times should the DCOM and mesh refinement be applied? + + + + + Array of decreasing positive not smaller than one nanometer real values + which specify how the initial triangles of the mesh should be iteratively + refined by edge splitting and related mesh refinement operations. + + + + + + + + + Array of decreasing positive not smaller than one nanometer real values + which specify the radius of the spherical region of interest within + which the DCOM algorithm decides for each vertex how the vertex will + be eventually relocated. The larger the DCOM radius is relative to + the target_edge_length the more likely it is that vertices will be + relocated so substantially that eventually triangle self-intersections + can occur. If the code detects these it warns and stops in a + controlled manner so that the user can repeat the analyses + with a smaller value. + + + + + + + + + Array of integers which specify for each DCOM step how many times + the mesh should be iteratively smoothened. + + Users should be aware the three array target_edge_length, + target_dcom_radius, and target_smoothing_step are interpreted in the + same sequence, i.e. the zeroth entry of each array specifies the + values to be used in the first DCOM iteration. The first entry of + each array those for the second DCOM iteration and so on and so forth. + + + + + + + + + Functionalities for placing regions-of-interest (ROIs) in the dataset + or at specific microstructural features to characterize composition + profiles and cumulated profiles for quantification of interfacial excess. + Paraprobe-nanochem currently places cylindrical ROIs. ROIs are probed + across the triangulated surface of a user-defined mesh. + ROIs are placed at the barycenter of the triangular facet. + + The tool can be instructed to orient the profile for each ROIs with + the positive normal of the triangle facet normals. Profiles are + computed for each ROI and facet triangle. The code will test which + ROIs are completely embedded in the dataset. + Specifically, in this test the tool evaluates if the ROI cuts at least + one triangle of the triangulated surface mesh of the edge of the dataset. + If this is the case the ROI will be considered close to the edge + (of the dataset) and not analyzed further; else the ROI will be + processed further. + Users should be aware that the latter intersection analysis is strictly + speaking not a volumetric intersection analysis as such one is much + more involved because the edge model can be a closed non-convex polyhedron + in which case one would have to test robustly if the cylinder pierces + or is laying completely inside the polyhedron. For this the polyhedron has + to be tessellated into convex polyhedra as otherwise tests like the + Gilbert-Johnson-Keerthi algorithm would not be applicable. + + Specifically, the tool computes atomically decomposed profiles. + This means molecular ions are split into atoms/isotopes with respective + multiplicity. As an example an H3O+ molecular ion contains three + hydrogen and one oxygen atom respectively. The tool then evaluates + how many ions are located inside the ROI or on the surface of the + ROI respectively. All atom types and the unranged ions are distinguished. + As a result, the analyses yield for each ROI a set of sorted lists of + signed distance values. Currently, the distance is the projected + distance of the ion position to the barycenter of the triangle + and triangle plane. + + This will return a one-dimensional profile. Post-processing the set + of atom-type-specific profiles into cumulated profiles enable the + classical Krakauer/Seidman-style interfacial excess analyses. + Furthermore, the tool can be instructed to compute for each + (or a selected sub-set of facet) a set of differently oriented profiles. + + + + + The feature mesh enables the injection of previously computed triangle + soup or mesh data. Such a mesh can be the model for a grain- or phase + boundary patch (from e.g. interface_meshing) jobs. + + + + Name of the HDF5 file which contains vertex coordinates and facet + indices to describe the desired set of triangles which represents + the feature. + + + + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + + + + + + Absolute path to the HDF5 dataset in the respectively specified HDF5 + file under filename which details the array of vertex positions. + + + + + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details the array of facet indices. + + + + + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details consistently oriented facet + normals of the facets. + + + + + + + + + + + The tool enables to inject precomputed distance information for each + point which can be used for further post-processing and analysis. + + + + + Name of an HDF5 file which contains ion distances. + + + + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically contains + these data. + + + + + + Absolute HDF5 path to the dataset with distance values for each ion. + + + + + + Which type of distance should be reported for the profile. + + + + + + + + + In which directions should the tool probe for each ROI. + + + + + + + + + For each ROI, how high (projected on the cylinder axis) + should the cylindrical ROI be. + + + + + + For each ROI, how wide (radius) should the cylindrical ROI be. + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_ranger.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_ranger.nxdl.xml new file mode 100644 index 0000000000..903fd73d9b --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_ranger.nxdl.xml @@ -0,0 +1,297 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The number of isotopes to consider as building blocks for searching molecular + ions. + + + + + The number of compositions to consider for molecular ion search tasks. + + + + + Configuration of a paraprobe-ranger tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + How many task to perform? + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A list of pairs of number of protons and either the value 0 (per row) + or the mass number for all those isotopes which are assumed present + in a virtual specimen. + The purpose of this field is to compute also composition-weighted + products to yield a simple estimation which could potentially help + scientists to judge if certain molecular ions are to be expected. + The corresponding setting store_composition_weighted_product should be + activated. + + + + + + + + + + A list of pairs of number of protons and mass number for all isotopes + to consider that can be composed into (molecular) ions, during the + recursive molecular_ion_search. + + + + + + + + + The mass-to-charge-state ratio interval in which + all molecular ions are searched. + + + + + + + + The maximum charge that a molecular ion should have. + + + + + The maximum number of isotopes of which the molecular ion + should be composed. Currently this must not be larger than 32. + + Users should be warned that the larger the maximum_charge and + especially the larger the maximum_number_of_isotopes is chosen, + the eventually orders of magnitude more costly the search becomes. + + This is because paraprobe-ranger computes really all (at least) + theoretically possible combinations that would have likely a + mass-to-charge-state ratio in the specified mass_to_charge_interval. + It is the challenge in atom probe to judge which of these (molecular) + ions are feasible and also practically possible. This tool does not + answer this question. + + Namely, which specific molecular ion will evaporate, remain stable + during flight and becomes detected is a complicated and in many cases + not yet in detail understood phenomenon. The ab-initio conditions + before and during launch, the local environment, arrangement and field + as well as the flight phase in an evacuated but not analysis chamber + with a complex electrical field, eventual laser pulsing in place, + temperature and remaining atoms or molecules all can have an effect + which iontypes are really physically evaporating and detected. + + + + + Report the accumulated atomic mass from each isotope building the ion. + Accounts for each identified ion. + Relatistic effects are not accounted for. + + + + + Report the product of the natural abundances from each isotope building + the ion. Accounts for each identified ion. + + The value zero indicates it is not possible to build such molecular ion + from nuclids which are all observationally stable. + Very small values can give an idea/about how likely such a molecular ion + is expected to form assuming equal probabilities. + + However in atom probe experiments this product has to be modified + by the (spatially-correlated) local composition in the region from + which the ions launch because the formation of a molecular ion depends + as summarized under maximum_number_of_isotopes on the specific + quantum-mechanical configuration and field state upon launch + or/and (early state) of flight respectively. + We are aware that this modified product can have a substantially + different value than the natural_abundance_product. + + Natural abundancies folded with the estimated compositions of the + specimen can differ by orders of magnitude. + + + + + + Report the charge state of the ions. + + + + + Report if identified ions should be characterized + wrt to their number of disjoint isotopes. + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_selector.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_selector.nxdl.xml new file mode 100644 index 0000000000..41d049ef07 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_selector.nxdl.xml @@ -0,0 +1,142 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Configuration of a paraprobe-selector tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + How many roi_selection processes should the tool execute. + + + + + This process identifies which of the points/ions in the datasets are + inside or on the surface of geometric primitives and meet optionally + specific other filtering constraints. + A typical use case of a roi_selection is to restrict analyses to + specific regions of the dataset, eventually regions with a complicated + shape. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_spatstat.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_spatstat.nxdl.xml new file mode 100644 index 0000000000..d9e2b26f0e --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_spatstat.nxdl.xml @@ -0,0 +1,374 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Maximum number of atoms per molecular ion. Should be 32 for paraprobe. + + + + + Number of different sources iontypes to distinguish. + + + + + Number of different target iontypes to distinguish. + + + + + Configuration of a paraprobe-spatstat tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + How many range_with_existent_iontypes processes should + the tool execute as part of the analysis. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The tool enables to inject precomputed distances of each ion to a + representation of the edge of the dataset which can be used to + control and substantially reduce edge effects when computing + spatial statistics. + + + + Name of an HDF5 file which contains ion-to-edge distances. + + + + + Absolute HDF5 path to the dataset with the + ion-to-edge distance values for each ion. + The shape of the distance values has to match the length + of the ion positions array in dataset/dataset_name_reconstruction + and dataset_name_mass_to_charge respectively. + + + + + Threshold to define how large an ion has to lay at least far away + from the edge of the dataset so that the ion can act as a source, + i.e. that an ROI is placed at the location of the ion and its + neighbors are analyzed how they contribute to the computed statistics. + + The ion_to_edge_distances threshold can be combined with a threshold + for the ion_to_feature_distances. + Specifically, if ion_to_feature_distances are loaded an ion only + acts as a source if both threshold criteria are met. + + The threshold is useful to process the dataset such that ROIs do + not protrude out of the dataset as this would add bias. + + + + + + In addition to spatial filtering, and considering how far ions lie + to the edge of the dataset, it is possible to restrict the analyses + to a sub-set of ions within a distance not farther away to a feature than + a threshold value. + + + + Name of an HDF5 file which contains ion-to-feature distances. + + + + + Absolute HDF5 path to the dataset with the + ion-to-feature distance values for each ion. + + + + + Threshold to define how close an ion has to lay to a feature so that + the ion can at all qualify as a source, i.e. that an ROI is placed + at the location of the ion and its neighbors are then analyzed + how they contribute to the computed statistics. + + Recall that the ion_to_feature_distances threshold is combined + with the ion_to_edge_distances threshold. + + + + + + + Specifies if the iontypes are randomized for the point cloud or not. + Internally paraprobe uses a sequentially executed deterministic MT19987 + (MersenneTwister) pseudo-random number generator to shuffle the + iontype labels randomly across the entire set of ions. + + + + + + + + + + How should the iontype be interpreted on the source-side, i.e. + all these ion positions where a regions-of-interest (ROI) around + so-called source ions will be placed. Different options exist + how iontypes are interpreted given an iontype represents + in general a (molecular) ion with different isotopes that have + individually different multiplicity. + + The value resolve_all will set an ion active in the analysis regardless + of which iontype it is. Each active ion is accounted for once. + + The value resolve_unknown will set an ion active when the ion is + of the UNKNOWNTYPE type. Each active ion is accounted for once. + + The value resolve_ion will set an ion active if it is of the specific + iontype, irregardless of its elemental or isotopic details. + Each active ion is counted once. + + The value resolve_element will set an ion active, and most importantly, + account for each as many times as the (molecular) ion contains + atoms of elements in the whitelist ion_query_isotope_vector. + + The value resolve_isotope will set an ion active, and most importantly, + account for each as many times as the (molecular) ion contains + isotopes in the whitelist ion_query_isotope_vector. + + In effect, ion_query_isotope_vector acts as a whitelist to filter + which ions are considered as source ions of the correlation statistics + and how the multiplicity of each ion will be factorized, i.e. how + often it is accounted for. + + + + + + + + + + + + Matrix of isotope vectors, as many as rows as different candidates + for iontypes should be distinguished as possible source iontypes. + In the simplest case, the matrix contains only the proton number + of the element in the row, all other values set to zero. + Combined with ion_query_type_source set to resolve_element this will + recover usual spatial correlation statistics like the 1NN C-C + spatial statistics. + + + + + + + + + Similarly as ion_query_type_source how should iontypes be interpreted + on the target-side, i.e. how many counts will be bookkept for ions + which are neighbors of source ions within or on the surface of each + inspection/ROI about each source ion. + Source ion in the center of the ROI are not accounted for during + counting the summary statistics. + For details about the resolve values consider the explanations in + ion_query_type_source. These account for ion_query_type_target as well. + + + + + + + + + + + + + Matrix of isotope vectors, as many as rows as different candidates for + iontypes to distinguish as possible targets. See additional comments + under ion_query_isotope_vector_source. + + + + + + + + + Specifies which spatial statistics to compute. + + + + Compute k-th nearest neighbour statistics. + + + + Order k. + + + + + Minimum value, increment, and maximum value of the histogram binning. + + + + + + + + + + Compute radial distribution function. + + + + Minimum value, increment, and maximum value of the histogram binning. + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_surfacer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_surfacer.nxdl.xml new file mode 100644 index 0000000000..e421eaaaa0 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_surfacer.nxdl.xml @@ -0,0 +1,289 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of alpha values (and offset values) to probe. + + + + + How many different match values does the filter specify. + + + + + Configuration of a paraprobe-surfacer tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + For now a support field for the tool to identify how many individual + analyses the tool should executed as part of the analysis. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specifies the method that is used to preprocess the point cloud. + The main purpose of this setting is to specify whether the point + cloud should be segmented or not during the preprocessing + to identify which points are more likely lying close to the edge + of the point cloud. These points could be more relevant than the + interior points for certain alpha-shape constructions. + + By default no such filtering is used during pre-processing. + By contrast, the option kuehbach activates a preprocessing + during which a Hoshen-Kopelman percolation analysis is used + to identify which points are closer to the edge of the dataset. + This can reduce the number of points in the alpha-shape + computation and thus improve performance substantially. + Details about the methods are reported in + `M. Kühbach et al. <https://doi.org/10.1038/s41524-020-00486-1>`_. + + + + + + + + + + When using the kuehbach preprocessing, this is the width of the + kernel for identifying which ions are in voxels close to the + edge of the point cloud. + + + + + Specifies which method to use to define the alpha value. + The value convex_hull_naive is the default. This instructs the tool + to use a fast specialized algorithm for computing only the convex + hull. The resulting triangles can be skinny. + + The value convex_hull_refine computes first also a convex_hull_naive + but refines the mesh by triangle flipping and splitting to improve + the quality of the mesh. + + The value smallest_solid instructs the CGAL library to choose a + value which realizes an alpha-shape that is the smallest solid. + + The value cgal_optimal instructs the library to choose a value + which the library considers as an optimal value. Details are + define in the respective section of the CGAL library on 3D alpha + shapes. + + The value set_of_values instructs to compute a list of + alpha-shapes for the specified alpha-values. + + The value set_of_alpha_wrappings instructs the library to generate + a set of so-called alpha wrappings. These are a method + which is similar to alpha shapes but provide additional guarantees + though such as watertightness and proximity constraints on the + resulting wrapping. + + + + + + + + + + + + + + Array of alpha values to use when alpha_value_choice is set_of_values + or when alpha_value_choice is set_of_alpha_wrappings. + + + + + + + + + Array of offset values to use when alpha_value_choice is + set_of_alpha_wrappings. The array of alpha_values and offset_values + define a sequence of (alpha and offset value). + + + + + + + + + Specifies if the tool should compute the set of exterior triangle + facets for each alpha complex (for convex hull, alpha shapes, and wrappings) + + + + + Specifies if the tool should check if the alpha complex of exterior + triangular facets is a closed polyhedron. + + + + + Specifies if the tool should compute all interior tetrahedra + of the alpha complex (currently only for alpha shapes). + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_tessellator.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_tessellator.nxdl.xml new file mode 100644 index 0000000000..24f2202166 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_tessellator.nxdl.xml @@ -0,0 +1,253 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Configuration of a paraprobe-tessellator tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + How many individual analyses should the tool execute. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The tool enables to inject precomputed distance information for + each point which can be used for further post-processing and analysis. + + + + Name of an HDF5 file which contains the ion distances. + Users are responsible this file and referred to dataset under + dataset_name have an ion_distance value for each ion. + + + + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional layer of + reproducibility. + + + + + + Absolute HDF5 path to the dataset with distance values for each ion. + + + + + + + Specifies for which points the tool will compute the tessellation. + By default, a Voronoi tessellation is computed for all ions in the + filtered point cloud. + + + + + + + + + + Specifies if the tool should report the volume of each cell. + + + + + Specifies if the tool should report the first-order neighbors of each cell. + + + + + Specifies if the tool should report the facets and vertices of each cell. + + + + + Specifies if the tool should report if the cell makes contact with + the tight axis-aligned bounding box about the point cloud. + This can be used to identify if the shape of the cell is affected + by the edge of the dataset or if cells are deeply enough embedded + into the point cloud so that the shape of their cells are not affected + by the presence of the boundary. + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_config_transcoder.nxdl.xml b/contributed_definitions/NXapm_paraprobe_config_transcoder.nxdl.xml new file mode 100644 index 0000000000..fb4973f03b --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_config_transcoder.nxdl.xml @@ -0,0 +1,119 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Configurations of a paraprobe-transcoder tool run in atom probe microscopy. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ideally an ever persistent resource where the source code of the + program and build instructions can be found so that the program can be + configured ideally in such a manner that the result of this computational + process is recreatable deterministically. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + + + + The path and name of the file (technology partner or community format) + from which to read the reconstructed ion positions. Currently, POS, + ePOS, APT files from APSuite, and NXS, i.e. NeXus/HDF5 files + are supported. + + + + + + + + The path and name of the file (technology partner or community format + from which to read the ranging definitions, i.e. how to map mass-to- + charge-state ratios on iontypes. Currently, RRNG, RNG, and NXS, i.e. + NeXus/HDF5 files are supported. + + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_clusterer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_clusterer.nxdl.xml new file mode 100644 index 0000000000..74b8a6133d --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_clusterer.nxdl.xml @@ -0,0 +1,503 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + The total number of entries in the restricted_identifier dictionary. + + + + + Results of a paraprobe-clusterer tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must no longer compute analyses. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases, it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + If nothing else is specified we assume that there + has to be at least one set of NXtransformations named + paraprobe defined, which specifies the coordinate system. + In which all positions are defined. + + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + A bitmask which identifies which of the ions in the dataset were + analyzed during this process. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used, padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe-toolbox executable. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth (padding). + + + + + + + + + The result of a cluster analyses. These include typically the label for + each ion/point documenting to which feature (if any) an ion is assigned. + Typically, each analysis/run yields only a single cluster. + In cases of fuzzy clustering it can be possible that an ion is assigned + to multiple cluster (eventually with different) weight/probability. + + + + Results of a DBScan clustering analysis. + + + + The epsilon (eps) parameter. + + + + + The minimum points (min_pts) parameter. + + + + + Number of members in the set which is partitioned into features. + Specifically, this is the total number of targets filtered from the + dataset. Cardinality here is not the total number of ions in the + dataset. + + + + + + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + Numerical identifier have to be strictly increasing. + + + + + + The evaporation sequence identifier to figure out which ions + from the reconstruction were considered targets. + + + + + + + + + The raw labels from the DBScan clustering backend process. + + + + + + + + The raw array of core sample indices which specify which of the + targets are core points. + + + + + + + + + Matrix of numerical label for each member in the set. + For classical clustering algorithms this can for instance + encode the cluster_identifier. + + + + + + + + + The array of weight which specifies how surely/likely the + cluster is associated/assigned to a specific identifier as + is specified in the cluster_identifier array. + For the DBScan and atom probe tomography the multiplicity + of each ion with respect to the cluster. That is how many times + should the position of the ion be accounted for because the ion + is e.g. a molecular ion with several elements or isotope of + requested type. + + + + + + + + Optional bitmask encoding if members of the set are assigned to as noise or not. + + + + + + + + Optional bitmask encoding if member of the set are a core point. + For details to which feature/cluster an ion/point is a core point + consider numerical_label. + + + + + + + + In addition to the detailed storage which members was grouped to + which feature/group summary statistics are stored under this group. + + + + + Total number of members in the set which are categorized as noise. + + + + + + Total number of members in the set which are categorized as a core point. + + + + + + Total number of clusters (excluding noise and unassigned). + + + + + Array of numerical identifier of each feature (cluster). + + + + + + + + Array of number of members for each feature. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_distancer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_distancer.nxdl.xml new file mode 100644 index 0000000000..5edb36e604 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_distancer.nxdl.xml @@ -0,0 +1,388 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + The total number of triangles in the set. + + + + + Results of a paraprobe-distancer tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + The tool can be used to compute the analytical distance of each ion + to a set of triangles. + + + + A bitmask which identifies which of the ions in the dataset were + analyzed. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of the triangles in the set + were considered. Usually these are all but sometimes users may + wish to filter certain portions of the triangles out. + If window_triangles is not provided it means that + all triangles were taken. + + + + Number of triangles covered by the mask. + The mask value for most may be 0. + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + The closest analytical distance of the ions to their respectively + closest triangle from the triangle set. + + + + + + + + A bitmask which identifies which of the distance values + can be assumed to have a consistent sign because the closest + triangle had a consistent outer unit normal defined. + For points whose bit is set 0 the distance is correct but the + sign is not reliable. + + + + Number of triangles covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. + + + + + + + + + The identifier of the triangle that is closest for each ion. + + + + + + + + A support field to visualize each ion and with this the distance + informations using XDMF and e.g. Paraview. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_intersector.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_intersector.nxdl.xml new file mode 100644 index 0000000000..efa4b5baeb --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_intersector.nxdl.xml @@ -0,0 +1,395 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of links pointing from current to next. + + + + + The total number of links pointing from next to current. + + + + + The total number of members in the current_set. + + + + + The total number of members in the next_set. + + + + + The total number of cluster found for coprecipitation analysis. + + + + + The number of rows in the table/matrix for coprecipitation stats. + + + + + Results of a paraprobe-intersector tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + The results of an overlap/intersection analysis. + + + + A matrix of feature_identifier which specifies which named features + from the current set have directed link(s) pointing to which named + feature(s) from the next set. + + + + + + + + + For each link/pair in current_to_next a characterization + whether the link is due to a volumetric overlap (0x00 == 0), + proximity (0x01 == 1), or something else unknown (0xFF == 255). + + + + + + + + A matrix of feature_identifier which specifies which named feature(s) + from the next set have directed link(s) pointing to which named + feature(s) from the current set. Only if the mapping whereby the + links is symmetric next_to_current maps the links in current_to_next + in the opposite direction. + + + + + + + + + For each link/pair in next_to_current a characterization + whether the link is due to a volumetric overlap (0x00 == 0), + proximity (0x01 == 1), or something else unknown (0xFF == 255). + + + + + + + + For each pair of links in current_to_next the volume of the + intersection, i.e. how much volume do the two features share. + If features do not intersect the volume is zero. + + + + + + + + During coprecipitation analysis the current and next set are analyzed + for links in a special way. Three set comparisons are made. Members + of the set in each comparison are analyzed for overlap and proximity: + + The first comparison is the current_set against the current_set. + The second comparison is the next_set against the next_set. + The third comparison is the current_set against the next_set. + + Once the (forward) links for these comparisons are ready the + pair relations are analyzed with respect to which feature identifier + cluster in identifier space. Thereby a logical connection (link) is + established between the features in the current_set and next_set. + Recall that these two set typically represent different features + within an observed system for otherwise the same parameterization. + Examples include two sets of e.g. precipitates with differing + chemical composition that were characterized in the same material + volume representing a snapshot of an e.g. microstructure at the same + point in time. Researchers may have performed two analyses, one to + characterize precipitates A and another one to characterize percipitates + B. Coprecipitation analysis now logically connects these independent + characterization results to establish spatial correlations of e.g. + precipitates spatial arrangement. + + + + Matrix of feature_identifier and cluster_identifier pairs which + encodes the cluster to which each feature_identifier was assigned. + Here for features of the current_set. + + + + + + + + + Matrix of feature_identifier and cluster_identifier pairs which + encodes the cluster to which each feature_identifier was assigned. + Here for features of the next_set. + + + + + + + + + The identifier (names) of the cluster. + + + + + + + + Pivot table as a matrix. The first column encodes how many + members from the current_set are in each cluster, one row per cluster. + The second column encodes how many members from the next_set are + in each cluster, in the same row per cluster respectively. + The last column encodes the total number of members in the cluster. + + + + + + + + + Pivot table as a matrix. The first column encodes the different + types of clusters based on their number of members in the sub-graph. + The second column encodes how many clusters with as many members + exist. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_nanochem.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_nanochem.nxdl.xml new file mode 100644 index 0000000000..684d18cd0a --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_nanochem.nxdl.xml @@ -0,0 +1,1973 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + The total number of atoms in the atomic_decomposition match filter. + + + + + The total number of isotopes in the isotopic_decomposition match filter. + + + + + The dimensionality of the delocalization grid. + + + + + The cardinality/total number of cells/grid points in the delocalization grid. + + + + + + The total number of XDMF values to represent all faces of triangles via XDMF. + + + + + The total number of entries in a feature dictionary. + + + + + The total number of member distinguished when reporting composition. + + + + + Results of a paraprobe-nanochem tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must no longer compute analyses. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases, it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + If nothing else is specified we assume that there + has to be at least one set of NXtransformations named + paraprobe defined, which specifies the coordinate system. + In which all positions are defined. + + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + A bitmask which identifies which of the ions in the dataset were + analyzed during this process. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used, padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe-toolbox executable. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth (padding). + + + + + + + + + + + The weighting model specifies how mark data are mapped to a weight + per point/ion. For atom probe microscopy (APM) mark data are e.g. + which iontype an ion has. As an example, different models are used + which account differently for the multiplicity of a point/ion + during delocalization: + + * unity, all points/ions get the same weight 1. + * atomic_decomposition, points get as much weight as they + have atoms of a type in atomic_decomposition_rule, + * isotope_decomposition, points get as much weight as they have + isotopes of a type in isotopic_decomposition_rule. + + + + + + + + + + + A list of elements (via proton number) to consider for the + atomic_decomposition weighting model. + Elements must exist in the periodic table of elements and be + specified by their number of protons. + Values in match are isotope hash values using the following + hashing rule $H = Z + 256*N$ with $Z$ the number of protons + and $N$ the number of neutrons of the isotope. + In the case of elements this hashing rule has the advantage + that for elements the proton number is their hash value because + N is zero. + + + + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + + + + + + + + + Array of values to filter according to method. For example, + if the filter specifies [1, 5, 6] and method is whitelist, + only entries with values matching 1, 5 or 6 will be processed. + All other entries will be filtered out/not considered. + + + + + + + + + A list of isotopes (via proton and neutron number) to consider + for the isotopic_decomposition weighting model. + Isotopes must exist in the nuclid table. + Values in match are isotope hash values using the following + hashing rule $H = Z + 256*N$ with $Z$ the number of protons + and $N$ the number of neutrons of the isotope. + + + + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + + + + + + + + + Array of values to filter according to method. For example, + if the filter specifies [1, 5, 6] and method is whitelist, + only entries with values matching 1, 5 or 6 will be processed. + All other entries will be filtered out/not considered. + + + + + + + + + How results of the kernel-density estimation were computed + into quantities. By default the tool computes the total number + (intensity) of ions or elements. Alternatively the tool can compute + the total intensity, the composition, or the concentration of the + ions/elements specified by the white list of elements in each voxel. + + + + + + + + + + + Weighting factor, in atom probe, often termed multiplicity. + The weighting factor is the multiplier with which the integrated + intensity contribution from the point/ion gets multiplied. + The delocalization computes the integrated intensity for each + grid cell. Effectively, this is an explicitly evaluated kernel + method where each specific position of an ion is replaced by a + smoothing kernel. For atom probe weights are positive and integer + specifically the multiplicity of the ion, in accordance with the + respective rulesets as defined by weighting_model. + + + + + + + + The discretized domain/grid on which the delocalization is applied. + + + + + + + + + + + The total number of cells/voxels of the grid. + + + + + + + + + + The symmetry of the lattice defining the shape of the unit cell. + + + + + + + + The unit cell dimensions according to the coordinate system + defined under coordinate_system. + + + + + + + + Number of unit cells along each of the d unit vectors. + The total number of cells, or grid points has to be the cardinality. + If the grid has an irregular number of grid positions in each direction, + as it could be for instance the case of a grid where all grid points + outside some masking primitive are removed, this extent field should + not be used. Instead use the coordinate field. + + + + + + + + + Reference to or definition of a coordinate system with + which the positions and directions are interpretable. + If the coordinate system is not specified the paraprobe + coordinate system is used. + + + + + + Integer which specifies the first index to be used for + distinguishing identifiers for cells. Identifiers are defined + either implicitly or explicitly. For implicit indexing the + identifiers are defined on the interval + [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + A tight axis-aligned bounding box about the grid. + + + + For atom probe should be set to true. + + + + + Integer which specifies the first index to be used for distinguishing + hexahedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + + Integer which specifies the first index to be used for distinguishing + identifiers for vertices. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + Integer which specifies the first index to be used for distinguishing + identifiers for faces. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + Positions of the vertices. + + Users are encouraged to reduce the vertices to unique set of positions + and vertices as this supports a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. + Naively here means that one for example stores each vertex of a triangle + mesh even though many vertices are shared between triangles and thus + the positions of these vertices do not have to be duplicated. + + + + + + + + + Array of identifiers from vertices which describe each face. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + + + + + + + + + Six equally formatted sextets chained together. For each + sextett the first entry is an XDMF primitive topology + key (here 5 for polygon), the second entry the XDMF primitive + count value (here 4 because each face is a quad). + The remaining four values are the vertex indices. + + + + + + + + How many distinct boundaries are distinguished? + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + + + + + + Name of the boundaries. E.g. left, right, front, back, bottom, top, + The field must have as many entries as there are number_of_boundaries. + + + + + + + + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + + + + + + + + + + The result of the delocalization based on which subsequent + iso-surfaces will be computed. In commercial software so far + there is not a possibility to export such grid. + + + + + + + + + + + + + + + + + + Cell center of mass positions along x. + + + + + + + + + Cell center of mass positions along y. + + + + + + + + Cell center of mass positions along z. + + + + + + + + Intensity of the field at given point + + + + + + + + Center of mass positions of each voxel for + rendering the scalar field via XDMF in e.g. + Paraview. + + + + + + + + + XDMF topology for rendering in combination with + xdmf_xyz the scalar field via XDFM in e.g. Paraview. + + + + + + + + + The three-dimensional gradient nabla operator applied to + scalar_field_magnitude. + + + + + + + + + + + + + + + + + + + + Cell center of mass positions along x. + + + + + + + + + Cell center of mass positions along y. + + + + + + + + Cell center of mass positions along z. + + + + + + + + The gradient vector. + + + + + + + + + Center of mass positions of each voxel for + rendering the scalar field via XDMF in e.g. + Paraview. + + + + + + + + + XDMF topology for rendering in combination with + xdmf_xyz the scalar field via XDFM in e.g. Paraview. + + + + + + + + + Halfwidth of the kernel about the central voxel. + The shape of the kernel is that of a cuboid + of extent 2*kernel_extent[i] + 1 in each dimension i. + + + + + + + + + + Sigma of the kernel in each dimension in the paraprobe + coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. + + + + + + + + Expectation value of the kernel in each dimension in the paraprobe + coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. + + + + + + + + + + An iso-surface is the boundary between two regions across which + the magnitude of a scalar field falls below/exceeds a threshold + magnitude phi. + For applications in atom probe microscopy the location and shape + of such a boundary (set) is typically approximated by + discretization. + This yields a complex of not necessarily connected geometric + primitives. Paraprobe-nanochem approximates this complex with + a soup of triangles. + + + + + The threshold or iso-contour value. + + + + + Details about the specific marching cubes algorithm + which was taken to compute the iso-surface. + The grid is the delocalization grid. + + + + Reference to the specific implementation of marching cubes used. + The value placed here should be a DOI. If there are no specific + DOI or details write not_further_specified, or give at least a + free-text description. The program and version used is the + specific paraprobe-nanochem. + + + + + + The resulting triangle soup computed via marching cubes. + + + + + + Integer which specifies the first index to be used for + distinguishing triangles. Identifiers are defined either + implicitly or explicitly. For implicit indexing the + identifiers are defined on the interval + [identifier_offset, identifier_offset+c-1]. + + + + + + Number of vertices. + + + + + Number of faces. + + + + + Integer which specifies the first index to be used for distinguishing + identifiers for vertices. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + + + + + Integer which specifies the first index to be used for distinguishing + identifiers for faces. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + + + + + Positions of the vertices. + + Users are encouraged to reduce the vertices to unique set of positions + and vertices as this supports a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. + Naively here means that one for example stores each vertex of a triangle + mesh even though many vertices are shared between triangles and thus + the positions of these vertices do not have to be duplicated. + + + + + + + + + Array of identifiers from vertices which describe each face. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + + + + + + + + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tri * (1+1+3). + + + + + + + + + Direction of each normal. + + + + + + + + + Qualifier how which specifically oriented normal to its + primitive each normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + + + + Direction of each normal. + + + + + + + + + Qualifier how which specifically oriented normal to its + primitive each normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + Triangle normals are oriented in the direction of the + gradient vector of the local delocalized scalar field. + :math:`\sum_{x, y, z} {\nabla{c}_i}^2`. + + + + + + + + + Triangle normals are oriented in the direction of the + gradient vector of the local delocalized scalar field. + The projection variable here describes the cosine of the + angle between the gradient direction and the normal + direction vector. + This is a descriptor of how parallel the projection is + that is especially useful to document those triangles + for whose projection is almost perpendicular. + + + + + + + + + + + + + + Array of edge length values. For each triangle the edge length + is reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + + + + + + + + + Array of interior angle values. For each triangle the angle + is reported for the angle opposite to the edges which are + traversed according to the sequence in which vertices + are indexed in triangles. + + + + + + + + + The center of mass of each triangle. + + + + + + + + + + Iso-surfaces of arbitrary scalar three-dimensional fields + can show a complicated topology. Paraprobe-nanochem can run + a DBScan-like clustering algorithm which performs a + connectivity analysis on the triangle soup. This yields a + set of connected features with their surfaces discretized + by triangles. Currently, the tool distinguishes at most + three types of features: + + 1. So-called objects, i.e. necessarily watertight features + represented polyhedra. + 2. So-called proxies, i.e. features that were replaced by a + proxy mesh and made watertight. + 3. Remaining triangle surface meshes of arbitrary shape and + cardinality. + + These features can be interpreted as microstructural features. + Some of them may be precipitates, some of them may be poles, + some of them may be segments of dislocation lines or other + crystal defects which are decorated (or not) with solutes. + + + + + The identifier which the triangle_soup connectivity analysis + returned, which constitutes the first step of the + volumetric_feature identification process. + + + + + + + + The array of keywords of feature_type dictionary. + + + + + + + + The array of values for each keyword of the + feature_type dictionary. + + + + + + + + The array of controlled keywords, need to be from + feature_type_dict_keyword, which specify which type + each feature triangle cluster belongs to. + Keep in mind that not each feature is an object or proxy. + + + + + + + + The explicit identifier of features. + + + + + + + + + Details for features which are (closed) objects. + Identifier have to exist in feature_identifier. + + + + + + + + + + + + + + + An oriented bounding box (OBB) to each object. + + + + Edge length of the oriented bounding box from largest + to smallest value. + + + + + + + + + + Oriented bounding box aspect ratio. YX versus ZY. + + + + + + + + + Position of the geometric center, which often is but + not necessarily has to be the center_of_mass of the + hexahedrally-shaped sample/sample part. + + + + + + + + + + A simple approach to describe the entire set of hexahedra + when the main intention is to store the shape of the + hexahedra for visualization. + + + + + + + + + + + + + + + + + + + + + + + + Details for all those objects close to edge, i.e. those which + have at least one ion which lays closer to a modelled edge + of the dataset than threshold. + + + + + + + + + + + + + + + Total (count) relevant for normalization. + + + + + + + + + + + + Count or weight which, when divided by total, + yields the composition of this element, isotope, + molecule or ion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + + + + + + + + + + + Details for all those objects far from edge, i.e. those + whose ions lay all at least threshold distant from a + modelled edge of the dataset. + + + + + + + + + + + + + + + Total (count) relevant for normalization. + + + + + + + + + + + + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + + + + + + + + + + + + + Details for features which are so-called proxies, i.e. objects + which have been reconstructed and combinatorially closed with + processing their partial triangulated_surface_mesh + (hole filling, refinement). + Identifier have to exist in feature_identifier. + + + + + + + + + + + + + + + + Details for those proxies close to edge, i.e. those which + have at least one ion which lays closer to a modelled edge + of the dataset than threshold. + Identifier have to exist in feature_identifier. + + + + + + + + + + + + + + + + Total (count) relevant for normalization. + + + + + + + + + + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + + + + + + + + + + + Details for those proxies far from edge, i.e. those whose + ions lay all at least threshold distant from a + modelled edge of the dataset. + + + + + + + + + + + + + + + Total (count) relevant for normalization. + + + + + + + + + + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + + + + + + + + + + + + + + + + + + The multiplicity whereby the ion position is accounted for + irrespective whether the ion is considered as a decorator + of the interface or not. + As an example, with atom probe it is typically not possible + to resolve the positions of the atoms which arrive at the detector + as molecular ions. Therefore, an exemplar molecular ion of two carbon + atoms can be considered to have a multiplicity of two to account that + this molecular ion contributes two carbon atoms at the reconstructed + location considering that the spatial resolution of atom probe + experiments is limited. + + + + + + + + The multiplicity whereby the ion position is accounted for when + the ion is considered one which is a decorator of the interface. + + + + + + + + The equation of the plane that is fitted initially. + + + + The four parameter :math:`ax + by + cz + d = 0` which define the plane. + + + + + + + + + The triangle surface mesh representing the interface model. + Exported at some iteration before the next DCOM step. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Direction of each normal + + + + + + + + + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + + + + + Direction of each normal + + + + + + + + + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + + + + + + + Array of edge length values. For each triangle the edge length is + reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + + + + + + + + + Array of interior angle values. For each triangle the angle is + reported for the angle opposite to the edges which are traversed + according to the sequence in which vertices are indexed in triangles. + + + + + + + + + + The triangle surface mesh representing the interface model. + Exported at some iteration after the next DCOM step. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Direction of each normal + + + + + + + + + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + + + + + Direction of each normal + + + + + + + + + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + + + + + + + + + + + + + + Array of edge length values. For each triangle the edge length is + reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + + + + + + + + + Array of interior angle values. For each triangle the angle is + reported for the angle opposite to the edges which are traversed + according to the sequence in which vertices are indexed in triangles. + + + + + + + + + + + + The ROIs are defined as cylinders for the computations. + To visualize these though we discretize them into regular n-gons. + Using for instance a 360-gon, i.e. a regular n-gon with 360 + edges resolves the lateral surface of each cylinder very finely + so that they are rendered smoothly in visualization software. + + + + + + Position of the geometric center, which often is but not + necessarily has to be the center_of_mass of the polyhedra. + + + + + + + + + Integer which specifies the first index to be used for distinguishing + ROI cylinder. Identifiers are defined explicitly. + + + + + + + + + + + + + + + The number of atoms in each ROI. + + + + + + + + The number of ions in each ROI. + + + + + + + + The orientation of the ROI defined via a vector which points along + the cylinder axis and whose length is the height of the cylinder. + + + + + + + + + + In the direction of the ROI. + + + + + Hashvalue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_ranger.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_ranger.nxdl.xml new file mode 100644 index 0000000000..9840e724c3 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_ranger.nxdl.xml @@ -0,0 +1,425 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. + + + + + Results of a paraprobe-ranger tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + Paraprobe-ranger loads the iontypes and evaluates for each + ion on which iontype it matches. If it matches on none, the + ion is considered of the default unknown type with a 0 as its + respective value in the iontypes array. + + + + + The length of the isotope_vector used to describe molecular ions. + + + + + + + + + + + The iontype ID for each ion that was best matching, stored in the + order of the evaporation sequence ID. The here computed iontypes + do not take into account the charge state of the ion which is + equivalent to interpreting a RNG and RRNG range files for each + ion in such a way that only the elements of which a (molecular) ion + is build are considered. By contrast, charged_iontypes takes + into account also the charge state. + + + + + + + + A bitmask which identifies exactly all those ions ranged irrespective + the type they ended up with. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + + Paraprobe-ranger performs a combinatorial search over + all possible or a reduced set of nuclids to identify + into which ions these can be composed. + + + + The main result is the list of molecular ions, here formatted + according to the definitions of a set of isotope_vectors + as detailed in :ref:`NXion`. + + + + + + + + + The mass-to-charge-state ratio of each molecular ion + without considering relativistic or quantum effects. + + + + + + + + The mass of each molecular ion without + considering relativistic or quantum effects. + + + + + + + + + The charge_state of each molecular ion. + + + + + + + + The product of the natural abundance of the isotopes building + each molecular ion. Further details are available in + :ref:`NXapm_paraprobe_config_ranger`. + + + + + + + + The product of the natural abundance of the isotopes building + each molecular ion. Further details are available in + :ref:`NXapm_paraprobe_config_ranger`. + + + + + + + + The number of disjoint nuclids for each molecular ion. + + + + + + + + The number of nuclids for each molecular ion. + + + + + + + + + Paraprobe-ranger loads iontypes and evaluates for each ion on which + iontype it matches. If it matches on none, the ion is considered of + the default unknown type with a 0 as its respective value in the + iontypes array. In contrast to use_existent_ranging this process + does neither needs measured ion position nor mass-to-charge-state + ratio values. + + + + + The length of the isotope_vector used to describe molecular ions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_selector.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_selector.nxdl.xml new file mode 100644 index 0000000000..791323a938 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_selector.nxdl.xml @@ -0,0 +1,274 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + Results of a paraprobe-selector tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + A bitmask which identifies which of the ions in the dataset + were selected to become included in the region-of-interest (ROI). + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_spatstat.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_spatstat.nxdl.xml new file mode 100644 index 0000000000..674afbe853 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_spatstat.nxdl.xml @@ -0,0 +1,364 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + Results of a paraprobe-spatstat tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + A bitmask which identifies which of the ions in the dataset were + analyzed. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + The iontype ID for each ion that was assigned to each ion during + the randomization of the ionlabels. Iontype labels are just permuted + but the total number of values for each iontype stay the same. + + The order matches the iontypes array from a given ranging results + as is specified in the configuration settings inside the specific + config_filename that was used for this spatstat analysis. + + + + + + + + K-nearest neighbor statistics. + + + + Right boundary of the binning. + + + + + + + + + + + + + Cumulated + + + + + + + + Cumulated and normalized by total counts + + + + + + + + + Radial distribution statistics. + + + + Right boundary of the binning. + + + + + + + + + + + + + Cumulated + + + + + + + + Cumulated and normalized by total counts + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_surfacer.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_surfacer.nxdl.xml new file mode 100644 index 0000000000..0e24bccc8b --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_surfacer.nxdl.xml @@ -0,0 +1,503 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + The number of vertices of the alpha complex. + + + + + The number of faces of the alpha complex. + + + + + The total number of XDMF values to represent all faces of triangles via XDMF. + + + + + The total number of XDMF values to represent all faces of tetrahedra via XDMF. + + + + + Results of a paraprobe-surfacer tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + A bitmask which identifies which of the ions in the dataset were + analyzed. Computations of alpha complexes may have filtered this + ion set further but this process is deterministic. + + + + Number of ions covered by the mask. The mask may be 0 for most. + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + Paraprobe-surfacer can be used to load a ROI that is the entire or a + sub-set of the ion point cloud. In the point_cloud_wrapping process + the tool computes a triangulated surface mesh which encloses the + ROI/point cloud. This mesh can be seen as a model for the edge of + the dataset. + Different algorithms can be used with paraprobe-surfacer to create + this mesh such as convex hulls, alpha-shapes as their generalization, + or alpha wrappings. + Ideally, the resulting mesh should be a watertight polyhedron. + This polyhedron is not necessarily convex. For some algorithms there + is no guarantee that the resulting mesh yields a watertight mesh. + + + + + + A bitmask which identifies exactly all those ions whose positions + were considered when defining the filtered point set from which + the alpha complex was then in fact computed. This window + can be different to the entire window as irrelevant ions might + have been filtered out to reduce the computational costs of the + alpha complex analysis. + + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The set of triangles in the coordinate system paraprobe + which discretizes the exterior surface of the alpha complex. + + + + Integer which specifies the first index to be used for distinguishing + triangles. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + + + + + + + Number of vertices. + + + + + Number of faces. + + + + + + + + + + + + + + + + + + + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tri * (1+1+3). + + + + + + + + + Do the triangles define a triangulated surface mesh which + is watertight? + + + + + The volume which the triangulated surface mesh encloses + provided that the mesh is watertight. + + + + + + The set of tetrahedra which represent the interior volume of the + complex if that is a closed 2-manifold. + + + + Integer which specifies the first index to be used for distin- + guishing tetrahedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined + on the interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + The accumulated volume of all interior tetrahedra. + + + + + + Number of vertices. + + + + + Number of faces. + + + + + + + + + + + + + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tet * (1+1+4). + + + + + + + + + + + + In the future we may want to wrap other primitives + like triangles or polylines. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_tessellator.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_tessellator.nxdl.xml new file mode 100644 index 0000000000..dc2bf91198 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_tessellator.nxdl.xml @@ -0,0 +1,677 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + The total number of facets/polygons defining the tessellation. + + + + + Results of a paraprobe-tessellator tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + The tool can be used to compute a Voronoi tessellation the entire + or a sub-set of the reconstruction. The point cloud in the ROI is + wrapped into a tight axis-aligned bounding box. The tool detects if + Voronoi cells make contact with the walls of this bounding box. + The tessellation is computed without periodic boundary conditions. + + + + A bitmask which identifies which of the ions in the dataset were + analyzed. + + + + Number of ions covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by the global axis-aligned bounding box, i.e. boundaries + of the threads are ignored. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the negative x axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The right wall has the positive x axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The front wall has the negative y axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The rear wall has the positive y axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the negative z axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the positive z axis of the paraprobe coordinate + system as the outer unit normal. + + + + Number of points covered by the mask. + The mask value for most may be 0. + + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + + + + + + + + + + + + + + + + Interior volume + + + + + + + + By which MPI process was the Voronoi cell computed. + + + + + + + + By which OpenMP thread was the Voronoi cell computed. + + + + + + + + The number of faces for each polyhedron. Faces of adjoining polyhedra + are counted for each polyhedron. This field can be used to interpret + the array/field with the individual area values for each face. + + + + + + + + + Integer which specifies the first index to be used for distinguishing + polyhedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + + + + Integer used to distinguish polyhedra for explicit indexing. + + + + + + + + A simple approach to describe the entire set of polyhedra when + the main intention is to store the shape of the polyhedra for + visualization. + + + + + Number of vertices. + + + + + Number of faces. + + + + + + + + + + + + + A sequence of always first an XDMF topology type key, followed + by the XDMF number of vertices of the polygon, followed by + the vertex identifier which define the facet polygon. First + we store the polygon of the first facet of the first cell, then + the second facet of the first cell, until the last facet of the + first cell, followed by the first facet of the second cell, + and so on and so forth. + + + + + + + + A sequence of cell identifier so that each facet is associated + with its cell because of which it is then possible to segment + out cells three-dimensionally based on cell i.e. evaporation_id. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXapm_paraprobe_results_transcoder.nxdl.xml b/contributed_definitions/NXapm_paraprobe_results_transcoder.nxdl.xml new file mode 100644 index 0000000000..cdab497064 --- /dev/null +++ b/contributed_definitions/NXapm_paraprobe_results_transcoder.nxdl.xml @@ -0,0 +1,568 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The total number of ions in the reconstruction. + + + + + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. + + + + + Number of mass-to-charge-state-ratio intervals mapped on this ion type. + + + + + Total number of integers in the supplementary XDMF topology array. + + + + + Number of ions probed in the combinatorial analysis of the charge states + + + + + Results of a paraprobe-transcoder tool run. + + + + + + Version specifier of this application definition. + + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + + + + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + + + + + The absolute path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + If used, contact information and eventually details + of at least the person who performed this analysis. + + + + + + + + + + + + + + + Details about the coordinate system conventions used. + + + + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + + + + + + + An array of triplets of integers which can serve as a supplementary + array for Paraview to display the reconstruction. The XDMF datatype + is here 1, the number of primitives 1 per triplet, the last integer + in each triplet is the identifier of each point starting from zero. + + + + + + + + + + On a mid term perspective we would like to evolve the paraprobe-toolbox + to an implementation stage where it works exclusively with completely + provenance-tracked formats for both the configuration of the workflow step + and/or analysis with each tool and also for the output of these analyses + in the form of so-called tool-specific results files. + Currently the Hierarchical Data Format 5 (HDF5) is used to store such data. + + Different file formats can be used to inject reconstructed datasets and + ranging definitions into the toolbox. Traditionally, these are the POS, + ePOS, and APT files with the tomographic reconstruction and other metadata + and RNG and RRNG file formats for the ranging definitions how mass-to-charge + state-ratio values map on (molecular) ion types. Such input should be + injected via specific NeXus/HDF5 files which are documented + in compliance with the NXapm application definition. + + So far the paraprobe-toolbox was used as a standalone tool. Therefore, it + was not relevant during the development to focus on interoperability. + Essentially paraprobe-transcoder was used as a parser to transcode data + in the above-mentioned file formats into a paraprobe-specific + representation. This transcoding should become deprecated. + Here we describe steps we have taken into this direction. + + With the work in the FAIRmat project and the desire to make the paraprobe- + toolbox also accessible as a cloud-computing capable service in the Nomad + Remote Tools Hub (NORTH) the topic of interoperability became more important + and eventually the NXapm application definition was proposed. + NORTH is a GUI and related service in a NOMAD OASIS instance which allows + to spawn preconfigured docker containers via JupyterHub. + Currently, NORTH includes the so-called apm container. A container with + tools specific for analyzing data from atom probe microscopy as well as + processing of point cloud and mesh data. + + The NXapm application definition and related implementation work within + NOMAD OASIS enabled users to parse content of POS, ePOS, APT, RNG, and + RRNG files, surplus key metadata from vendor-agnostic electronic lab notebook + solutions directly into NOMAD OASIS via the uploads section. + The process is automated and yields an NXapm-compliant NeXus/HDF5 file + inside the uploads section in return. + + With these improvements made there is no longer a need for - at least the + users of a NOMAD OASIS and NORTH instance to use the deprecated + PARAPROBE.Transcoder.Results.*.h5 files. Ideally, paraprobe should + automatically detect that the input can now be an NXapm-compliant NeXus/HDF5 + file and in response work with this file directly. + To remain compliant with users however who do not have or do not wish + to use a NOMAD OASIS or NXapm or NeXus at all right now, the solution is + as follows: + + Calling the configuration stage of paraprobe-transcoder is always mandatory. + It is always the first step of working with the toolbox. In this process + the user defines the input files. These can either be nxs i.e. the NXapm/NeXus/ + HDF5 file from e.g. the upload section, or such a file that was obtained from + a colleague with a NOMAD OASIS instance. + In all other cases, users can pass the reconstruction and ranging definitions + using the traditional POS, ePOS, or APT and RNG or RRNG file formats respectively. + + Based on which input the user delivers, the parmsetup-transcoder tool then + creates a configuration file PARAPROBE.Transcoder.Config.SimID.*.nxs and + informs the user whether the input was NeXus (and thus if all relevant + input is already available) or whether the paraprobe-transcoder tool needs + to be executed to convert the content of the vendor files first into a + format which paraprobe can provenance track and understand. + In the latter case, the PARAPROBE.Transcoder.Config.SimID.*.nxs file is + used to communicate to all subsequently used tools from which files + the tools can expect to find the reconstruction and ranging definitions. + + All subsequent analysis steps start also with a tool-specific configuration. + This configuration step reads in (among others) the + PARAPROBE.Transcoder.Config.SimID.*.nxs file from which the configuration + tool identifies automatically whether to read the reconstruction and ranging data + from PARAPROBE.Transcoder.Results.SimID.*.h5 or directly the NXapm-compliant + NeXus/HDF5 file that was created upon preparing the upload or the file shared + from a colleague. This design removes the need for unnecessary copies of the data. + Currently still though users should execute the transcoder step as it will + generate a supplementary XDMF topology field with which the data in either + the NeXus/HDF5 or the transcoded vendor files can be displayed using e.g. + Paraview. For this purpose XDMF is used. + + Of course ideally the APT community would at some point converge to use + a common data exchange file format. To this end, AMETEK/Cameca's APT file format + could be a good starting point but so far it is lacking a consistent way of + how to store generalized ranging definitions and post-processing results. + POS, ePOS, Rouen's ATO, as well as other so far used representations of data + like CSV or text files have, to the best of our current knowledge, no + concept of how to marry reconstruction and (optional) ranging data into + one self-descriptive format. + + This summarizes the rationale behind the current choices of the I/O for + paraprobe. Furthermore, this summarizes also why the fundamental design + of splitting an analysis always into steps of configuration (with parmsetup), + task execution (with the respective C/C++ or Python tool of the toolbox), + and post-processing (e.g. with autoreporter) is useful because it offers + a clear description of provenance tracking. This is a necessary step to make + atom probe microscopy data at all better aligned with the aims of the + FAIR principles. + + The internal organization of the data entries in the atom_probe group + in this application definition for paraprobe-transcoder results files + mirror the definitions of the NXapm for consistency reasons. + + + + + + Mass-to-charge-state ratio values. + + + + + + + + + + + + Three-dimensional reconstructed positions of the ions. + Interleaved array of x, y, z positions in the specimen space. + + + + + + + + + + + Details about how peaks, with taking into account + error models, were interpreted as ion types or not. + + + + + + + + + Details and results of the combinatorial analyses of this + range definition to identify the charge_state for an ion. + + + + Currently charge_state not charge! + + + + + + + + Specific isotopes building each candidate matching the range. + + + + + + + + + Accumulated mass of the isotopes in each candidate. + Not corrected for quantum effects. + + + + + + + + + Product of natural abundance of the isotopes per candidate. + + + + + + + + Filter criterion on the product of the natural abundances + computed from each isotope building the (molecular) ion. + Such a filter can be used to reduce the number of possible + molecular ions considered when trying to find a unique solution + to the question which charge_state does a molecular ion + within a given range and given combination of elements have. + + + + + Filter criterion on the minimum half life which all isotopes + building the (molecular) ion need to have to consider the + candidate. + Such a filter can be used to reduce the number of possible + molecular ions considered when trying to find a unique solution + to the question which charge_state does a molecular ion + within a given range and given combination of elements have. + + + + + + If the value is zero/false it means that non-unique solutions + are accepted. These are solutions where multiple candidates + differ in their isotopes but have the same charge. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXbeam_path.nxdl.xml b/contributed_definitions/NXbeam_path.nxdl.xml new file mode 100644 index 0000000000..9dc4546fa7 --- /dev/null +++ b/contributed_definitions/NXbeam_path.nxdl.xml @@ -0,0 +1,452 @@ + + + + + + + + A beam path consisting of one or more optical elements. + + NXbeam_path is used in NXopt to describe the beam path, i.e. the arrangement + of optical elements between the excitation source and the sample, or between + the sample and the detector unit. + + To describe the order of the elements, use 'order(NXtransformations)', where + each element's position points to the preceding element via '@depends_on'. + Special case beam splitter: A beam splitter is a device which separates the + beam into two or more beams. If such a device is part of the beam path use + two or more NXbeam_paths to describe the beam paths after the beam splitter. + In this case, in the dependency chain of the new beam paths, the first + elements each point to the beam splitter, as this is the previous element. + + Describe the relevant optical elements in the beam path by using the + appropriate base classes. You may use as many elements as needed, also + several elements of the same type as long as each element has its own name. + + + + Entry point of the dependency chain defined by the NXtransformations + field, i.e. a link to the last element in the beam path. + Example: /entry/instrument/beam_path/detector. + + + + + + Specify the order of the optical elements by defining a dependency chain. + For each element, a '@depends_on' attribute should be used to state the + position of the element in the beam path by pointing to the previous + element. For the very first element, use the string "." instead. + + + + For each element in the beam path, one such field must exist with a + '@depends_on' attribute defined to specify its position in the beam + path. Note that also 'NXopt/ENTRY/INSTRUMENT/sample_stage' and windows + ('NXopt/ENTRY/INSTRUMENT/sample_stage/entry_window' and + 'NXopt/ENTRY/INSTRUMENT/sample_stage/exit_window') may be added to the + dependency chain, i.e. may have an entry in this class even if they are + not described in the beam path. + ELEMENT is a place holder for the name of an optical beam path element. + Note that the name of this field must be exactly the same as the + element's field name. + + + + Add a link to the previous beam path element. + + + + + + + Excitation source. One or more may be needed (e.g. two for a pump-probe + setup with one pump and one probe beam). + Depending on the source type, different properties are relevant, which + are provided through the respective base class (e.g. use NXopt_source for + lamps or lasers, NXchem_source for chemical reaction etc.). + Some base classes are incomplete (NXchem_source, NXbio_source); the + expertise of the respective communities is needed. + + + + Use this field to point to the previous optical element. + + + + + Type of excitation source. + + + + + + + + + + + + + + + + + + + + + + + Lifespan of the excitation (typically provided in hours). + + + + + How many hours has the lamp been used? + + + + + Wavelengths or energy vector of the excitation source. This can be a + single value or a spectrum, depending on the type of experiment. + + + + Unit of wavelength or energy. + + + + + + + Two- or three-dimensional beam profile. + + + + + + + + + Power of one light pulse if the source is a pulsed source. + + + + + Is the excitation source continuous wave (CW)? + + + + + Power of CW beam. + + + + + FWHM bandwidth of the excitation source. + + + + + Coherence length. + + + + + Divergence of the excitation beam. + + + + + + Use this field to describe a simple pinhole (round geometry). Define its + dimension using 'diameter'. For more complex geometries, 'NXaperture' + should be used. + + + + + Use this field to describe a simple slit (rectangular geometry). Define + its dimensions using 'x_gap' and 'y_gap'. For more complex geometries, + 'NXaperture' should be used. + + + + + Use this field to describe an aperture. To specify a window, use the + field 'window_NUMBER(NXaperture)'. + + + + + A window, e.g. an entry or exit window of a cryostat. + + + + Use this field to point to the previous optical element. + + + + + The material of the window. + + + + + + + + + + + + + + + If you specified 'other' as material, decsribe here what it is. + + + + + Thickness of the window + + + + + Angle of the window normal (outer) vs. the substrate normal + (similar to the angle of incidence). + + + + + If reference data were measured add a link to the NeXus file where they + are described. + + + + + + + + A device that reduces the intensity of a beam by attenuation. + + + + The transmitted intensity divided by the incident intensity. + + + + + Attenuation of the attenuator in dB. + + + + Unit of the measured data is not covered by NXDL units state + here which unit was used. + + + + + + Input and output aperture of the attenuator. + + + + + Geometry (shape, size etc.) of the attenuator. + + + + + + A diffraction grating. Define relevant parameters in the corresponding + fields, e.g. order of diffration (diffraction_order) or angular + dispersion (angular_dispersion). + + + + Define the type of the grating. + + + + + Dispersion of the grating in nm/mm (or e.g. nm/mrad). + + + + + Number of grooves per mm. + + + + + Blaze wavelength of the grating. + + + + + Efficiency curve versus wavelength or energy. + + + + + + + + Spectral values, e.g. wavelength or energy. Vector of length + N_spectrum. + + + + Unit of wavelength array (e.g. nanometer or Angstrom) + + + + + + + A device blocking the beam in a temporal periodic pattern, e.g. a optical + chopper wheel. Specify the frequency range using 'min_frequency' and + 'max_frequency'. + + + + Minimum frequency in Hertz. + + + + + Maximum frequency in Hertz. + + + + + Frequency resolution in Hertz. + + + + + + A monochromator or spectrometer. + + + + Spectral values of the monochromator, e.g. wavelength or energy values + used for the measurement. + + + + Unit of wavelength array (e.g. nanometer or Angstrom) + + + + + + Diffraction grating. If two or more gratings were used, define the + angular dispersion and the wavelength range (min/max wavelength) for + each grating and make sure that the wavelength ranges do not overlap. + The dispersion should be defined for the entire wavelength range of the + experiment. + + + + Dispersion of the grating in nm/mm. + + + + + Minimum wavelength of the grating. + + + + + Maximum wavelength of the grating. + + + + + + Spectral resolution of the instrument. + + + + + Define the width of the monochromator slit in the subfield x_gap. + + + + Was the slit width fixed? + + + + + If slit width was not fixed, define the maximum slit width. + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXbeam_splitter.nxdl.xml b/contributed_definitions/NXbeam_splitter.nxdl.xml new file mode 100644 index 0000000000..bbb399929a --- /dev/null +++ b/contributed_definitions/NXbeam_splitter.nxdl.xml @@ -0,0 +1,363 @@ + + + + + + + + + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the beam splitter material and/or coating is defined. + + + + + Length of the spectrum vector (e.g. wavelength or energy) for which the + reflectance or transmission of the beam splitter is given. + + + + + Number of parameters needed do descripe the shape of the beam splitter. + + + + + Number of objects the beam splitter is made up of. + + + + + Number of outputs, i.e. number of paths the beam takes after being split by + the beam splitter. + + + + + A beam splitter, i.e. a device splitting the light into two or more beams. + + Information about types and properties of beam splitters is provided e.g. + [here](https://www.rp-photonics.com/beam_splitters.html). + + Use two or more NXbeam_paths to describe the beam paths after the beam + splitter. In the dependency chain of the new beam paths, the first elements + each point to this beam splitter, as this is the previous element. + + + + Specify the beam splitter type (e.g. dielectric mirror, pellicle, + dichroic mirror etc.). Shape (e.g. prism, plate, cube) and dimension + should be described in 'geometry'. Define if the beam splitter is + polarizing or not in the field 'polarizing(NX_BOOLEAN)'. + + + + + + + + + + + + + + + + + If you selected 'other' in 'type' use this field to specify which type of + beam splitter was used. + + + + + Is the beam splitter polarizing? + + + + + + Does the beam splitter have multiple outputs (diffractive optical + element), i.e. more than two outputs? + + + + + Describe the geometry (shape, dimension etc.) of the beam splitter. + Specify the dimensions in 'SHAPE/size'. A sketch of the device should be + provided in the 'sketch(NXdata)' field to clarify (i) the shape and + dimensions of the device, and (ii) the input and outputs (i.e. the + direction of the incoming and outcoming (split) beams). + + + + + Describe the shape (plate, cube, wedged, prism etc.). + + + + + + + + + + + + + If you chose 'other' in 'shape' describe what it is. + + + + + Sketch of the beam splitter showing its geometry. The paths of the + incoming and split beam should be illustrated and labelled (0 for the + incoming beam, and 1, 2,..., N_outputs for the outputs (i.e. the split + beam paths)). + + + + + Physical extent of the beam splitter device. The beam splitter might be + made up of one or more objects (NX_objects). The meaning and location + of the axes used will vary according to the value of the 'shape' + variable. 'N_shapepar' defines how many parameters: + + * For 'cube' the parameters are (width, length). + * For 'cylinder' the parameters are (diameter, length). + * For 'plate' the parameters are (width, height, length). + * For 'prism' the parameters are (width, height, length). + * For 'wedged' the parameters are (width, height, shortest length). + The wedge angle should be provided in 'SHAPE/wedge_angle'. + * For 'other' the parameters may be (A, B, C, ...) with the labels + defined in the sketch plotted in 'SHAPE/sketch'. + + + + + + + + + Wedge angle if 'shape' is 'wedged'. + + + + + + + Beam splitting ratio(s) for the various outputs (i.e. the + paths of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting with 1. + + + + + + + + Clear aperture of the device (e.g. 90% of diameter for a disc, or 90% of + length and height for square geometry). + + + + + + Substrate of the beam splitter. Describe the material of the substrate in + substrate/substrate_material and provide its index of refraction in + substrate/index_of_refraction_substrate, if known. + + + + Specify the material of the beam splitter. If the device has a coating + it should be described in coating/coating_material. Is the material + birefringent? + + + + + Thickness of the beam splitter substrate. Define the minimum and + maximum thickness (for a wedged geomtry). For a homogeneous thickness + (e.g. as in plate beam splitters) the minimum and maximum values are + equal. + + + + + + + + Complex index of refraction of the beam splitter substrate. Specify at + given spectral values (e.g. wavelength, energy, wavenumber etc.). + + + + + + + + + + Is the beam splitter coated? If yes, specify the type and material of the + coating and the spectral range for which it is designed. If known, you + may also provide its index of refraction. For a beam splitter cube + consisting of two prisms which are glued together, you may want to + specify the the glue and the coatings of each prism. + + + + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + + + + + Specify the coating material. + + + + + Thickness of the coating. + + + + + Wavelength range for which the coating is designed. Enter the minimum + and maximum values of the wavelength range. + + + + + + + + Complex index of refraction of the coating. Specify at given spectral + values (e.g. wavelength, energy, wavenumber etc.). + + + + + + + + + + Wavelength range for which the beam splitter is designed. Enter the + minimum and maximum values of the wavelength range. Alternatively, or + additionally, you may define the wavelength range for the coating in + coating/wavelength_range_coating. + + + + + + + + Optical loss of the beam splitter for the various outputs (i.e. the paths + of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting + with 1. + + + + + + + + Optimized angle of incidence for the desired splitting ratio. + + + + + + Angle of deflection corresponding to the optimized angle of incidence + defined in incident_angle. + + + + + Range of the angles of incidence (AOI) for which the beam splitter can be + operated. Specify the minimum and maximum angles of the range. + + + + + + + + + Reflectance of the beam splitter at given spectral values. + + + + + + + + Transmission at given spectral values for the various outputs (i.e. the + paths of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting + with 1. + + + + + + + diff --git a/contributed_definitions/NXbias_spectroscopy.nxdl.xml b/contributed_definitions/NXbias_spectroscopy.nxdl.xml new file mode 100644 index 0000000000..ad484c806f --- /dev/null +++ b/contributed_definitions/NXbias_spectroscopy.nxdl.xml @@ -0,0 +1,168 @@ + + + + + + Base classes definition for bias spectroscopy. + + Bias sweeps while measuring arbitrary channels with I(V) curves. + + + + Select the channels to record. + + + + + If chosen, the Bias voltage resets to its initial value (before the sweep initiation) at + the conclusion of the spectroscopy measurement. When this option is not selected, the Bias + voltage maintains the last value acquired during the sweep. This functionality proves + beneficial, especially when combining multiple sweep segments. As an illustration of an + automated measurement: turn off the z-Controller, commence spectroscopy sweep segments ( + forward sweep only, without resetting the bias), restore the bias to its initial value, + and then turn on the z-Controller. + + + + + Select whether to record the Z position during Z averaging time at the end of + the sweep (after Z control time) and store the average value in the header of + the file when saving. Using this option increases the sweep time by Z averaging + time. + + + + + Select whether to set the Lock-In to run during the measurement. When using this + feature, make sure the Lock-In is configured correctly and settling times are + set to twice the Lock-In period at least. This option is ignored when Lock-In is + already running. This option is disabled if the Sweep Mode is MLS and the flag + to configure the Lock-In per segment in the Multiline segment editor is set. + + + + + Time during which the spectroscopy data are acquired and averaged. + + + + + Number of sweeps to measure and average. + + + + + The first bias values of the sweep. + + + + + The last bias values of the sweep. + + + + + Define the sweep number of points, that is, the maximum spectrum resolution eq. + Bias window divide by Num Pixel. + + + + + Duration over which the Z position is recorded and averaged before and after the + sweep (the latter only if Record final Z position is selected in the Advanced + section). After the initial z averaging time, if Z-Controller to Hold is + selected in the Advanced section, the z-Controller is set to hold and the tip is + placed at the previously averaged z position (plus z offset). + + + + + Select a filter to smooth the displayed data. When saving, if any filter is selected, + filtered data are saved to file along with the unfiltered data. + + + + + Filter order of a dynamic filter or width (in number of points) for the Gaussian + filter. + + + + + Cutoff frequency for dynamic filters. + + + + + Offset added to the initial averaged position Zaver before starting to sweep. + This parameter is disabled when Z-Controller to Hold is deselected in the + Advanced section. The LED “Alt” next to the Z offset indicates if an alternate + Z-controller setpoint is enabled. + + + + + Time to wait after changing the bias to the next level and before + starting to acquire data. + + + + + No doc yet. + + + + + Time to wait after the sweep has finished and the bias is ramped to + the initial value. + + + + + Time during which the Z-Controller is enabled once a sweep has finished. + When averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled + for this duration between each sweep. After the last sweep, it will wait the + specified time before continuing a running scan. This ensures each sweep + reliably starts from the same position. This parameter is disabled when + Z-Controller to Hold is deselected in the Advanced section. + + + + + Maximum rate at which the bias changes (before, during and after sweeping). + (V/s) + + + + + Select whether to measure the backward (return) sweep or the forward only. + + + + + Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. + It is selected by default. When deselected, Z-offset and Z control time parameters + are disabled. + + + diff --git a/contributed_definitions/NXcalibration.nxdl.xml b/contributed_definitions/NXcalibration.nxdl.xml index 16e54bd054..d4d3ed8925 100644 --- a/contributed_definitions/NXcalibration.nxdl.xml +++ b/contributed_definitions/NXcalibration.nxdl.xml @@ -1,6 +1,27 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays @@ -10,11 +31,6 @@ Number of coefficients of the calibration function - - - Number of features used to fit the calibration function - - Number of points of the calibrated and uncalibrated axes @@ -24,6 +40,35 @@ Subclass of NXprocess to describe post-processing calibrations. + + + A description of the procedures employed. + + + + + A digital persistent identifier (e.g., DOI, ISO standard) referring to a detailed description of a + calibration method but no actual calibration data. + + + + + A digital persistent identifier (e.g., a DOI) referring to a publicly available calibration measurement + used for this instrument, e.g., a measurement of a known standard containing calibration information. + The axis values may be copied or linked in the appropriate NXcalibration fields for reference. + + + + + A file serialisation of a calibration which may not be publicly available (externally from the nexus file). + + This metadata can be a documentation of the source (file) or database (entry) from which pieces + of information have been extracted for consumption (e.g. in a research data management system (RDMS)). + It is also possible to include the actual file by using the `file` field. + + The axis values may be copied or linked in the appropriate NXcalibration fields for reference. + + Indicates the name of the last operation applied in the NXprocess sequence. @@ -34,6 +79,47 @@ Has the calibration been applied? + + + Vector containing the data coordinates in the original uncalibrated axis + + + + + + + The symbol of the axis to be used in the fit_function, e.g., `energy`, `E`. + This should comply to the following naming rules (similar to python's naming rules): + + * A variable name must start with a letter or the underscore character + * A variable name cannot start with a number + * A variable name can only contain alpha-numeric characters and underscores (A-z, 0-9, and _ ) + * Variable names are case-sensitive (age, Age and AGE are three different variables) + + + + + The path from which this data is derived, e.g., raw detector axis. + Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. + + + + + + Additional input axis to be used in the formula. + The part after `input_` is used as the symbol to be used in the `fit_function`, i.e., + if the field name is `input_my_field` you should refer to this axis by `my_field` in the `fit_function`. + + + + + + + The path from which this data is derived, e.g., raw detector axis. + Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. + + + For non-linear energy calibrations, e.g. in a TOF, a polynomial function is fit @@ -51,7 +137,13 @@ Use a0, a1, ..., an for the coefficients, corresponding to the values in the coefficients field. - Use x0, x1, ..., xn for the variables. + Use x0, x1, ..., xn for the nth position in the `original_axis` field. + If there is the symbol attribute specified for the `original_axis` this may be used instead of x. + If you want to use the whole axis use `x`. + Alternate axis can also be available as specified by the `input_SYMBOL` field. + The data should then be referred here by the `SYMBOL` name, e.g., for a field + name `input_my_field` it should be referred here by `my_field` or `my_field0` if + you want to read the zeroth element of the array. The formula should be numpy compliant. @@ -59,32 +151,41 @@ For linear calibration. Scaling parameter. + This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. For linear calibration. Offset parameter. + This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. - + - A vector representing the axis after calibration, matching the data length + Mapping data for calibration. + + This can be used to map data points from uncalibrated to calibrated values, + i.e., by multiplying each point in the input axis by the corresponding point in the mapping data. - - - - + - Vector containing the data coordinates in the original uncalibrated axis + A vector representing the axis after calibration, matching the data length + + + The path to which this data is written, e.g., the calibrated energy. + Should be a valid NeXus path name, e.g., /entry/data/energy. + + - + - A description of the procedures employed. + Any data acquired/used during the calibration that does not fit the `NX_FLOAT` fields above. + NXdata groups can be used for multidimensional data which are relevant to the calibration - + diff --git a/contributed_definitions/NXcg_alpha_complex.nxdl.xml b/contributed_definitions/NXcg_alpha_complex.nxdl.xml new file mode 100644 index 0000000000..b6a466bc58 --- /dev/null +++ b/contributed_definitions/NXcg_alpha_complex.nxdl.xml @@ -0,0 +1,122 @@ + + + + + + + Computational geometry of alpha shapes or alpha wrappings about primitives. + + For details see: + + * https://dx.doi.org/10.1109/TIT.1983.1056714 for 2D, + * https://dx.doi.org/10.1145/174462.156635 for 3D, + * https://dl.acm.org/doi/10.5555/871114 for weighted, and + * https://doc.cgal.org/latest/Alpha_shapes_3 for 3D implementation + * https://doc.cgal.org/latest/Manual/packages.html#PkgAlphaWrap3 for 3D wrappings + + in CGAL, the Computational Geometry Algorithms Library. + As a starting point, we follow the conventions of the CGAL library. + + + + Type of alpha complex following the terminology used by CGAL for now. + + Basic means (unweighted) alpha shapes. Alpha_wrapping means meshes + created using the alpha_wrapping algorithm. + + + + + + + + + + Are singular faces removed, i.e. has the alpha complex + been regularized or not. + + + + + + The alpha parameter, i.e. the radius of the alpha-sphere that + is used when computing the alpha complex. + + + + + + The offset distance parameter used when computing alpha_wrappings. + + + + + + + Point cloud for which the alpha shape or wrapping has been computed. + + + + + + Triangle soup for which the alpha wrapping has been computed. + + + + + Triangle mesh representing the alpha complex. + + + + + + Set of tetrahedra representing the volume inside the alpha complex. + + + + diff --git a/contributed_definitions/NXcg_cylinder_set.nxdl.xml b/contributed_definitions/NXcg_cylinder_set.nxdl.xml new file mode 100644 index 0000000000..e5bb83807a --- /dev/null +++ b/contributed_definitions/NXcg_cylinder_set.nxdl.xml @@ -0,0 +1,145 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the space in which the members are assumed embedded. + + + + + The cardinality of the set, i.e. the number of members. + + + + + Computational geometry description of a set of cylinders. + + The radius can either be defined in the radii field or by filling both + the upper_cap_radii or lower_cap_radii field. The latter field case can + thus be used to represent truncated cones. + + + + A direction vector which is parallel to the cylinder/cone axis + and whose magnitude is the height of the cylinder/cone. + + + + + + + + + + Radius of the cylinder if all have the same radius. + + + + + Radii of the cylinder. + + + + + + + + Radii of the upper circular cap. + + This field, combined with lower_cap_radius can be used to describe + (eventually truncated) circular cones. + + + + + + + + Radii of the upper circular cap. + + This field, combined with upper_cap_radius can be used to describe + (eventually truncated) circular cones. + + + + + + + + + Lateral surface area + + + + + + + + Area of the upper cap of each cylinder. + + + + + + + + Area of the lower cap of each cylinder. + + + + + + + + Sum of upper and lower cap areas and lateral surface area + of each cylinder. + + + + + + + diff --git a/contributed_definitions/NXcg_ellipsoid_set.nxdl.xml b/contributed_definitions/NXcg_ellipsoid_set.nxdl.xml new file mode 100644 index 0000000000..e22a677c11 --- /dev/null +++ b/contributed_definitions/NXcg_ellipsoid_set.nxdl.xml @@ -0,0 +1,65 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the space in which the members are assumed embedded. + + + + + The cardinality of the set, i.e. the number of members. + + + + + Computational geometry description of a set of ellipsoids. + + + + Radius of the half axes. + + Use if all ellipsoids in the set have the same half-axes. + + + + + + + + Half-axes radii of each ellipsoid. + + + + + + + + diff --git a/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml b/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml new file mode 100644 index 0000000000..48610a31d2 --- /dev/null +++ b/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml @@ -0,0 +1,241 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 2. + + + + + The number of vertices. + + + + + The number of edges. + + + + + The number of faces. + + + + + The total number of vertices of all faces. Faces are polygons. + + + + + The total number of Weinberg vector values of all faces. + + + + + Computational geometry of primitives via a face-and-edge-list data structure. + + Primitives must neither be degenerated nor self-intersect but can differ in + their properties. A face-and-edge-list-based description of primitives is + frequently used for triangles and polyhedra to store them on disk for + visualization purposes (see OFF, PLY, VTK, or STL file formats). + + Although this description is storage efficient it is not well suited for + topological analyses though. In this case, scientists may need a different + view on the primitives which is better represented with e.g. a + half_edge_data_structure. + + Having an own base class for the data structure how primitives are stored is + useful to embrace both users with small or very detailed specification demands. + + + + Hint to help resolve in which Euclidean coordinate system + field values vertices are defined. + + + + + Dimensionality of the primitives described. + + + + + + Number of vertices for each face. + + Each entry represents the total number of vertices for that face, + irrespectively whether vertices are shared among faces or not. + + + + + + + + Number of edges for each face. + + Each entry represents the total number of edges for that face, + irrespectively whether edges are shared across faces or not. + + + + + + + + Number of faces of the primitives. + + + + + Integer offset whereby the identifier of the first member + of the vertices differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + + + + + Integer offset whereby the identifier of the first member + of the edges differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + + + + + Integer offset whereby the identifier of the first member + of the faces differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + + + + + Integer identifier to distinguish all vertices explicitly. + + + + + + + + Integer used to distinguish all edges explicitly. + + + + + + + + Integer used to distinguish all faces explicitly. + + + + + + + + Positions of the vertices. + + Users are encouraged to reduce the vertices to a unique set as this may + result in a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. Naively here means that each + vertex is stored even though many share the same positions. + + + + + + + + + The edges are stored as pairs of vertex identifier. + + + + + + + + + The faces are stored as a concatenated array of vertex identifier tuples. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + + + + + + + + + If true, indicates that the vertices are all placed at different positions + and have different identifiers, i.e. no points overlap or are counted more + than once. + + + + + If true, indicates that no edge is stored more than once. + + Users are encouraged to consider using a half_edge_data_structure instead. + + + + + If true, indicates that no face is stored more than once. + + + + + Specifies for each face which winding order was used if any: + + * 0 - undefined + * 1 - counter-clockwise (CCW) + * 2 - clock-wise (CW) + + + + + + diff --git a/contributed_definitions/NXcg_geodesic_mesh.nxdl.xml b/contributed_definitions/NXcg_geodesic_mesh.nxdl.xml new file mode 100644 index 0000000000..6314db3427 --- /dev/null +++ b/contributed_definitions/NXcg_geodesic_mesh.nxdl.xml @@ -0,0 +1,55 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computational geometry description of a geodesic mesh. + + A geodesic surface mesh is a triangulated surface mesh with metadata which + can be used as an approximation to describe the surface of a sphere. + Triangulation of spheres are commonly used in Materials Science + for quantifying texture of materials, i.e. the relative rotation of + crystals to sample directions. + + For additional details or an introduction into the topic of geodesic meshes + see (from which specifically the section on subdivision schemes is relevant). + + * `E. S. Popko and C. J. Kitrick <https://doi.org/10.1201/9781003134114>`_ + + Earth scientists have specific demands and different views about what should + be included in such a base class, given that nested geodesic meshes are a key + component of climate modelling software. For now we propose to use this + base class as a container for organizing data related to geodesic meshes. + + Specifically an instance of this base class should detail the rule set how + e.g. a geodesic (surface) mesh was instantiated as there are many + possibilities to do so. + + + + diff --git a/contributed_definitions/NXcg_grid.nxdl.xml b/contributed_definitions/NXcg_grid.nxdl.xml new file mode 100644 index 0000000000..4d5aced5fe --- /dev/null +++ b/contributed_definitions/NXcg_grid.nxdl.xml @@ -0,0 +1,155 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the grid. + + + + + The cardinality or total number of cells aka grid points. + + + + + Number of boundaries of the bounding box or primitive housing the grid. + + + + + Computational geometry description of a grid of Wigner-Seitz cells in Euclidean space. + + Three-dimensional grids with cubic cells are if not the most frequently used + example of such grids. Examples of numerical methods where grids are used + are spectral-solver based crystal plasticity or other stencil methods like + phase-field or cellular automata. + + + + Location of the origin of the grid. + + Use the depends_on field that is inherited from the :ref:`NXcg_primitive_set` + class to specify the coordinate system in which the origin location is defined. + + + + + + + + The symmetry of the lattice defining the shape of the unit cell. + + + + + + + + The unit cell dimensions using crystallographic notation. + + + + + + + + Number of unit cells along each of the d unit vectors. + + The total number of cells or grid points has to be the cardinality. + If the grid has an irregular number of grid positions in each direction, + as it could be for instance the case of a grid where all grid points + outside some masking primitive are removed, this extent field should + not be used. Instead, use the coordinate field. + + + + + + + + + Position of each cell in Euclidean space. + + + + + + + + + Coordinate of each cell with respect to the discrete grid. + + + + + + + + + + A tight bounding box about the grid. + + + + + + Number of boundaries distinguished + + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + + + + + Name of domain boundaries of the simulation box/ROI + e.g. left, right, front, back, bottom, top. + + + + + + + + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + + + + + + diff --git a/contributed_definitions/NXcg_half_edge_data_structure.nxdl.xml b/contributed_definitions/NXcg_half_edge_data_structure.nxdl.xml new file mode 100644 index 0000000000..40213352e3 --- /dev/null +++ b/contributed_definitions/NXcg_half_edge_data_structure.nxdl.xml @@ -0,0 +1,207 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 2. + + + + + The number of vertices. + + + + + The number of faces. + + + + + The number of half-edges. + + + + + Computational geeometry description of a half-edge data structure. + + Such a data structure can be used to efficiently circulate around faces + and iterate over vertices of a planar graph. + + + + Hint to help resolve in which Euclidean coordinate system + field values vertices are defined. + + + + + Dimensionality of the primitives described. + + + + + + Number of vertices for each face. + + Each entry represents the total number of vertices for that face, + irrespectively whether vertices are shared among faces or not. + + + + + + + + Number of edges for each face. + + Each entry represents the total number of edges for that face, + irrespectively whether edges are shared across faces or not. + + + + + + + + Number of faces of the primitives. + + + + + Integer offset whereby the identifier of the first member + of the vertices differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + + + + + Integer offset whereby the identifier of the first member + of the edges differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + + + + + Integer offset whereby the identifier of the first member + of the faces differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + + + + + + The position of the vertices. + + + + + + + + + Identifier of the incident half-edge. + + + + + + + + Identifier of the (starting)/associated half-edge of the face. + + + + + + + + The identifier of the vertex from which this half-edge is outwards pointing. + + + + + + + + Identifier of the associated oppositely pointing half-edge. + + + + + + + + If the half-edge is a boundary half-edge the + incident face identifier is NULL, i.e. 0. + + + + + + + + Identifier of the next half-edge. + + + + + + + + Identifier of the previous half-edge. + + + + + + + + Users are referred to the literature for the background of L. Weinberg's + work about topological characterization of planar graphs: + + * `L. Weinberg 1966a, <https://dx.doi.org/10.1109/TCT.1964.1082216>`_ + * `L. Weinberg, 1966b, <https://dx.doi.org/10.1137/0114062>`_ + * `E. A. Lazar et al. <https://doi.org/10.1103/PhysRevLett.109.095505>`_ + + and how this work can e.g. be applied in space-filling tessellations + of microstructural objects like crystals/grains. + + + + diff --git a/contributed_definitions/NXcg_hexahedron_set.nxdl.xml b/contributed_definitions/NXcg_hexahedron_set.nxdl.xml new file mode 100644 index 0000000000..8ea85fb981 --- /dev/null +++ b/contributed_definitions/NXcg_hexahedron_set.nxdl.xml @@ -0,0 +1,193 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of hexahedra. + + + + + Computational geometry description of a set of hexahedra in Euclidean space. + + This class can also be used to describe cuboids or cubes, axis-aligned or not. + The class represents different access and description levels to offer both + applied scientists and computational geometry experts an approach whereby + different specific views can be implemented using the same base class: + + * In the simplest case experimentalists may use this base class to describe + the dimensions or size of a specimen. In this case the alignment with axes + is not relevant as eventually only the volume of the specimen is of interest. + * In many cases, take for example an experiment where a specimen was cut out + from a specifically deformed piece of material, the orientation of the + specimen's edges with the experiment coordinate system is of high relevance. + Examples include knowledge about the specimen edge, whether it is + parallel to the rolling, the transverse, or the normal direction. + * While the above-mentioned use cases are sufficient to pinpoint the sample + within a known laboratory/experiment coordinate system, these descriptions + are not detailed enough to specify e.g. a CAD model of the specimen. + * Therefore, groups and fields for an additional, computational-geometry- + based view of hexahedra is offered to serve additional computational + tasks: storage-oriented simple views or detailed topological/graph-based + descriptions. + + Hexahedra are important geometrical primitives, which are among the most + frequently used elements in finite element meshing/modeling. + + As a specialization of the :ref:`NXcg_primitive_set` base class hexahedra + are assumed non-degenerated, closed, and built of polygons that are + not self-intersecting. + + The term hexahedra will be used throughout this base class but includes + the special cases cuboid, cube, box, axis-aligned bounding box (AABB), + and optimal bounding box (OBB). + + An axis-aligned bounding box is a common data object in computational science + and simulation codes to represent a cuboid whose edges are aligned with the + base vectors of a coordinate system. As a part of binary trees, these data + objects are important for making time- as well as space-efficient queries + of geometric primitives in techniques like kd-trees. + + An optimal bounding box is a common data object which provides the best + tightly fitting box about an arbitrary object. In general, such boxes are + rotated. Exact and substantially faster in practice approximate algorithms + exist to compute optimal or near optimal bounding boxes for sets of points. + + + + + Qualifier for the shape of each hexahedron. + + + + + + + + + Qualifier that is useful in cases when one edge is longer than all other + edges of the hexahedra. Often the term length is associated with the + assumption that one edge is parallel to an axis of the coordinate system. + + + + + + + + Qualifier often used to describe the extent of an object in the horizontal + direction assuming a specific coordinate system. + + For the sake of explicitness quantities like length, width, and height + should not be reported without specifying also the assumed reference frame. + + + + + + + + Qualifier often used to describe the extent of an object in the vertical + direction assuming a specific coordinate system. + + + + + + + + Volume of each hexahedron. + + + + + + + + Total (surface) area (of all six faces) of each hexahedron. + + + + + + + + Area of each of the six faces of each hexahedron. + + + + + + + + + Specifies if the hexahedra represent cuboids or cubes eventually rotated + ones but at least not too exotic six-faced polyhedra. + + + + + + + + Only to be used if is_box is present. In this case, this field describes + whether hexahedra are boxes whose primary edges are parallel to the + axes of the coordinate system. + + + + + + + + + + + + + Combined storage of all primitives of all hexahedra. + + + + + Individual storage of each hexahedron. + + + + + Individual storage of each hexahedron as a graph. + + + diff --git a/contributed_definitions/NXcg_marching_cubes.nxdl.xml b/contributed_definitions/NXcg_marching_cubes.nxdl.xml new file mode 100644 index 0000000000..4cc765fd82 --- /dev/null +++ b/contributed_definitions/NXcg_marching_cubes.nxdl.xml @@ -0,0 +1,61 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computational geometry description of the marching cubes algorithm. + + Documenting which specific version was used helps with understanding how + robust the results are with respect to the topology of the triangulation. + + + + Reference/link to and/or details of the grid on which a specific + marching cubes algorithm implementation is operating. + + + + + Reference to the specific implementation of marching cubes used. + + See for example the following papers for details about how to identify a + DOI which specifies the implementation used: + + * `W. E. Lorensen <https://doi.org/10.1109/MCG.2020.2971284>`_ + * `T. S. Newman and H. Yi <https://doi.org/10.1016/j.cag.2006.07.021>`_ + + The value placed here should be a DOI. If there are no specific DOI or + details write not_further_specified, or give at least a free-text + description. + + + + + diff --git a/contributed_definitions/NXcg_parallelogram_set.nxdl.xml b/contributed_definitions/NXcg_parallelogram_set.nxdl.xml new file mode 100644 index 0000000000..bfb868c47d --- /dev/null +++ b/contributed_definitions/NXcg_parallelogram_set.nxdl.xml @@ -0,0 +1,106 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of parallelograms. + + + + + Computational geometry description of a set of parallelograms. + + This class can also be used to describe rectangles or squares, irrespective + whether these are axis-aligned or not. The class represents different + access and description levels to embrace applied scientists and computational + geometry experts with their different views: + + * The simplest case is the communication of dimensions aka the size of a + region of interest in the 2D plane. In this case, communicating the + alignment with axes is maybe not as relevant as it is to report the area + of the ROI. + * In other cases the extent of the parallelogram is relevant though. + * Finally, in CAD models it should be possible to specify the polygons + which the parallelograms represent with exact numerical details. + + Parallelograms are important geometrical primitives as their usage for + describing many scanning experiments shows where typically parallelogram-shaped + ROIs are scanned across the surface of a sample. + + The term parallelogram will be used throughout this base class thus including + the important special cases rectangle, square, 2D box, axis-aligned bounding box + (AABB), or optimal bounding box (OBB) as analogous 2D variants to their 3D + counterparts. See :ref:`NXcg_hexahedron_set` for the generalization in 3D. + + An axis-aligned bounding box is a common data object in computational science + and simulation codes to represent a rectangle whose edges are aligned with the + axes of a coordinate system. As a part of binary trees AABBs are important data + objects for executing time- as well as space-efficient queries + of geometric primitives in techniques like kd-trees. + + An optimal bounding box is a common data object which provides the best, i.e. + most tightly fitting box about an arbitrary object. In general such boxes are + rotated. Other than in 3D dimensions, the rotation calipher method offers + a rigorous approach to compute an optimal bounding box to a point set in 2D. + + + + + To specify which parallelogram is a rectangle. + + + + + + + + Only to be used if is_rectangle is present. In this case, this field + describes whether parallelograms are rectangles whose primary edges + are parallel to the axes of the coordinate system. + + + + + + + + + + Combined storage of all primitives of all parallelograms. + + + + + Individual storage of each parallelogram. + + + + diff --git a/contributed_definitions/NXcg_point_set.nxdl.xml b/contributed_definitions/NXcg_point_set.nxdl.xml new file mode 100644 index 0000000000..c2190590d0 --- /dev/null +++ b/contributed_definitions/NXcg_point_set.nxdl.xml @@ -0,0 +1,87 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality. + + + + + The cardinality of the set, i.e. the number of points. + + + + + Computational geometry description of a set of points. + + Points may have an associated time value. Users are advised though to store + time data of point sets rather as instances of time events, where for each + point in time there is an :ref:`NXcg_point_set` instance which specifies the + points' locations. + + This is a frequent situation in experiments and computer simulations, where + positions of points are taken at the same point in time (real time or + simulated physical time). Thereby, the storage of redundant time stamp + information per point is considered as obsolete. + + + + Coordinates of the points. + + + + + + + + + (Elapsed) time for each point. + + If the field time is needed contextualize the time_offset relative to which + time values are defined. Alternative store timestamp. + + + + + + + + ISO8601 with local time zone offset for each point. + + + + + + + + ISO8601 with local time zone offset that serves as the reference + for values in the field time. + + + diff --git a/contributed_definitions/NXcg_polygon_set.nxdl.xml b/contributed_definitions/NXcg_polygon_set.nxdl.xml new file mode 100644 index 0000000000..95c157ce1e --- /dev/null +++ b/contributed_definitions/NXcg_polygon_set.nxdl.xml @@ -0,0 +1,131 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be either 2 or 3. + + + + + The cardinality of the set, i.e. the number of polygons. + + + + + + The total number of vertices when visiting every polygon. + + + + + + Computational geometry description of a set of polygons in Euclidean space. + + Polygons are specialized polylines: + + * A polygon is a geometric primitive that is bounded by a closed polyline + * All vertices of this polyline lay in the d-1 dimensional plane. + whereas vertices of a polyline do not necessarily lay on a plane. + * A polygon has at least three vertices. + + Each polygon is built from a sequence of vertices (points with identifiers). + The members of a set of polygons may have a different number of vertices. + Sometimes a collection/set of polygons is referred to as a soup of polygons. + + As three-dimensional objects, a set of polygons can be used to define the + hull of what is effectively a polyhedron; however users are advised to use + the specific :ref:`NXcg_polyhedron_set` base class if they wish to describe closed + polyhedra. Even more general complexes can be thought of. An example are the + so-called piecewise-linear complexes used in the TetGen library. + + As these complexes can have holes though, polyhedra without holes are one + subclass of such complexes, users should rather design an own + base class e.g. NXcg_polytope_set to describe such even more + complex primitives instead of abusing this base class for such purposes. + + + + The total number of vertices in the set. + + + + + + Combined storage of all primitives of all polygons. + + + + + Individual storage of the mesh of each polygon. + + + + + Individual storage of each polygon as a graph. + + + + + + For each polygon its accumulated length along its edges. + + + + + + + + Interior angles for each polygon. There are as many values per polygon + as the are number_of_vertices. + The angle is the angle at the specific vertex, i.e. between the adjoining + edges of the vertex according to the sequence in the polygons array. + Usually, the winding_order field is required to interpret the value. + + + + + + + + Curvature type: + + * 0 - unspecified, + * 1 - convex, + * 2 - concave + + + + + + diff --git a/contributed_definitions/NXcg_polyhedron_set.nxdl.xml b/contributed_definitions/NXcg_polyhedron_set.nxdl.xml new file mode 100644 index 0000000000..b087b0c790 --- /dev/null +++ b/contributed_definitions/NXcg_polyhedron_set.nxdl.xml @@ -0,0 +1,114 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of polyhedra. + + + + + The total number of edges for all polyhedra. + + + + + The total number of faces for all polyhedra. + + + + + Computational geometry description of a set of polyhedra in Euclidean space. + + Polyhedra or so-called cells (especially in the convex of tessellations) are + constructed from polygon meshes. Polyhedra may make contact to allow a usage + of this base class for a description of tessellations. + + For the description of more complicated manifolds and especially for polyhedra + with holes, users are advised to check if their particular needs are described + by creating customized instances of an :ref:`NXcg_polygon_set`. + + + + + The number of faces for each polyhedron. Faces of adjoining polyhedra + are counted for each polyhedron. + + + + + + + + Area of each of faces. + + + + + + + + The number of edges for each polyhedron. Edges of adjoining polyhedra + are counterd for each polyhedron. + + + + + Length of each edge. + + + + + + + + + Combined storage of all primitives of all polyhedra. + + + + + Individual storage of each polyhedron. + + + + + Individual storage of each polygon as a graph. + + + diff --git a/contributed_definitions/NXcg_polyline_set.nxdl.xml b/contributed_definitions/NXcg_polyline_set.nxdl.xml new file mode 100644 index 0000000000..64a002f86c --- /dev/null +++ b/contributed_definitions/NXcg_polyline_set.nxdl.xml @@ -0,0 +1,145 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 1. + + + + + The cardinality of the set, i.e. the number of polylines. + + + + + + The number of vertices, supporting the polylines. + + + + + The total number of vertices traversed when visiting every polyline. + + + + + Computational geometry description of a set of polylines. + + Each polyline is built from a sequence of vertices (points with identifiers). + Each polyline must have a start and an end point. + The sequence describes the positive traversal along the polyline when + walking from the first to the last vertex. + + + + Reference to an instance of :ref:`NXcg_point_set` which defines + the location of the vertices that are referred to in the + NXcg_polyline_set instance. + + + + + The total number of vertices that have different positions. + + + + + The total number of vertices, irrespective of their eventual uniqueness. + + + + + The total number of vertices of each polyline, irrespectively + whether vertices are shared by vertices or not. + See the docstring for polylines for further details about how + a set with different polyline members should be stored. + + + + + + + + + Positions of the vertices which support the members of the polyline set. + + Users are encouraged to reduce the vertices to unique positions and vertices + as this often supports with storing geometry data more efficiently. + It is also possible though to store the vertex positions naively + in which case vertices_are_unique is likely False. + Naively, here means that one stores each vertex of a triangle mesh + even though many vertices are shared between triangles and thus + storing multiple copies of their positions is redundant. + + + + + + + + + + If true indicates that the vertices are all placed at different + positions and have different identifiers, i.e. no points overlap + or are counted several times. + + + + + Sequence of identifier for vertices how they build each polyline. + + A trivial example is a set with two polylines with three vertices each. + If the polylines meet in a junction, say the second vertex is shared + and marking the junction between the two polylines, it is possible that + there are only five unique positions. This suggests to store five + unique vertices. + + A non-trivial example is a set with several polylines. Assume that each + has a different number of vertices. The array stores the identifier of + the vertices in the sequence how the polylines are visited: + + The first entry is the identifier of the first vertex of the first polyline, + followed by the second vertex of the first polyline, until the last vertex + of the first polyline. + Thereafter, the first vertex of the second polyline, and so on and so forth. + Using the (cumulated) counts in number_of_vertices, the vertices of the + n-th polyline can be accessed on the following array index interval: + :math:`[\sum_{i=0}^{i=N-1}, \sum_{i=0}^{i=N}]`. + + + + + + diff --git a/contributed_definitions/NXcg_primitive_set.nxdl.xml b/contributed_definitions/NXcg_primitive_set.nxdl.xml new file mode 100644 index 0000000000..e8cb457bc1 --- /dev/null +++ b/contributed_definitions/NXcg_primitive_set.nxdl.xml @@ -0,0 +1,212 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the space. + + + + + The cardinality of the set, i.e. the number of members. + + + + + Computational geometry description of a set of primitives in Euclidean space. + + Primitives must neither be degenerated nor self-intersect. + Individual primitives can differ in their properties (e.g. size, shape, rotation). + + + + + Hint to help resolve in which Euclidean coordinate system field values + like center or orientation are defined. + + + + + The dimensionality of the primitive set. + + + + + + + + + + The cardinality of the primitive set. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + Therefore, implicit identifier are completely defined by the value of + identifier_offset and cardinality. For example if identifier run from + -2 to 3 the value for identifier_offset is -2. + + For explicit indexing the field identifier has to be used. + Fortran-/Matlab- and C-/Python-style indexing have specific implicit + identifier conventions where identifier_offset is 1 and 0 respectively. + + + + + Identifier of each member for explicit indexing. + + + + + + + + The center of mass position of each primitive. + + + + + + + + + + True if the center is a center of mass. + + + + + + + + A qualitative description of the shape of each primitive. + + + + + + + + + Qualifier for the length of characteristic features of the primitive. + + Often the term length is associated with the assumption that one + edge is parallel to an axis of the coordinate system. + + + + + + + + Qualifier often used to describe the length of one characteristic edge + within the coordinate system. + + + + + + + + True if primitive is closed such that it has properties like area or volume. + + + + + + + + Volume of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + + + + + + + + Alias for surface_area of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + + + + + + + + Direction unit vector which points along the + longest principal axis of each primitive. + + Use the depends_on attribute to specify in which coordinate system + these direction unit vectors are defined. + + + + + + + + + + + diff --git a/contributed_definitions/NXcg_roi_set.nxdl.xml b/contributed_definitions/NXcg_roi_set.nxdl.xml new file mode 100644 index 0000000000..69bc0042e5 --- /dev/null +++ b/contributed_definitions/NXcg_roi_set.nxdl.xml @@ -0,0 +1,57 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + Use the depends_on fields of the respective specialized + :ref:`NXcg_primitive_set` base class surplus + :ref:`NXcoordinate_system_set` with at least one instance of + :ref:`NXcoordinate_system` to define explicitly the reference frame in + which the primitives are defined. Alternatively, although + disencouraged, one may use one :ref:`NXcoordinate_system_set` with + with only one :ref:`NXcoordinate_system` in the application definition + to specify implicitly in which reference frame the primitives are + defined. If none of these two possibilities is used all primitives + are assumed defined in the McStas coordinate system. + + + + Base class for a region-of-interest (ROI) bound by geometric primitives. + + So-called region-of-interest(s) (ROIs) are typically used to describe a + region in space (and time) where an observation is made or for which + a computer simulation is performed with given boundary conditions. + + + + + + + + + diff --git a/contributed_definitions/NXcg_sphere_set.nxdl.xml b/contributed_definitions/NXcg_sphere_set.nxdl.xml new file mode 100644 index 0000000000..8b12834749 --- /dev/null +++ b/contributed_definitions/NXcg_sphere_set.nxdl.xml @@ -0,0 +1,61 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 2. + + + + + The cardinality of the set, i.e. the number of circles or spheres. + + + + + Computational geometry description of a set of spheres. + + Each sphere can have a different radius but all need to have finite volume. + + + + In the case that all spheres have the same radius. + + + + + In the case that spheres have different radius use this + instead of the radius field. + + + + + + diff --git a/contributed_definitions/NXcg_tetrahedron_set.nxdl.xml b/contributed_definitions/NXcg_tetrahedron_set.nxdl.xml new file mode 100644 index 0000000000..509347c515 --- /dev/null +++ b/contributed_definitions/NXcg_tetrahedron_set.nxdl.xml @@ -0,0 +1,86 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of tetrahedra. + + + + + Computational geometry description of a set of tetrahedra. + + Among hexahedral elements, tetrahedral elements are one of the most + frequently used geometric primitive for meshing and describing volumetric + objects in continuum-field simulations. + + + + + Area of each of the four triangular faces of each tetrahedron. + + + + + + + + + Length of each edge of each tetrahedron. + + + + + + + + + + Combined storage of all primitives of all tetrahedra. + + + + + Individual storage of each tetrahedron. + + + + + Individual storage of each tetrahedron as a graph. + + + diff --git a/contributed_definitions/NXcg_triangle_set.nxdl.xml b/contributed_definitions/NXcg_triangle_set.nxdl.xml new file mode 100644 index 0000000000..7d994eb3e9 --- /dev/null +++ b/contributed_definitions/NXcg_triangle_set.nxdl.xml @@ -0,0 +1,97 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 2. + + + + + The cardinality of the set, i.e. the number of triangles. + + + + + The number of unique vertices supporting the triangles. + + + + + Computational geometry description of a set of triangles. + + + + Number of unique vertices in the triangle set. + + + + + Combined storage of all primitives of all triangles. + + This description resembles the typical representation of primitives + in file formats such as OFF, PLY, VTK, or STL. + + + + + Individual storage of each triangle. + Users are advised that using such individual storage of primitives + may be less storage efficient than creating a combined storage. + + + + + + Length of the edges of each triangle. + + For each triangle values are reported via traversing + the vertices in the sequence as these are defined. + + + + + + + + + Interior angles of each triangle. + + For each triangle values are reported for the angle opposite + to the respective edges in the sequence how vertices are defined. + + + + + + + diff --git a/contributed_definitions/NXcg_triangulated_surface_mesh.nxdl.xml b/contributed_definitions/NXcg_triangulated_surface_mesh.nxdl.xml new file mode 100644 index 0000000000..da55b25306 --- /dev/null +++ b/contributed_definitions/NXcg_triangulated_surface_mesh.nxdl.xml @@ -0,0 +1,42 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computational geometry description of a mesh of triangles. + + The mesh may be self-intersecting and have holes but the + triangles used must not be degenerated. + + + + A graph-based approach to describe the mesh when it is also desired + to perform topological processing or analyses on the mesh. + + + diff --git a/contributed_definitions/NXcg_unit_normal_set.nxdl.xml b/contributed_definitions/NXcg_unit_normal_set.nxdl.xml new file mode 100644 index 0000000000..21470b34f0 --- /dev/null +++ b/contributed_definitions/NXcg_unit_normal_set.nxdl.xml @@ -0,0 +1,75 @@ + + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality, which has to be at least 2. + + + + + The cardinality of the set, i.e. the number of unit normals. + + + + + Computational geometry description of a set of (oriented) unit normal vectors. + + Store normal vector information as properties of primitives. + Use only only as a child of an instance of :ref:`NXcg_primitive_set` + so that this instance acts as the parent to define a context. + + + + Direction of each normal - a unit normal. + + + + + + + + + Qualifier which details the orientation of each normal vector + in relation to its primitive, assuming the object is viewed + from a position outside the object. + + * 0 - undefined + * 1 - outer unit normal vector + * 2 - inner unit normal vector + + + + + + diff --git a/contributed_definitions/NXchamber.nxdl.xml b/contributed_definitions/NXchamber.nxdl.xml index 4a6973cc81..f6cbac9137 100644 --- a/contributed_definitions/NXchamber.nxdl.xml +++ b/contributed_definitions/NXchamber.nxdl.xml @@ -1,19 +1,41 @@ - + - + + - Component of an instrument to store or place objects and specimens. + Base class for a chamber in an instrument that stores real or simulated objects. - Given name/alias. + Given name for the chamber of this component e.g. analysis chamber + or buffer chamber, load-lock chamber, microscope column, glove box. - Free-text field for describing details about the chamber. For example out of which material was the chamber built. + diff --git a/contributed_definitions/NXchemical_composition.nxdl.xml b/contributed_definitions/NXchemical_composition.nxdl.xml new file mode 100644 index 0000000000..fd92848709 --- /dev/null +++ b/contributed_definitions/NXchemical_composition.nxdl.xml @@ -0,0 +1,69 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The number of samples or things. + + + + + (Chemical) composition of a sample or a set of things. + + + + + Total based on which composition information is normalized. + + + + + + + + + Count or weight which, when divided by total yields the composition + of this element, isotope, molecule or ion. + + + + + + + + Count divided by total in atom percent. + + + + + + + diff --git a/contributed_definitions/NXchemical_process.nxdl.xml b/contributed_definitions/NXchemical_process.nxdl.xml new file mode 100644 index 0000000000..437fcf0b6a --- /dev/null +++ b/contributed_definitions/NXchemical_process.nxdl.xml @@ -0,0 +1,60 @@ + + + + + + A planned or unplanned process which results in chemical changes (i.e., changes in the chemical bonds) in a specified material. + + Examples include any chemical reactions (addition, subtraction, replacement, ...). + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process started. + + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process ended. + + + + + Short description of the chemical process. + + + + + Method by which this process was performed. + + + + + This can be any data or other descriptor acquired during the chemical process + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + + + diff --git a/contributed_definitions/NXcircuit.nxdl.xml b/contributed_definitions/NXcircuit.nxdl.xml new file mode 100644 index 0000000000..ede8976178 --- /dev/null +++ b/contributed_definitions/NXcircuit.nxdl.xml @@ -0,0 +1,136 @@ + + + + + + Application definition for circuit devices. + + + + Hardware type used in circuit, includes hardware manufacturers and type + + + + + The tunneling current between tip and sample after application of bias voltage. + + + + + Calibration of the current measurement (A/V). + + + + + Offset of the current measurement. + + + + + Proportional relationship between the probe output voltage and the actual + tunneling current when measuring the tunneling current. + + + + + The scan channels are selected by users (in scan contronaller). + + + + + The bandwitdh of the Hardware and/or Software + + + + + (Signals Periods) The Signals Period is the rate at which the signals are + transferred to the host computer running the control software. This is usually + lower by a factor of 10 than the sampling rate, because an internal oversampling + of the signal is done on the real time engine. You can reduce the oversampling + down to 1 in order to resolve higher frequencies in the Spectrum Analyzer. + + + + + Update rate for several processes like History Graph, Auto-Approach, and for + many Programming Interface functions. This is usually set to 20 ms. All + additional timings (7-9) can only be integer multiples of this value. They can + be set to different values, but the actual timing value will be coerced to a + multiple of the Acquisition Period. + + + + + Update rate of animated graphical indicators. These are e.g. some graphs & + sliders. A reasonable value is 40 ms (25 updates per second). Increase this + period to reduce the processor load for the graphical user interface, especially + on slow computers. This value is purely a user interface update rate and does + not affect measurements in any way. + + + + + Update rate of digital indicators, e.g. the numbers displayed besides each + slider. Here, 3 updates per second, or 300 ms is enough. This value is purely a + user interface update rate and does not affect measurements in any way. + + + + + The Measurements period is the integration time for precise measurements + (averaging over specified period), mostly used in sweep modules. Examples are + recording of a force-distance curve or a resonance of a cantilever. For fast + measurements with small steps, a value of 40 ms may be reasonable. For normal + use, 300-500 ms is a good value, but for recording a resonance of a high-Q + cantilever, values of several seconds might be necessary. Usually this parameter + doesn’t need to be set from this module; the sweep modules will set this value + according to the sweep timings. + + + + + Number of output channels + + + + + The user output in each monitor mode. + + + + + The values for each output channel. + + + + + User outputs whose name can be modified in the corresponding module. + + + + + The rate at which the one of the signal changes when ramping to the starting + point. (V/s) + + + diff --git a/contributed_definitions/NXcircuit_board.nxdl.xml b/contributed_definitions/NXcircuit_board.nxdl.xml new file mode 100644 index 0000000000..9610f8f43f --- /dev/null +++ b/contributed_definitions/NXcircuit_board.nxdl.xml @@ -0,0 +1,45 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Circuit board with e.g. ADC and/or DAC electronic components. + + Currently used to store the settings of the so-called magboards used in + Nion electron microscopes but likely this could be a useful base class for + substantially more use cases where details at a deep technical instrument design + level are relevant or important. + + + + TBD by Nion Co. + + + + + diff --git a/contributed_definitions/NXclustering.nxdl.xml b/contributed_definitions/NXclustering.nxdl.xml new file mode 100644 index 0000000000..147c4baa1b --- /dev/null +++ b/contributed_definitions/NXclustering.nxdl.xml @@ -0,0 +1,124 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of numeral labels per object. + + + + + Number of categorical labels per object. + + + + + Total number of clusters detected. + + + + + Metadata to the results of a clustering analysis. + + Clustering algorithms are routine tools to segment a set of objects/primitives + into groups, objects of different type. A plethora of algorithms have been + proposed for geometric primitives as objects, such as points, triangles, + or (abstract) objects. + + This base class considers metadata and results of one clustering + applied to a set in which objects are either categorized as noise + or belonging to a cluster, specifically here only one cluster. + + + + How many numeric labels does each object have. + + + + + How many categorical labels does each object have. + + + + + Reference to a set of objects investigated in a cluster analysis. + Objects must have clear integer identifier. + + + + + Reference to numeric attribute data for each object. + + + + + Reference to categorical attribute data for each object. + + + + + + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + + + + + Total number of objects categorized as unassigned. + + + + + Total number of objects categorized as noise. + + + + + Total number of clusters (excluding noise and unassigned). + + + + + Number of objects associated to each cluster. The labels are implicit, + meaning the zeroth/first entry in the array belongs to the first cluster, + the second entry to the second cluster and so on and so forth. + The first cluster has the value of identifier_offset as its identifier. + The second cluster has identifier_offset + 1, and so on and so forth. + + + + + + + diff --git a/contributed_definitions/NXcollectioncolumn.nxdl.xml b/contributed_definitions/NXcollectioncolumn.nxdl.xml index 13e0d213f3..a154c58abf 100644 --- a/contributed_definitions/NXcollectioncolumn.nxdl.xml +++ b/contributed_definitions/NXcollectioncolumn.nxdl.xml @@ -1,9 +1,30 @@ - + - + + - Subclass of NXelectronanalyser to describe the electron collection column of a - photoelectron analyser. + Subclass of NXelectronanalyser to describe the electron collection + column of a photoelectron analyser. @@ -27,7 +48,7 @@ Distance between sample and detector entrance - + Labelling of the lens setting in use. @@ -41,6 +62,20 @@ + + + Acceptance angle of the collection column. + + This concept is related to term `7.4`_ of the ISO 18115-1:2023 standard. + + .. _7.4: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.4 + + + + + Acceptance length or area of the collection column. + + The magnification of the electron lens assembly. @@ -80,4 +115,5 @@ Individual lenses in the collection column section + diff --git a/contributed_definitions/NXcomponent_em.nxdl.xml b/contributed_definitions/NXcomponent_em.nxdl.xml new file mode 100644 index 0000000000..a68436e9b7 --- /dev/null +++ b/contributed_definitions/NXcomponent_em.nxdl.xml @@ -0,0 +1,69 @@ + + + + + + + Base class for components used in an electron microscope. + + The electron microscope can be a real one or a simulated microscope. + The key motivation behind this generalization is the observation that in all + cases a controlled electron beam is generated in reality or that beam is simulated + and this beam is then used or modified in a controlled manner for the purpose + of studying physical interaction mechanisms of the beam with matter. + Here it does not matter whether one considers a real specimen or a simulated one. + + Using a common description for the real experiment in the lab and - what is + typically a simplification of it - via a computer simulation, has the benefit + that many pieces of information can be stored in the same way. In effect, + users are guided with finding information and unnecessary descriptive + variety for what are exactly the same concept is avoided to work towards + more interoperability. + + Another motivation to make no fundamental distinction between a scanning and + a transmission electron microscope is that both are electron microscopes whose + components are often very similar. + + + + Given name to the component e.g stage, lens C1, etc. + + + + + Ideally, a (globally) unique persistent identifier, link, or text to a + resource which gives further details to this component. + If such resource does not exist, a free-text field to report + further details about the component is possible. + + + + + + + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. + + + diff --git a/contributed_definitions/NXcoordinate_system.nxdl.xml b/contributed_definitions/NXcoordinate_system.nxdl.xml new file mode 100644 index 0000000000..494b92956e --- /dev/null +++ b/contributed_definitions/NXcoordinate_system.nxdl.xml @@ -0,0 +1,143 @@ + + + + + + Base class to detail a coordinate system (CS). + + Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as + a member in an :ref:`NXcoordinate_system_set` and the name of the instance + should be this alias. This may support a process whereby jargon when talking + about coordinate systems and conventions may become cleaner for users + because it is not evident for people outside a lab that terms like e.g. + tip space or specimen space refer to the same coordinate system. + This is an example of jargon used in e.g. the field of atom + probe tomography. + + + + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door-handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. + + + + + + An alternative name given to that coordinate system. + + + + + Coordinate system type. + + + + + + + + Handedness of the coordinate system if it is a Cartesian. + + + + + + + + + Possibility to define an alias for the name of the x-axis. + + + + + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. + + + + + Base unit vector along the first axis which spans the coordinate system. + This axis is frequently referred to as the x-axis in real space and + the i-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the y-axis. + + + + + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the z-axis. + + + + + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. + + + + + + diff --git a/contributed_definitions/NXcoordinate_system_set.nxdl.xml b/contributed_definitions/NXcoordinate_system_set.nxdl.xml index 3e1d15e101..11b22f28fa 100644 --- a/contributed_definitions/NXcoordinate_system_set.nxdl.xml +++ b/contributed_definitions/NXcoordinate_system_set.nxdl.xml @@ -1,62 +1,120 @@ - + - + + - Container to hold different coordinate systems conventions. - - It is the purpose of this base class to define these conventions and - offer a place to store mappings between different coordinate systems - which are relevant for the interpretation of the data described - by the application definition and base class instances. - - For each Cartesian coordinate system users should use a set of - NXtransformations: - - * These should define the three base vectors. - * The location of the origin. - * The affine transformations which bring each axis of this coordinate system - into registration with the McStas coordinate system. - * Equally, affine transformations should be given for the inverse mapping. - - As an example one may take an experiment or computer simulation where - there is a laboratory (lab) coordinate system, a sample/specimen coordinate - system, a crystal coordinate system, and additional coordinate systems, - which are eventually attached to components of the instrument. - - If no additional transformation is specified in this group or if an - instance of an NXcoordinate_system_set is absent it should be assumed - the so-called McStas coordinate system is used. - - Many application definitions in NeXus refer to this `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ coordinate system. - This is a Cartesian coordinate system whose z axis points along the neutron - propagation axis. The systems y axis is vertical up, while the x axis points - left when looking along the z-axis. Thus, McStas is a right-handed coordinate system. - - Within each NXtransformations a depends_on section is required. The depends_on - field specifies if the coordinate system is the root/reference - (which is indicated by writing "." in the depends_on section.) + Base class to hold different coordinate systems and representation conversions. + + How many nodes of type :ref:`NXcoordinate_system_set` should be used in an appdef? + + * 0; if no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across + the appdef an instance of NXcoordinate_system is defined, + the default NeXus `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ + coordinate system is assumed. This makes :ref:`NXcoordinate_system_set` and + NXcoordinate_system base classes backwards compatible to older + NeXus conventions and classes. + * 1; if only one :ref:`NXcoordinate_system_set` is defined, it should be placed + as high up in the node hierarchy (ideally right below an instance of NXentry) + of the application definition tree as possible. + This :ref:`NXcoordinate_system_set` should at least define one NXcoordinate_system + instance which should be called mcstas for the sake of improved clarity. + Alternatively, at least one NXcoordinate_system member of the set should be + defined and named such that it is clear how this coordinate system is + typically referred to in a community. Additional NXcoordinate_system instances + should be specified if possible in that same :ref:`NXcoordinate_system_set` instead + of cluttering them across the tree. + + If this is the case, it is assumed that the NXcoordinate_system_members + overwrite the NeXus default McStas coordinate system, i.e. users can thereby + conveniently and explicitly specify the coordinate system(s) that + they wish to use. + + Users are encouraged to write also explicit and clean depends_on fields in + all groups that encode information about where the interpretation of coordinate + systems is relevant. If these depends_on hints are not provided, it is + automatically assumed that all children (to arbitrary depth) + of that branch and sub-branches below the one in which that + :ref:`NXcoordinate_system_set` is defined use either the only NXcoordinate_system_set + instance in that set or the application definition is considered + underconstrained which should at all costs be avoided and in which case + again McStas is assumed. + * 2 and more; as soon as more than one :ref:`NXcoordinate_system_set` is specified + somewhere in the tree, different interpretations are possible as to which + of these coordinate system sets and instances apply or take preference. + We realize that such ambiguities should at all costs be avoided. + However, the opportunity for multiple sets and their instances enables to + have branch-specific coordinate system conventions which could especially + be useful for deep classes where multiple scientific methods are combined or + cases where having a definition of global translation and conversion tables + how to convert between representations in different coordinate systems + is not desired or available for now. + We argue that having 2 or more :ref:`NXcoordinate_system_set` instances and respective + NXcoordinate_system instances makes the interpretation eventually unnecessary + complicated. Instead, developers of application definitions should always try + to work for clarity and thus use only one top-level coordinate system set. + + For these reasons we conclude that the option with one top-level + :ref:`NXcoordinate_system_set` instance is the preferred choice. + + McStas is used if neither an instance of :ref:`NXcoordinate_system_set` nor an instance + of NXcoordinate_system is specified. However, even in this case it is better + to be explicit like for every other coordinate system definition to support + users with interpreting the content and logic behind every instance of the tree. + + How to store coordinate systems inside :ref:`NXcoordinate_system_set`? + Individual coordinate systems should be specified as members of the + :ref:`NXcoordinate_system_set` instance using instances of NXcoordinate_system. + + How many individual instances of NXcoordinate_system to allow within one + instance of :ref:`NXcoordinate_system_set`? + + * 0; This case should be avoided for the sake of clarity but this case could + mean the authors of the definition meant that McStas is used. We conclude, + McStas is used in this case. + * 1; Like above-mentioned this case has the advantage that it is explicit + and faces no ambiguities. However, in reality typically multiple + coordinate systems have to be mastered especially for complex + multi-signal modality experiments. + * 2 or more; If this case is realized, the best practice is that in every + case where a coordinate system should be referred to the respective class + has a depends_on field which resolves the possible ambiguities which specific + coordinate systems is referred to. The benefit of this explicit and clear + specifying of the coordinate system used in every case is that especially + in combination with having coordinate systems inside deeper branches + makes up for a very versatile, backwards compatible, but powerful system + to express different types of coordinate systems using NeXus. + + In effect, 1 should be the preferred choice. However, if more than one coordinate + system is defined for practical purposes, explicit depends_on fields should + always guide the user for each group and field which of the coordinate system + one refers to. - - - A group of transformations which specify: - - * Three base vectors of the coordinate system. - * Origin of the coordinate system. - * A depends_on keyword. Its value can be "." or the name of an - NXtransformations instance which needs to exist in the - NXcoordinate_system_set instance. - * If the coordinate system is the reference one it has to be named - reference. - - In case of having more than one NXtransformations there has to be for - each additional coordinate system, i.e. the one not the reference: - - * A set of translations and rotations which map each base vector to the reference. - * A set of translations and rotations which map each reference base vector - to the coordinate system. - - The NXtransformations for these mappings need to be formatted - according to the descriptions in NXtransformations. - - + + diff --git a/contributed_definitions/NXcorrector_cs.nxdl.xml b/contributed_definitions/NXcorrector_cs.nxdl.xml index 47e10cf9f7..94c9b891f2 100644 --- a/contributed_definitions/NXcorrector_cs.nxdl.xml +++ b/contributed_definitions/NXcorrector_cs.nxdl.xml @@ -1,40 +1,116 @@ - + - + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of images taken, at least one. + + + Corrector for aberrations in an electron microscope. - Different vendors use a different naming schemes for aberration coefficients. - It is the users responsibility to map to the best matching values. + Different technology partners use different naming schemes and + models for quantifying the aberration coefficients. - In transmission electron microscopes the spherical aberration corrector is - a component that is controlled via instructing the microscope to achieve - set point values. The corrector is composed of multiple lenses and other - parts with vendor-specific details which are often undisclosed. - - In the case of Nion Co. microscopes the coefficients of the corrector can be - retrieved via NionSwift, which is why currently the Nion convention for the - aberration coefficients is used. + The corrector in an electron microscope is composed of multiple lenses + and multipole stigmators with details specific for the technology partner + and microscope. Many of their technical details is proprietary knowledge. Was the corrector used? - + + - Given name/alias. + Specific information about the concrete alignment procedure which is a + process during which the corrector is configured to enable a calibrated + usage of the instrument. + + This :ref:`NXprocess` group should also be used when one describes in a computer + simulation the specific details about the modelled or assumed aberration + corrections. In effect, this base class can also be used for harmonizing + the description of such simulation details across different computer codes + to enable that a research data management system can find these information + in a common place - formatted in a normalized representation. + This reduces the necessity to include substantial case-dependent verification + code in the research data management system. - - - - - Ideally, a (globally) unique persistent identifier, link, - or text to a resource which gives further details. If this does not exist - a free-text field to report further details about the corrector. - - - + + + Discouraged free-text field to add further details about + the alignment procedure. + + + + + The outer tilt angle of the beam in tableau acquisition. + + TODO: The relevant axes which span the tilt_angle need a + cleaner description. + + + + + + + + The exposure time of single tilt images. + + + + + + + + The factor of enlargement of the apparent size, + not the physical size, of an object. + + + + + + + + The images taken during the alignment procedure. + + + + + Place for storing measured or estimated aberrations (for each image or final). + + + + + + - + diff --git a/contributed_definitions/NXcrystal_structure.nxdl.xml b/contributed_definitions/NXcrystal_structure.nxdl.xml new file mode 100644 index 0000000000..921663cef6 --- /dev/null +++ b/contributed_definitions/NXcrystal_structure.nxdl.xml @@ -0,0 +1,280 @@ + + + + + + + + + Number of reflectors (Miller crystallographic plane triplets). + + + + + Number of atom positions. + + + + + Dimensionality of the lattice. + + + + + Base class to describe the atomic crystal structure of a phase. + + This base class contains key metadata that are relevant parameter to every + physics-based model to simulate radiation matter interaction. + + Examples where such base class is useful are kinematic or dynamic + diffraction simulations of e.g. (Kikuchi or other type of) patterns. + + + + Detail in which reference frame the unit cell is defined. + + + + + Dimensionality of the lattice. + + + + + + + + + + Reference to another resource that was used for + instantiating this structure model. + + + + + Crystallography unit cell parameters a, b, and c. + + + + + + + + + Crystallography unit cell parameters alpha, beta, and gamma. + + + + + + + + Area of the unit cell considering that d = 2. + + + + + Volume of the unit cell considering that d = 3. + + + + + Crystal system + + + + + + + + + + + + + + + Laue group using International Table of Crystallography Notation. + + + + + + Point group using International Table of Crystallography Notation. + + + + + + Space group from the International Table of Crystallography Notation. + + + + + + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + + + + + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + + + + + Identifier for each phase. + + The value 0 is reserved for the unknown phase that represents the + null-model no sufficiently significant confirmation. In other words, + the phase_name is n/a, notIndexed. + + The phase identifier value has to match with the integer postfix of the + group name which represents that instance in a NeXus/HDF5 file, i.e. + if two phases were used e.g. 0 and 1, two instances of an + :ref:`NXcrystal_structure` named phase0 and phase1 + should be stored in the HDF5 file. + + + + + + Name of the phase/alias. + + If the phase_identifier is 0 and one would like to use the field + phase_name the value should be n/a. + + + + + Label for each atom position. + + + + + + + + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) <https://doi.org/10.1017/S1431927621012241>`_ + + + + + + + + + Atom positions. + + + + + + + + Reference to an instance of :ref:`NXcoordinate_system` + whereby the positions can be resolved. + + + + + + + Relative occupancy of the atom position. + + + + + + + + How many reflectors are distinguished. + + Value has to match value for symbol n_hkl. + + + + + + Miller indices :math:`(hkl)[uvw]` of the planes. + + The first triplet specify :math:`(hkl)` the second triplet :math:`[uvw]`. + Miller indices refer to the Cartesian right-handed coordinate system + of the unit cell. + + + + + + + + + Spacing between crystallographic planes as defined by field miller. + + + + + + + + Relative intensity of the signal for the plane. + + + + + + + + In case the :ref:`NXcrystal_structure` base class is used + with analyzed orientation maps this field stores how many scan points + of the map were identified as that phase. + + + + + + + diff --git a/contributed_definitions/NXcs_computer.nxdl.xml b/contributed_definitions/NXcs_computer.nxdl.xml new file mode 100644 index 0000000000..79a8accf15 --- /dev/null +++ b/contributed_definitions/NXcs_computer.nxdl.xml @@ -0,0 +1,80 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a set of computing nodes. + + + + Given name/alias to the computing system, e.g. MyDesktop. + + + + + Name of the operating system, e.g. Windows, Linux, Mac, Android. + + + + Version plus build number, commit hash, or description of an ever + persistent resource where the source code of the program and build + instructions can be found so that the program can be configured in + such a manner that the result file is ideally recreatable yielding + the same results. + + + + + + + Ideally a (globally) unique persistent identifier of the computer, i.e. + the Universally Unique Identifier (UUID) of the computing node. + + + + + + Details about (classical) processing units (CPUs) or a system thereof. + + + + + Details about coprocessor/graphic cards/accelerator units or a system thereof. + + + + + Details about the memory sub-system. + + + + + Details about the I/O sub-system. + + + diff --git a/contributed_definitions/NXcs_cpu.nxdl.xml b/contributed_definitions/NXcs_cpu.nxdl.xml new file mode 100644 index 0000000000..13357448b3 --- /dev/null +++ b/contributed_definitions/NXcs_cpu.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a central processing unit (CPU) of a computer. + + + + Given name of the CPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_cpu_obj.nxdl.xml b/contributed_definitions/NXcs_cpu_obj.nxdl.xml new file mode 100644 index 0000000000..8a23293212 --- /dev/null +++ b/contributed_definitions/NXcs_cpu_obj.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a (central) processing unit (C)PU of a computer. + + + + Given name of the CPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_cpu_sys.nxdl.xml b/contributed_definitions/NXcs_cpu_sys.nxdl.xml new file mode 100644 index 0000000000..7a05ae8403 --- /dev/null +++ b/contributed_definitions/NXcs_cpu_sys.nxdl.xml @@ -0,0 +1,48 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a system of classical central processing units. + + For coprocessor or graphic cards use :ref:`NXcs_gpu_sys` instead. + + + + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single CPU one + could describe using one instance of :ref:`NXcs_cpu_obj` inside one instance of + :ref:`NXcs_cpu_sys`. + A dual-socket server one could describe using two instances of :ref:`NXcs_cpu_obj` + inside one instance of :ref:`NXcs_cpu_sys`. + A server with two dual-socket server nodes one could describe + with the above group of one :ref:`NXcs_cpu_sys` into another :ref:`NXcs_cpu_sys`. + + + diff --git a/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml b/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml new file mode 100644 index 0000000000..60f3a1c3c5 --- /dev/null +++ b/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml @@ -0,0 +1,114 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of entries (e.g. number of points or objects). + + + + + Number of bits assumed for the container datatype used. + + + + + Length of mask considering the eventual need for padding. + + + + + Computer science base class for packing and unpacking booleans. + + This base class bookkeeps metadata to inform software about necessary modulo + operations to decode e.g. set membership of objects in sets which are encoded + as a packed array of boolean values. + + One use case is processing of object sets (point cloud data). When one applies + e.g. a spatial filter to a set of points to define which points are analyzed + and which not, one can store this information in a compact manner using an array + of boolean values. If the value is True the point is taken, otherwise the point + is not taken. + + The resulting boolean array will be filled with True and False in a manner + that is often arbitrary and in general case-dependent. + + Especially when the number of points is large, for instance several thousands + or more, some situations can be more efficiently stored if one would not store + the boolean array but just list the identifiers of the points taken. + + For example, if within a set of 1000 points only one point is taken, it would + take (naively) 4000 bits to store the array but only 32 bits to store e.g. the + ID of the single point that is taken. Of course the 4000 bit field is so + sparse that it could be compressed resulting also in a substantial reduction + of the storage demands. Therefore, boolean masks are useful in that + they store compact representation of set memberships. + + The number of encoded pieces of information is not necessarily + an integer multiple of the bit depth. + + + + Possibility to refer to which set this mask applies. + + If depends_on is not provided, it is assumed that the mask + applies to its direct parent. + + + + + Number of objects represented by the mask. + + + + + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + + + + + The content of the mask. If padding is used, padding bits have to be set to 0. + + + + + + + + Link to/or array of identifiers for the objects. The decoded mask is + interpreted consecutively, i.e. the first bit in the mask matches + to the first identifier, the second bit in the mask to the second + identifier and so on and so forth. Resolving of identifier follows + the conventions made for depends_on, so consult the also its description. + + + + + + diff --git a/contributed_definitions/NXcs_gpu.nxdl.xml b/contributed_definitions/NXcs_gpu.nxdl.xml new file mode 100644 index 0000000000..94adaf58ef --- /dev/null +++ b/contributed_definitions/NXcs_gpu.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a graphic processing unit (GPU) of a computer. + + + + Given name of the GPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_gpu_obj.nxdl.xml b/contributed_definitions/NXcs_gpu_obj.nxdl.xml new file mode 100644 index 0000000000..8353ca814c --- /dev/null +++ b/contributed_definitions/NXcs_gpu_obj.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a graphic processing unit (GPU) of a computer. + + + + Given name of the GPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_gpu_sys.nxdl.xml b/contributed_definitions/NXcs_gpu_sys.nxdl.xml new file mode 100644 index 0000000000..e7fedabd41 --- /dev/null +++ b/contributed_definitions/NXcs_gpu_sys.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a system of coprocessor or graphics processors. + + + + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single GPU one + could describe using one instance of :ref:`NXcs_gpu_obj` inside one instance of + :ref:`NXcs_gpu_sys`. + A desktop computer with two GPUs one could describe using two instances + of :ref:`NXcs_gpu_obj` inside one instance of :ref:`NXcs_gpu_sys`. + A GPU server like nowadays used for artificial intelligence + one could describe as a system with n instances of :ref:`NXcs_gpu_obj` + in one :ref:`NXcs_gpu_sys` or :ref:`NXcs_cpu_sys`. + + + diff --git a/contributed_definitions/NXcs_io_obj.nxdl.xml b/contributed_definitions/NXcs_io_obj.nxdl.xml new file mode 100644 index 0000000000..de28eb64ca --- /dev/null +++ b/contributed_definitions/NXcs_io_obj.nxdl.xml @@ -0,0 +1,55 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a storage object in an input/output system. + + + + Qualifier for the type of storage medium used. + + + + + + + + + + Total amount of data which the medium can hold. + + + + + + Given name to the I/O unit. + + + + diff --git a/contributed_definitions/NXcs_io_sys.nxdl.xml b/contributed_definitions/NXcs_io_sys.nxdl.xml new file mode 100644 index 0000000000..0caf528f04 --- /dev/null +++ b/contributed_definitions/NXcs_io_sys.nxdl.xml @@ -0,0 +1,38 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of system of a computer. + + In the same way how a hierarchy of instances of :ref:`NXcs_cpu_obj` or :ref:`NXcs_gpu_obj` + can be defined one can also define a hierarchy of :ref:`NXcs_mm_obj` and :ref:`NXcs_io_obj` + instances. + + + diff --git a/contributed_definitions/NXcs_mm_obj.nxdl.xml b/contributed_definitions/NXcs_mm_obj.nxdl.xml new file mode 100644 index 0000000000..4e69e64e1d --- /dev/null +++ b/contributed_definitions/NXcs_mm_obj.nxdl.xml @@ -0,0 +1,51 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a memory in a memory system. + + + + Qualifier for the type of random access memory. + + + + + + Total amount of data which the medium can hold. + + + + + + Given name to the I/O unit. + + + + diff --git a/contributed_definitions/NXcs_mm_sys.nxdl.xml b/contributed_definitions/NXcs_mm_sys.nxdl.xml new file mode 100644 index 0000000000..70037fbeaa --- /dev/null +++ b/contributed_definitions/NXcs_mm_sys.nxdl.xml @@ -0,0 +1,43 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a memory system of a computer. + + In the same way how a hierarchy of instances of :ref:`NXcs_cpu_obj` or :ref:`NXcs_gpu_obj` + can be defined one can also define a hierarchy of :ref:`NXcs_mm_obj` and :ref:`NXcs_io_obj` + instances. + + + + How much physical memory does the system provide. + + + + diff --git a/contributed_definitions/NXcs_prng.nxdl.xml b/contributed_definitions/NXcs_prng.nxdl.xml new file mode 100644 index 0000000000..911faf63c6 --- /dev/null +++ b/contributed_definitions/NXcs_prng.nxdl.xml @@ -0,0 +1,83 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of pseudo-random number generator. + + The purpose of this base class is to identify if exactly the same sequence + can be reproduced, like for a PRNG or not (for a true physically random source). + + + + Physical approach or algorithm whereby random numbers are generated. + + Different approaches for generating random numbers with a computer exists. + Some use a dedicated physical device whose the state is unpredictable + (physically). Some use a strategy of mangling information from the system + clock. Also in this case the sequence is not reproducible without having + additional pieces of information. + + In most cases though so-called pseudo-random number generator (PRNG) + algorithms are used. These yield a deterministic sequence of practically + randomly appearing numbers. These algorithms differ in their quality in + how close the resulting sequences are random, i.e. sequentially + uncorrelated. Nowadays one of the most commonly used algorithm is the + MersenneTwister (mt19937). + + + + + + + + + + + Name of the PRNG implementation and version. If such information is not + available or if the PRNG type was set to other the DOI to the publication + or the source code should be given. + + + + + Parameter of the PRNG controlling its initialization + and thus controlling the specific sequence generated. + + + + + Number of initial draws from the PRNG after its initialized with the seed. + These initial draws are typically discarded in an effort to equilibrate the + sequence. If no warmup was performed or if warmup procedures are unclear, + users should set the value to zero. + + + + diff --git a/contributed_definitions/NXcs_profiling.nxdl.xml b/contributed_definitions/NXcs_profiling.nxdl.xml new file mode 100644 index 0000000000..d37224f9cb --- /dev/null +++ b/contributed_definitions/NXcs_profiling.nxdl.xml @@ -0,0 +1,149 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description for performance and profiling data of an application. + + Performance monitoring and benchmarking of software is a task where questions + can be asked at various levels of detail. In general, there are three main + contributions to performance: + + * Hardware capabilities and configuration + * Software configuration and capabilities + * Dynamic effects of the system in operation and the system working together + with eventually multiple computers, especially when these have to exchange + information across a network and these are used usually by multiple users. + + At the most basic level users may wish to document how long e.g. a data + analysis with a scientific software (app) took. + A frequent idea is here to answer practical questions like how critical is the + effect on the workflow of the scientists, i.e. is the analysis possible in + a few seconds or would it take days if I were to run this analysis on a + comparable machine? + For this more qualitative performance monitoring, mainly the order of + magnitude is relevant, as well as how this was achieved using parallelization + (i.e. reporting the number of CPU and GPU resources used, the number of + processes and threads configured, and providing basic details about the computer). + + At more advanced levels benchmarks may go as deep as detailed temporal tracking + of individual processor instructions, their relation to other instructions, the + state of call stacks; in short eventually the entire app execution history + and hardware state history. Such analyses are mainly used for performance + optimization, i.e. by software and hardware developers as well as for + tracking bugs. Specialized software exists which documents such performance + data in specifically-formatted event log files or databases. + + This base class cannot and should not replace these specific solutions for now. + Instead, the intention of the base class is to serve scientists at the + basic level to enable simple monitoring of performance data and log profiling + data of key algorithmic steps or parts of computational workflows, so that + these pieces of information can guide users which order of magnitude differences + should be expected or not. + + Developers of application definitions should add additional fields and + references to e.g. more detailed performance data to which they wish to link + the metadata in this base class. + + + + + Path to the directory from which the tool was called. + + + + + Command line call with arguments if applicable. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the app was started. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the app terminated or crashed. + + + + + Wall-clock time how long the app execution took. This may be in principle + end_time minus start_time; however usage of eventually more precise timers + may warrant to use a finer temporal discretization, + and thus demands a more precise record of the wall-clock time. + + + + + Qualifier which specifies with how many nominal processes the app was + invoked. The main idea behind this field e.g. for apps which use e.g. MPI + (Message Passing Interface) parallelization is to communicate + how many processes were used. + + For sequentially running apps number_of_processes and number_of_threads + is 1. If the app uses exclusively GPU parallelization number_of_gpus + can be larger than 1. If no GPU is used number_of_gpus is 0 even though + the hardware may have GPUs installed, thus indicating these were not + used though. + + + + + Qualifier how many nominal threads were used at runtime. + Specifically here the maximum number of threads used for the + high-level threading library used (e.g. OMP_NUM_THREADS), posix. + + + + + Qualifier with how many nominal GPUs the app was invoked at runtime. + + + + + + A collection with one or more computing nodes each with own resources. + This can be as simple as a laptop or the nodes of a cluster computer. + + + + + A collection of individual profiling event data which detail e.g. how + much time the app took for certain computational steps and/or how much + memory was consumed during these operations. + + + + diff --git a/contributed_definitions/NXcs_profiling_event.nxdl.xml b/contributed_definitions/NXcs_profiling_event.nxdl.xml new file mode 100644 index 0000000000..9da91f9c04 --- /dev/null +++ b/contributed_definitions/NXcs_profiling_event.nxdl.xml @@ -0,0 +1,98 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of processes. + + + + + Computer science description of a profiling event. + + + + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking started. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking ended. + + + + + Free-text description what was monitored/executed during the event. + + + + + Wall-clock time how long the event took. + + This may be in principle end_time minus start_time; however usage of + eventually more precise timers may warrant to use a finer temporal + discretization, and thus demand for a more precise record of the + wall-clock time. + + Elapsed time may contain time portions where resources were idling. + + + + + Number of processes used (max) during the execution of this event. + + + + + Number of threads used (max) during the execution of this event. + + + + + Number of GPUs used (max) during the execution of this event. + + + + + Maximum amount of virtual memory allocated per process during the event. + + + + + + + + Maximum amount of resident memory allocated per process during the event. + + + + + + diff --git a/contributed_definitions/NXdac.nxdl.xml b/contributed_definitions/NXdac.nxdl.xml new file mode 100644 index 0000000000..b73dc7abee --- /dev/null +++ b/contributed_definitions/NXdac.nxdl.xml @@ -0,0 +1,38 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Digital-to-analog converter component/integrated circuit. + + + + TBD. + + + diff --git a/contributed_definitions/NXdata_mpes.nxdl.xml b/contributed_definitions/NXdata_mpes.nxdl.xml new file mode 100644 index 0000000000..3649da88c5 --- /dev/null +++ b/contributed_definitions/NXdata_mpes.nxdl.xml @@ -0,0 +1,150 @@ + + + + + + :ref:`NXdata_mpes` describes the plottable data and related dimension scales in MPES + experiments. + + It extends the NXdata class and provides a glossary of explicitly named axis names + which are typical for MPES data. + + + + Calibrated energy axis. + + This could be a link to either + /entry/process/energy_calibration/calibrated_axis or + /entry/process/energy_correction/calibrated_axis. + + + + The energy can be either stored as kinetic or as binding energy. + + + + + Calibrated kinetic energy axis. + + This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. + + .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + + + + + Calibrated binding energy axis. + + This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. + + .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + + + + + + + + + + Calibrated x axis in k-space. + Units are 1/Angström. + + + + + + + Calibrated y axis in k-space. + Units are 1/Angström + + + + + + + Calibrated z axis in k-space. + Units are 1/Angström. + + + + + + + Fast-axis angular coordinate (or second slow axis if angularly integrated). + + + + + + + Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in + 2 dimensions) + + + + + + + Fast-axis spatial coordinate (or second slow axis if spatially integrated) + + + + + + + Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in + 2 dimensions) + + + + + + + Calibrated delay time. + + + + + + + Linear polarization angle of the incoming or outgoing beam. + + Could be a link to /entry/instrument/beam/incident_polarization_angle or + /entry/instrument/beam/final_polarization_angle if they exist. + + + + + + + Ellipticity of the incoming or outgoing beam. + + Can be any of linear polarization angle (degrees), ellipticity (arb. units). + Could be a link to /entry/instrument/beam/incident_ellipticity or + /entry/instrument/beam/final_ellipticity if they exist. + + + + + diff --git a/contributed_definitions/NXdata_mpes_detector.nxdl.xml b/contributed_definitions/NXdata_mpes_detector.nxdl.xml new file mode 100644 index 0000000000..c681b95425 --- /dev/null +++ b/contributed_definitions/NXdata_mpes_detector.nxdl.xml @@ -0,0 +1,189 @@ + + + + + + :ref:`NXdata_mpes_detector` describes the plottable data and related dimension scales + for raw detector data in MPES experiments. + + It extends the NXdata class and provides a glossary of explicitly named axis names + which are typical for raw MPES data. + + + + + + + + + Raw data before calibration. + + + + + Detector pixel in x direction. + + + + + + + Detector pixel in y direction. + + + + + + + (Un)calibrated energy axis. + + + + The energy can be either stored as kinetic or as binding energy. + + + + + (Un)calibrated kinetic energy axis. + + This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. + + .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + + + + + (Un)calibrated binding energy axis. + + This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. + + .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + + + + + + + + + + (Un)calibrated x axis in k-space. + Units are 1/Angström. + + + + + + + (Un)calibrated y axis in k-space. + Units are 1/Angström + + + + + + + (Un)calibrated z axis in k-space. + Units are 1/Angström. + + + + + + + Fast-axis angular coordinate (or second slow axis if angularly integrated). + + + + + + + Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in two + dimensions) + + + + + + + Fast-axis spatial coordinate (or second slow axis if spatially integrated) + + + + + + + Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in two + dimensions) + + + + + + + + Total time of flight + + + + + + + Time-of-flight values, analog-to-digital converted. + + + + + + + (Un)calibrated delay time. + + + + + + + Linear polarization angle of the incoming or outgoing beam. + + + + + + + Ellipticity of the incoming or outgoing beam. + + + + + + + Describes an axis which is coming from outside the detectors scope. + + Think of a detector just being triggered for readout by the rest of the experimental + setup - it would just know that it collected N images, which would flatten the external + parameters to one axis, too. + This can then be linked, e.g. with NXcalibration, to the appropriate fields in the instrument + and write it to the top-level NXdata. + + + diff --git a/contributed_definitions/NXdeflector.nxdl.xml b/contributed_definitions/NXdeflector.nxdl.xml index 1af741055d..833acf2a4b 100644 --- a/contributed_definitions/NXdeflector.nxdl.xml +++ b/contributed_definitions/NXdeflector.nxdl.xml @@ -1,12 +1,33 @@ - + - + + Deflectors as they are used e.g. in an electron analyser. - Qualitative type of deflector with respect to the number of pole pieces + Qualitative type of deflector with respect to the number of pole pieces. @@ -21,27 +42,17 @@ identifiers use respective manufacturer fields. - - - Name of the manufacturer who built/constructed the deflector. - - - - - Hardware name, hash identifier, or serial number that was given by the - manufacturer to identify the deflector. - - + - Ideally an identifier, persistent link, or free text which gives further details - about the deflector. + Ideally an identifier, persistent link, or free text which gives + further details about the deflector. - Excitation voltage of the deflector. For dipoles it is a single number. For - higher orders, it is an array. + Excitation voltage of the deflector. For dipoles it is a single number. + For higher order multipoles, it is an array. @@ -50,17 +61,18 @@ higher orders, it is an array. - + Specifies the position of the deflector by pointing to the last transformation in the transformation chain in the NXtransformations group. - + + Collection of axis-based translations and rotations to describe the location and geometry of the deflector as a component in the instrument. Conventions from the - NXtransformations base class are used. In principle, the McStas coordinate + :ref:`NXtransformations` base class are used. In principle, the McStas coordinate system is used. The first transformation has to point either to another component of the system or . (for pointing to the reference frame) to relate it relative to the experimental setup. Typically, the components of a system should diff --git a/contributed_definitions/NXdelocalization.nxdl.xml b/contributed_definitions/NXdelocalization.nxdl.xml new file mode 100644 index 0000000000..c5b8558746 --- /dev/null +++ b/contributed_definitions/NXdelocalization.nxdl.xml @@ -0,0 +1,146 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of points/objects. + + + + + Number of mark data per point/object. + + + + + Number of atoms in the whitelist. + + + + + Number of isotopes in the whitelist. + + + + + Base class to describe the delocalization of point-like objects on a grid. + + Such a procedure is for instance used in image processing and e.g. atom probe + microscopy (APM) to discretize a point cloud onto a grid to enable e.g. + computing of point density, composition, or concentration values, obtain + scalar fields, and compute gradients of these fields. + + + + Reference or link to the grid on which the delocalization is applied. + + + + + Reference or link to the points which are delocalized on the grid. + + + + + + The weighting model specifies how mark data are mapped to a weight per point. + For atom probe microscopy (APM) as an example, different models are used which + account differently for the multiplicity of an ion/atom: + + * default, points all get the same weight 1.; + for APM this is equivalent to ion species + * atomic_decomposition, points get as much weight as they have atoms + of a type in element_whitelist, + * isotope_decomposition, points get as much weight as they have + isotopes of a type in isotope_whitelist. + + This description shows an example that could be reinterpreted for + similar such data processing steps in other fields of science. + + + + + + + + + + + A list of elements (via proton number) to consider for the atomic_decomposition + weighting model. Elements must exist in the periodic table of elements. + + + + + + + + A list of isotopes to consider for the isotope_decomposition weighting model. + Isotopes must exist in the nuclid table. Entries in the fastest changing + dimension should be the pair of proton (first entry) and neutron number + (second entry). + + + + + + + + + Attribute data for each member of the point cloud. For APM these are the + ion species labels generated via ranging. The number of mark data per + point is 1 in the case for atom probe. + + + + + + + + + Weighting factor with which the integrated intensity per grid cell is + multiplied specifically for each point. For APM the weight are positive + integer values, specifically the multiplicity of the ion, + according to the details of the weighting_model. + + + diff --git a/contributed_definitions/NXdispersion.nxdl.xml b/contributed_definitions/NXdispersion.nxdl.xml new file mode 100644 index 0000000000..3351b27465 --- /dev/null +++ b/contributed_definitions/NXdispersion.nxdl.xml @@ -0,0 +1,37 @@ + + + + + + A dispersion denoting a sum of different dispersions. + All NXdispersion_table and NXdispersion_function groups will be added together + to form a single dispersion. + + + + The name of the composite model. + + + + + diff --git a/contributed_definitions/NXdispersion_function.nxdl.xml b/contributed_definitions/NXdispersion_function.nxdl.xml new file mode 100644 index 0000000000..d056b35b08 --- /dev/null +++ b/contributed_definitions/NXdispersion_function.nxdl.xml @@ -0,0 +1,128 @@ + + + + + + + + The number of repetitions for the repeated parameters + + + + + This describes a dispersion function for a material or layer + + + + The name of this dispersion model. + + + + + This should be a python parsable function. + Here we should provide which keywords are available + and a BNF of valid grammar. + + + + + The sign convention being used (n + or - ik) + + + + + + + + + The identifier used to represent energy + in the formula. It is recommended to use `E`. + + + + + The minimum energy value at which this formula is valid. + + + + + The maximum energy value at which this formula is valid. + + + + + The energy unit used in the formula. + The field value is a scaling factor for the units attribute. + It is recommeded to set the field value to 1 and carry all the unit + scaling information in the units attribute. + + + + + The identifier useed to represent wavelength + in the formula. It is recommended to use `lambda`. + + + + + The wavelength unit used in the formula. + The field value is a scaling factor for the units attribute. + It is recommeded to set the field value to 1 and carry all the unit + scaling information in the units attribute. + + + + + The minimum wavelength value at which this formula is valid. + + + + + The maximum wavelength value at which this formula is valid. + + + + + Which representation does the formula evaluate to. + This may either be n for refractive index or eps for dielectric function. + The appropriate token is then to be used inside the formula. + + + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXdispersion_repeated_parameter.nxdl.xml b/contributed_definitions/NXdispersion_repeated_parameter.nxdl.xml new file mode 100644 index 0000000000..e2b8dcfce9 --- /dev/null +++ b/contributed_definitions/NXdispersion_repeated_parameter.nxdl.xml @@ -0,0 +1,65 @@ + + + + + + + + The number of parameter repetitions + + + + + A repeated parameter for a dispersion function + + + + The name of the parameter + + + + + A description of what this parameter represents + + + + + A unit array associating a unit with each parameter. + The first element should be equal to values/@unit. + The values should be SI interpretable standard units + with common prefixes (e.g. mikro, nano etc.) or their + short-hand notation (e.g. nm, mm, kHz etc.). + + + + + + + + The value of the parameter + + + + + + diff --git a/contributed_definitions/NXdispersion_single_parameter.nxdl.xml b/contributed_definitions/NXdispersion_single_parameter.nxdl.xml new file mode 100644 index 0000000000..f8c45ba098 --- /dev/null +++ b/contributed_definitions/NXdispersion_single_parameter.nxdl.xml @@ -0,0 +1,43 @@ + + + + + + A single parameter for a dispersion function + + + + The name of the parameter + + + + + A description of what this parameter represents + + + + + The value of the parameter + + + diff --git a/contributed_definitions/NXdispersion_table.nxdl.xml b/contributed_definitions/NXdispersion_table.nxdl.xml new file mode 100644 index 0000000000..9cca5ae70d --- /dev/null +++ b/contributed_definitions/NXdispersion_table.nxdl.xml @@ -0,0 +1,88 @@ + + + + + + + The symbols in this schema to denote the dimensions + + + + The number of energy and dielectric function points + + + + + A dispersion table denoting energy, dielectric function tabulated values. + + + + The name of this dispersion model. + + + + + The sign convention being used (n + or - ik) + + + + + + + + + The wavelength array of the tabulated dataset. + This is essentially a duplicate of the energy field. + There should be one or both of them present. + + + + + + + + The energy array of the tabulated dataset. + This is essentially a duplicate of the wavelength field. + There should be one or both of them present. + + + + + + + + The refractive index array of the tabulated dataset. + + + + + + + + The dielectric function of the tabulated dataset. + + + + + + diff --git a/contributed_definitions/NXdispersive_material.nxdl.xml b/contributed_definitions/NXdispersive_material.nxdl.xml new file mode 100644 index 0000000000..452c384824 --- /dev/null +++ b/contributed_definitions/NXdispersive_material.nxdl.xml @@ -0,0 +1,225 @@ + + + + + + NXdispersion + + + + + An application definition for a dispersive material. + + + + Version number to identify which definition of this application definition was + used for this entry/data. + + + + + URL where to find further material (documentation, examples) relevant to the + application definition + + + + + + + + + + + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + + + + + The colloquial name of the material, e.g. graphite or diamond for carbon. + + + + + The phase of the material + + + + + + + + + + + Additional information about the phase if the + material phase is other. + + + + + This field may be used to denote additional phase information, + such as crystalin phase of a crystal (e.g. 4H or 6H for SiC) or + if a measurement was done on a thin film or bulk material. + + + + + + Denotes whether the dispersion is calculated or derived from an experiment + + + + + + + + + + A text description of this reference, e.g. + `E. Example et al, The mighty example, An example journal 50 (2023), 100` + + + + + + + The dispersion along the optical axis of the material. + This should be the only dispersion available for isotropic materials. + For uniaxial materials this denotes the ordinary axis. + For biaxial materials this denotes the x axis or epsilon 11 tensor element + of the diagionalized permittivity tensor. + + + + The name of this dispersion model. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This should only be filled for biaxial materials. + It denotes the epsilon 22 direction of the diagionalized + permittivity tensor. + + + + The name of this dispersion model. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This should only be filled for uniaxial or biaxial materials. + For uniaxial materials this denotes the extraordinary axis. + For biaxial materials this denotes the epsilon 33 tensor element + of the diagionalized perimittivty tensor. + + + + The name of this dispersion model. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXdistortion.nxdl.xml b/contributed_definitions/NXdistortion.nxdl.xml index 5189d5e3b0..08517614a8 100644 --- a/contributed_definitions/NXdistortion.nxdl.xml +++ b/contributed_definitions/NXdistortion.nxdl.xml @@ -1,6 +1,27 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays @@ -37,11 +58,10 @@ For `symmetry-guided distortion correction`_, - where a pattern of features is mapped to the regular geometric structure - expected from the symmetry. Here we record the number of elementary symmetry - operations. - - .. _symmetry-guided distortion correction: https://www.sciencedirect.com/science/article/abs/pii/S0304399118303474?via%3Dihub + where a pattern of features is mapped to the regular geometric structure expected + from the symmetry. Here we record the number of elementary symmetry operations. + + .. _symmetry-guided distortion correction: https://www.sciencedirect.com/science/article/abs/pii/S0304399118303474?via%3Dihub diff --git a/contributed_definitions/NXebeam_column.nxdl.xml b/contributed_definitions/NXebeam_column.nxdl.xml index c31a227224..f3ee7a99bc 100644 --- a/contributed_definitions/NXebeam_column.nxdl.xml +++ b/contributed_definitions/NXebeam_column.nxdl.xml @@ -1,11 +1,39 @@ - + - + + + + - Container for components to form a controlled electron beam. + Base class for a set of components providing a controllable electron beam. - - + + + The source which creates the electron beam. @@ -14,8 +42,8 @@ Given name/alias. - - + + Voltage relevant to compute the energy of the electrons immediately after they left the gun. @@ -48,35 +76,34 @@ Material of which the emitter is build, e.g. the filament material. + Ideally, a (globally) unique persistent identifier, link, or text to a resource which gives further details. + - Affine transformation which detail the arrangement in the - microscope relative to the optical axis and beam path. + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. - - - - A sensor used to monitor an external or internal condition. - - + + - Individual ocharacterization results for the position, shape, + Individual characterization results for the position, shape, and characteristics of the electron beam. - NXtransformations should be used to specify the location - of the position at which the beam was probed. + :ref:`NXtransformations` should be used to specify the location + of the position at which the beam was probed. diff --git a/contributed_definitions/NXelectron_level.nxdl.xml b/contributed_definitions/NXelectron_level.nxdl.xml new file mode 100644 index 0000000000..b39e0fd721 --- /dev/null +++ b/contributed_definitions/NXelectron_level.nxdl.xml @@ -0,0 +1,918 @@ + + + + + + Electronic level probed in X-ray spectroscopy or resonance experiments. + + + + Symbol of the chemical element. + + For each, the atomic number, common English name, and standard atomic weight are also given. + + + + + Z=1, name="hydrogen", standard_atomic_weight=1.0078 + + + + + Z=2, name="helium", standard_atomic_weight=4.0026 + + + + + Z=3, name="lithium", standard_atomic_weight=6.94 + + + + + Z=4, name="beryllium", standard_atomic_weight=9.0122 + + + + + Z=5, name="boron", standard_atomic_weight=10.81 + + + + + Z=6, name="carbon", standard_atomic_weight=12.011 + + + + + Z=7, name="nitrogen", standard_atomic_weight=14.007 + + + + + Z=8, name="oxygen", standard_atomic_weight=15.999 + + + + + Z=9, name="fluorine", standard_atomic_weight=18.9984 + + + + + Z=10, name="neon", standard_atomic_weight=20.1797 + + + + + Z=11, name="sodium", standard_atomic_weight=22.9898 + + + + + Z=12, name="magnesium", standard_atomic_weight=24.305 + + + + + Z=13, name="aluminum", standard_atomic_weight=26.9815 + + + + + Z=14, name="silicon", standard_atomic_weight=28.085 + + + + + Z=15, name="phosphorus", standard_atomic_weight=30.9738 + + + + + Z=16, name="sulfur", standard_atomic_weight=32.06 + + + + + Z=17, name="chlorine", standard_atomic_weight=35.453 + + + + + Z=18, name="argon", standard_atomic_weight=39.948 + + + + + Z=19, name="potassium", standard_atomic_weight=39.0983 + + + + + Z=20, name="calcium", standard_atomic_weight=40.078 + + + + + Z=21, name="scandium", standard_atomic_weight=44.9559 + + + + + Z=22, name="titanium", standard_atomic_weight=47.867 + + + + + Z=23, name="vanadium", standard_atomic_weight=50.9415 + + + + + Z=24, name="chromium", standard_atomic_weight=51.996 + + + + + Z=25, name="manganese", standard_atomic_weight=54.938 + + + + + Z=26, name="iron", standard_atomic_weight=55.845 + + + + + Z=27, name="cobalt", standard_atomic_weight=58.9332 + + + + + Z=28, name="nickel", standard_atomic_weight=58.6934 + + + + + Z=29, name="copper", standard_atomic_weight=63.546 + + + + + Z=30, name="zinc", standard_atomic_weight=65.38 + + + + + Z=31, name="gallium", standard_atomic_weight=69.72 + + + + + Z=32, name="germanium", standard_atomic_weight=72.63 + + + + + Z=33, name="arsenic", standard_atomic_weight=74.9216 + + + + + Z=34, name="selenium", standard_atomic_weight=78.971 + + + + + Z=35, name="bromine", standard_atomic_weight=79.904 + + + + + Z=36, name="krypton", standard_atomic_weight=83.798 + + + + + Z=37, name="rubidium", standard_atomic_weight=85.4678 + + + + + Z=38, name="strontium", standard_atomic_weight=87.62 + + + + + Z=39, name="yttrium", standard_atomic_weight=88.9058 + + + + + Z=40, name="zirconium", standard_atomic_weight=91.224 + + + + + Z=41, name="niobium", standard_atomic_weight=92.9064 + + + + + Z=42, name="molybdenum", standard_atomic_weight=95.95 + + + + + Z=43, name="technetium", standard_atomic_weight=97.907 + + + + + Z=44, name="ruthenium", standard_atomic_weight=101.07 + + + + + Z=45, name="rhodium", standard_atomic_weight=102.906 + + + + + Z=46, name="palladium", standard_atomic_weight=106.42 + + + + + Z=47, name="silver", standard_atomic_weight=107.868 + + + + + Z=48, name="cadmium", standard_atomic_weight=112.414 + + + + + Z=49, name="indium", standard_atomic_weight=114.818 + + + + + Z=50, name="tin", standard_atomic_weight=118.71 + + + + + Z=51, name="antimony", standard_atomic_weight=121.76 + + + + + Z=52, name="tellurium", standard_atomic_weight=127.6 + + + + + Z=53, name="iodine", standard_atomic_weight=126.905 + + + + + Z=54, name="xenon", standard_atomic_weight=131.293 + + + + + Z=55, name="cesium", standard_atomic_weight=132.905 + + + + + Z=56, name="barium", standard_atomic_weight=137.327 + + + + + Z=57, name="lanthanum", standard_atomic_weight=138.905 + + + + + Z=58, name="cerium", standard_atomic_weight=140.116 + + + + + Z=59, name="praseodymium", standard_atomic_weight=140.908 + + + + + Z=60, name="neodymium", standard_atomic_weight=144.242 + + + + + Z=61, name="promethium", standard_atomic_weight=145.0 + + + + + Z=62, name="samarium", standard_atomic_weight=150.36 + + + + + Z=63, name="europium", standard_atomic_weight=151.96 + + + + + Z=64, name="gadolinium", standard_atomic_weight=157.25 + + + + + Z=65, name="terbium", standard_atomic_weight=158.925 + + + + + Z=66, name="dysprosium", standard_atomic_weight=162.5 + + + + + Z=67, name="holmium", standard_atomic_weight=164.93 + + + + + Z=68, name="erbium", standard_atomic_weight=167.259 + + + + + Z=69, name="thulium", standard_atomic_weight=168.934 + + + + + Z=70, name="ytterbium", standard_atomic_weight=173.045 + + + + + Z=71, name="lutetium", standard_atomic_weight=174.967 + + + + + Z=72, name="hafnium", standard_atomic_weight=178.49 + + + + + Z=73, name="tantalum", standard_atomic_weight=180.948 + + + + + Z=74, name="tungsten", standard_atomic_weight=183.84 + + + + + Z=75, name="rhenium", standard_atomic_weight=186.207 + + + + + Z=76, name="osmium", standard_atomic_weight=190.23 + + + + + Z=77, name="iridium", standard_atomic_weight=192.217 + + + + + Z=78, name="platinum", standard_atomic_weight=195.084 + + + + + Z=79, name="gold", standard_atomic_weight=196.967 + + + + + Z=80, name="mercury", standard_atomic_weight=200.592 + + + + + Z=81, name="thallium", standard_atomic_weight=204.383 + + + + + Z=82, name="lead", standard_atomic_weight=207.2 + + + + + Z=83, name="bismuth", standard_atomic_weight=208.98 + + + + + Z=84, name="polonium", standard_atomic_weight=209.0 + + + + + Z=85, name="astatine", standard_atomic_weight=210.0 + + + + + Z=86, name="radon", standard_atomic_weight=222.0 + + + + + Z=87, name="francium", standard_atomic_weight=223.0 + + + + + Z=88, name="radium", standard_atomic_weight=226.0 + + + + + Z=89, name="actinium", standard_atomic_weight=227.0 + + + + + Z=90, name="thorium", standard_atomic_weight=232.038 + + + + + Z=91, name="protactinium", standard_atomic_weight=231.036 + + + + + Z=92, name="uranium", standard_atomic_weight=238.029 + + + + + Z=93, name="neptunium", standard_atomic_weight=237.048 + + + + + Z=94, name="plutonium", standard_atomic_weight=239.052 + + + + + Z=95, name="americium", standard_atomic_weight=243.0 + + + + + Z=96, name="curium", standard_atomic_weight=247.0 + + + + + Z=97, name="berkelium", standard_atomic_weight=247.0 + + + + + Z=98, name="californium", standard_atomic_weight=251.0 + + + + + Z=99, name="einsteinium", standard_atomic_weight=252 + + + + + Z=100, name="fermium", standard_atomic_weight=257 + + + + + Z=101, name="mendelevium", standard_atomic_weight=258 + + + + + Z=102, name="nobelium", standard_atomic_weight=259 + + + + + Z=103, name="lawrencium", standard_atomic_weight=266 + + + + + Z=104, name="rutherfordium", standard_atomic_weight=267 + + + + + Z=105, name="dubnium", standard_atomic_weight=268 + + + + + Z=106, name="seaborgium", standard_atomic_weight=269 + + + + + Z=107, name="bohrium", standard_atomic_weight=270 + + + + + Z=108, name="hassium", standard_atomic_weight=269 + + + + + Z=109, name="meitnerium", standard_atomic_weight=278 + + + + + Z=110, name="darmstadtium", standard_atomic_weight=281 + + + + + Z=111, name="roentgenium", standard_atomic_weight=282 + + + + + Z=112, name="copernicium", standard_atomic_weight=285 + + + + + Z=113, name="nihonium", standard_atomic_weight=286 + + + + + Z=114, name="flerovium", standard_atomic_weight=289 + + + + + Z=115, name="moscovium", standard_atomic_weight=290 + + + + + Z=116, name="livermorium", standard_atomic_weight=293 + + + + + Z=117, name="tennessine", standard_atomic_weight=294 + + + + + Z=118, name="oganesson", standard_atomic_weight=294 + + + + + + + IUPAC symbol of the electronic level. + For each level, the electronic orbital configuration is also given + + For reference, see Jenkins, R., Manne, R., Robin, R., & Senemaud, C. (1991). + IUPAC—nomenclature system for x-ray spectroscopy. X-Ray Spectrometry, 20(3), 149-155. + + + + + same as 1s in level_xray + + + + + 2s + + + + + 2p_{1/2} + + + + + 2p_{3/2} + + + + + 3s + + + + + 3p_{1/2} + + + + + 3p_{3/2} + + + + + 3d_{3/2} + + + + + 3d_{5/2} + + + + + 4s + + + + + 4p_{1/2} + + + + + 4p_{3/2} + + + + + 4d_{3/2} + + + + + 4d_{5/2} + + + + + 4f_{5/2} + + + + + 4f_{7/2} + + + + + 5s + + + + + 5p_{1/2} + + + + + 5p_{3/2} + + + + + 5d_{3/2} + + + + + 5d_{5/2} + + + + + 5f_{5/2} + + + + + 5f_{7/2} + + + + + 6s + + + + + 6p_{1/2} + + + + + 6p_{3/2} + + + + + + + Electronic orbital configuration of the electronic level. + + + + + same as K in level_xray + + + + + L1 + + + + + L3 + + + + + M1 + + + + + M2 + + + + + M3 + + + + + M4 + + + + + M5 + + + + + N1 + + + + + N2 + + + + + N3 + + + + + N4 + + + + + N5 + + + + + N6 + + + + + N7 + + + + + O1 + + + + + O2 + + + + + O3 + + + + + O4 + + + + + O5 + + + + + O6 + + + + + O7 + + + + + P1 + + + + + P2 + + + + + P3 + + + + + + + description of X-ray electronic level + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + diff --git a/contributed_definitions/NXelectronanalyser.nxdl.xml b/contributed_definitions/NXelectronanalyser.nxdl.xml index c08d6649f7..81e46dff06 100644 --- a/contributed_definitions/NXelectronanalyser.nxdl.xml +++ b/contributed_definitions/NXelectronanalyser.nxdl.xml @@ -1,28 +1,58 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays - Number of fast axes (axes acquired symultaneously, without scanning a - pysical quantity) + Number of fast axes (axes acquired simultaneously, without scanning a + physical quantity) - Number of slow axes (axes acquired scanning a pysical quantity) + Number of slow axes (axes acquired scanning a physical quantity) + + + + + Number of data points in the transmission function. - Subclass of NXinstrument to describe a photoelectron analyser. + Basic class for describing a electron analyzer. + + This concept is related to term `12.59`_ of the ISO 18115-1:2023 standard. + + .. _12.59: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.59 - Free text description of the type of the detector + Free text description of the type of the detector @@ -35,26 +65,92 @@ - + - Energy resolution of the electron analyser (FWHM of gaussian broadening) + Work function of the electron analyser. + + The work function of a uniform surface of a conductor is the minimum energy required to remove + an electron from the interior of the solid to a vacuum level immediately outside the solid surface. + + The kinetic energy :math:`E_K` of a photoelectron emitted from an energy-level with binding energy + :math:`E_B` below the Fermi level is given by :math:`E_K = h\nu - E_B - W = h\nu - E_B - e \phi_{\mathrm{sample}}`. + Here, :math:`W = e \phi_{\mathrm{sample}}` is the work function of the sample surface (with the potential difference :math:`\phi_{\mathrm{sample}}` + between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the vacuum just outside the surface). + + In PES measurements, the sample and the spectrometer (with work function :math:`\phi_{\mathrm{spectr.}}`) + are electrically connected and therefore their Fermi levels are aligned. Due to the difference in local + vacuum level between the sample and spectrometer, there exists an electric potential difference (contact potential) + :math:`\Delta\phi = \phi_{\mathrm{sample}} - \phi_{\mathrm{spectr.}}`. The measured kinetic energy of + a photoelectron in PES is therefore given by + :math:`E_K^{\mathrm{meas.}} = h\nu - E_B + \Delta \phi = h\nu - E_B - e \phi_{\mathrm{spectr.}}`. + As a result, the measured kinetic energy :math:`E_K^{\mathrm{meas.}}` of a photoelectron is `independent` + of the sample work function. Nonetheless, the work function :math:`\phi_s` needs to be known to + accurately determine the binding energy scale. - + - Momentum resolution of the electron analyser (FWHM) + Energy range of the voltage supplies. This influences the noise of the supplies, + and thereby the energy resolution. - + + + Energy resolution of the analyser with the current setting. May be linked from an + NXcalibration. + + This concept is related to term `10.24`_ of the ISO 18115-1:2023 standard. + + .. _10.24: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 + + + + + + + + + + + + Momentum resolution of the electron analyser (FWHM) + + + + + + + + + + Angular resolution of the electron analyser (FWHM) - - + + + + + + + + + Spatial resolution of the electron analyser (Airy disk radius) + + This concept is related to term `10.15 ff.`_ of the ISO 18115-1:2023 standard. + + .. _10.15 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.15 - + + + + + + + + List of the axes that are acquired simultaneously by the detector. @@ -62,12 +158,12 @@ Other variables such as temperature, manipulator angles etc. are labeled as fast or slow in the data. .. csv-table:: Examples - :header: "Mode", "fast_axes", "slow_axes" + :header: "Mode", "fast_axes", "slow_axes" - Hemispherical in ARPES mode, "['energy', 'kx']","" - "Hemispherical with channeltron, sweeping energy mode", "", [\"energy\"] - "Tof", "['energy', 'kx', 'ky']","" - "Momentum microscope, spin-resolved", "['energy', 'kx', 'ky']", "['spin up-down', 'spin left-right']" + Hemispherical in ARPES mode, "['energy', 'kx']","" + "Hemispherical with channeltron, sweeping energy mode", "", [\"energy\"] + "Tof", "['energy', 'kx', 'ky']","" + "Momentum microscope, spin-resolved", "['energy', 'kx', 'ky']", "['spin up-down', 'spin left-right']" Axes may be less abstract than this, i.e. ['detector_x', 'detector_y']. If energy_scan_mode=sweep, fast_axes: ['energy', 'kx']; slow_axes: ['energy'] is allowed. @@ -85,22 +181,67 @@ + + + Transmission function of the electron analyser. + + The transmission function (TF) specifies the detection efficiency per solid angle for electrons of + different kinetic energy passing through the electron analyser. It depends on the spectrometer + geometry as well as operation settings such as lens mode and pass energy. + The transmission function is usually given as relative intensity vs. kinetic energy. + + The TF is used for calibration of the intensity scale in quantitative XPS. Without proper + transmission correction, a comparison of results measured from the same sample using different + operating modes for an instrument would show significant variations in atomic + concentrations. + + This concept is related to term `7.15 ff.`_ of the ISO 18115-1:2023 standard. + + .. _7.15 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.15 + + + + + + + + + + + + + + Kinetic energy values + + + + + + + + Relative transmission efficiency for the given kinetic energies + + + + + + - Refers to the last transformation specifying the positon of the manipulator in - the NXtransformations chain. + Refers to the last transformation specifying the position of the electron analyser + in the NXtransformations chain. Collection of axis-based translations and rotations to describe the location and - geometry of the manipulator as a component in the instrument. Conventions from - the NXtransformations base class are used. In principle, the McStas coordinate - system is used. The first transformation has to point either to another - component of the system or . (for pointing to the reference frame) to relate it - relative to the experimental setup. Typically, the components of a system should - all be related relative to each other and only one component should relate to - the reference coordinate system. + geometry of the electron analyser as a component in the instrument. Conventions + from the NXtransformations base class are used. In principle, the McStas + coordinate system is used. The first transformation has to point either to + another component of the system or "." (for pointing to the reference frame) to + relate it relative to the experimental setup. Typically, the components of a + system should all be related relative to each other and only one component + should relate to the reference coordinate system. @@ -125,12 +266,18 @@ - Deflectors outside the main optics ensambles described by the subclasses + Deflectors outside the main optics ensembles described by the subclasses - Individual lenses outside the main optics ensambles described by the subclasses + Individual lenses outside the main optics ensembles described by the subclasses + + + + + + Any other resolution not explicitly named in this base class. diff --git a/contributed_definitions/NXellipsometry.nxdl.xml b/contributed_definitions/NXellipsometry.nxdl.xml index 7e04bc5cf8..2af9c29691 100644 --- a/contributed_definitions/NXellipsometry.nxdl.xml +++ b/contributed_definitions/NXellipsometry.nxdl.xml @@ -1,36 +1,89 @@ - + - + + + + + + - Variables used throughout the document, e.g. dimensions and important - parameters + Variables used throughout the document, e.g. dimensions or parameters. - + - Size of the energy or wavelength vector used, the length of - NXinstrument/spectrometer/wavelength array + Length of the spectrum array (e.g. wavelength or energy) of the measured + data. - + - How many variables are saved in a measurement. e.g. 2 for Psi and - Delta, 16 for Mueller matrix elements, 15 for normalized Mueller - matrix, 3 for NCS, the length of NXsample/column_names + Number of sensors used to measure parameters that influence the sample, + such as temperature or pressure. - + - Number of incident angles used, the length of - NXinstrument/angle_of_incidence array + Number of measurements (1st dimension of measured_data array). This is + equal to the number of parameters scanned. For example, if the experiment + was performed at three different temperatures and two different pressures + N_measurements = 2*3 = 6. - + - Number of sample parameters scanned, if you varied any of the - parameters such as temperature, pressure, or pH, the maximal length of - the arrays specified by NXsample/environment_conditions/SENSOR/value - if it exists. + Number of detection angles of the beam reflected or scattered off the + sample. + + + + + Number of angles of incidence of the incident beam. + + + + + Number of observables that are saved in a measurement. e.g. one for + intensity, reflectivity or transmittance, two for Psi and Delta etc. This + is equal to the second dimension of the data array 'measured_data' and the + number of column names. @@ -90,171 +143,78 @@ * parameters used to tune the state of the sample * sample description - + An application definition for ellipsometry. - + - Version number to identify which definition of this application definition was - used for this entry/data. + Version number to identify which definition of this application + definition was used for this entry/data. - + - URL where to find further material (documentation, examples) relevant to the - application definition + URL where to find further material (documentation, examples) relevant + to the application definition. - + - Unique identifier of the experiment, such as a (globally persistent) unique - identifier. - i) The identifier is usually defined by the facility or principle investigator. - ii) The identifier enables to link experiments to e.g. proposals. + An optional free-text description of the experiment. + + However, details of the experiment should be defined in the specific + fields of this application definition rather than in this experiment + description. - + - A free-text description of the experiment. What is the aim of the experiment? - The general procedure. - - - - - Start time of the experiment. UTC offset should be specified. + Specify the type of ellipsometry. + + + + + + + + + - - - - Commercial or otherwise defined given name to the program that was used to - generate the result file(s) with measured data and metadata. This program - converts the measured signals to ellipsometry data. If home written, one can - provide the actual steps in the NOTE subfield here. - - - - - Either version with build number, commit hash, or description of a (online) - repository where the source code of the program and build instructions can be - found so that the program can be configured in such a way that result files can - be created ideally in a deterministic manner. - - - - - Website of the software. - - - - - - Contact information of at least the user of the instrument or the investigator - who performed this experiment. Adding multiple users if relevant is recommended. - - - - Name of the user. - - - - - Name of the affiliation of the user at the point in time when the experiment was - performed. - - - - - Full address (street, street number, ZIP, city, country) of the user's - affiliation. - - - - - Email address of the user. - - - - - Author ID defined by https://orcid.org/. - - - - - Official telephone number of the user. - - - - General properties of the ellipsometry equipment + Properties of the ellipsometry equipment. - - - The name of the instrument - - - - The used version of the hardware if available. If not a commercial instrument - use date of completion of the hardware. - - - - + - Name of the company which build the instrument + Name of the company which build the instrument. - + - ISO8601 date when the instrument was constructed. UTC offset should be - specified. + ISO8601 date when the instrument was constructed. + UTC offset should be specified. - - - Commercial or otherwise defined name of the software that was used for the - measurement - - - - Version and build number or commit hash of the software source code - - - + + - Website of the software. + Commercial or otherwise defined given name of the program that was + used to generate the result file(s) with measured data and metadata. + This program converts the measured signals to ellipsometry data. If + home written, one can provide the actual steps in the NOTE subfield + here. - - - - - Specify the used light source. Multiple selection possible. - + - - - Were focussing probes (lenses) used? - - - + - Were the recorded data corrected by the window effects of the lenses? - - - - - Specify the angular spread caused by the focussing probes - - - - - What type of ellipsometry was used? See Fujiwara Table 4.2 + What type of ellipsometry was used? See Fujiwara Table 4.2. @@ -271,569 +231,127 @@ - + - Was a calibration performed? If yes, when was it done? If the calibration time - is provided, it should be specified in calibration/calibration_time. + Define which element rotates, e.g. polarizer or analyzer. - - - - - + + + + - - - Ellipsometers require regular calibration to adjust the hardware parameters for - proper zero values and background light compensation. - - + + - If calibtration status is 'calibration time provided', specify the ISO8601 date - when calibration was last performed before this measurement. UTC offset should - be specified. + Specify the used light source. Multiple selection possible. - - - - Arrays which provide the measured calibration data. Multiple sets are possible, - e.g. Psi and delta measured on a e.g. silicon calibration wafer, and the - straight-through data. We recommend to provide data that is measured under the - same settings as the measurement was performed, that is if Psi and Delta are - measured for your data, also provide Psi and Delta here and use the same - wavelenghts as for the measured data. - - - - What data were recorded for the calibration? The number of variables - (N_variables) have to be set to the number of provided data columns accordingly, - e.g. psi/delta -> N_variables = 2, Jones vector -> N_variables = 4, Mueller - martix -> N_variables = 16, etc. - + - - - - - + + + + - - - Angle(s) of incidence used during the calibration measurement (excluding - straight through mode) - - - - - - - - The wavelength or equivalent values (which are inter-convertible). - The importer should convert all to one unit, and make the others - accessible. Historically, energy is used in eV, but for visible - spectroscopy wavelength is more common, for IR wave numbers in - 1/cm units. - - Possibly use the same type of data as for the measurement. - - - - - - - - Calibration is performed on a reference surface (usually a silicon wafer with a - well defined oxide layer) at a number of angles of incidence and in a straight - through mode (transmission in air). - - - - - - - - + - Free-text to describe which sample was used for calibration, e.g. silicon wafer - with 25 nm thermal oxide layer. + If focussing probes (lenses) were used, please state if the data + were corrected for the window effects. - - - - - Incident angle of the beam vs. the normal of the bottom reflective (substrate) - surface in the sample - - - - - - - - Sample stage, holding the sample at a specific position in X,Y,Z (Cartesian) - coordinate system and at an orientation defined by three Euler angles (alpha, - beta, gamma). The stage may be motorized or manual, special for liquids or gas - environment. - - - - Specify what type of stage was used. - - - - - - - - - - - - A free-text field to provide information about the stage. - - - - - The stage coordinate system vs. the incident beam. The Z-axis of the stage is considered to point along the normal of the substrate (bottom reflecting surface) from the stage towards the general direction of the light source. The beam comes with the angle of incidence towards this Z-axis, but in opposite direction, thus they are connected with a rotation of 180 - angle of incidence (in degrees). - This transformation brings us from the NEXUS coordinates to the stage coordinates. - Then provide the set of translations (if there are any). These all have a vector defining their relative direction in the current coordinate system. (This current coordinate system changes with every transformation if you set the parameter 'depends' to the name of the previous step.) - Last, provide the rotations of the sample - - + - If there is no motorized stage, we should at least qualify where the beam hits - the sample and in what direction the sample stands in a free-text description, - e.g. 'center of sample, long edge parallel to plane of incidence'. + Were the recorded data corrected by the window effects of the + focussing probes (lenses)? - - - - - For environmental measurements, the environment (liquid, vapor, vacuum etc.) is - enclosed in a cell or cryostat, which has windows both in the direction of the - source and the detector (looking from the sample). These windows also add a - phase shift to the light altering the measured signal. This shift has to be - corrected based on measuring a known sample in the environmental cell. - - - - The material of the window - - - - - - - - - - - - - - - If you specified 'other' as window material, decsribe here what it is. - - - - - Thickness of the window - - - - - Angle of the window normal (outer) vs. the substrate normal (similar to the - angle of incidence). - - - - - Recorded data that can be used to calculate the window effect. Typically this is - the substrate (e.g. silicon with thermal oxide layer) in air without window and - in a known medium with the window. - - + - What sample was used to estimate the window effect? + Specify the angular spread caused by the focussing probes. - - - Wavelength of the reference data. Use the same wavelengths at which all other - measurements are recorded - - - - - - - - Recorded data of a reference surface with and without window/medium. - - - - - - - - - - - - Which type of detector was used, and what is known about it? A detector can be a - photomultiplier (PMT), a CCD in a camera, or an array in a spectrometer. If so, - the whole detector unit goes in here. Integration time is the count time field, - or the real time field. See their definition. - - - - What kind of detector module is used, e.g. CCD-spectrometer, CCD camera, PMT, - photodiode, etc. - - - - - - - - - - - - - If you specified 'other' as detector type, please write down what it is. - - - - - Define how many rotations of the rotating element were taken into account per - spectrum. - - - - - Define which element rotates, e.g. polarizer or analyzer. - - - - - - - - - - - Rotation rate, if the revolution does not change during the measurement. - - - - - Specify maximum and minimum values for the revolution. - - - - - - + - Minimum signal for which dynamic averaging is performed. + Properties of the detector used. Integration time is the count time + field, or the real time field. See their definition. - - - - Value for the minimum intensity chosen. Data points below this value might be - skipped by the instrument - - - - - - The spectroscope element of the ellipsometer before the detector, but often - integrated to form one closed unit. Information on the dispersive element can be - specified in the subfield GRATING. Note that different gratings might be used - for different wavelength ranges. The dispersion of the grating for each - wavelength range can be stored in grating_dispersion. - - - - Wavelength value(s) used for the measurement. An array of 1 or more elements. - Length defines N_wavelength - - - - - - + + - Diffraction grating, as could be used in a monochromator. If two or more - gratings were used, define the angular dispersion and the wavelength range - (min/max wavelength) for each grating and make sure that the wavelength ranges - do not overlap. The dispersion should be defined for the entire wavelength range - of the experiment. + Properties of the rotating element defined in + 'instrument/rotating_element_type'. - + - Dispersion of the grating in nm/mm used. + Define how many revolutions of the rotating element were averaged + for each measurement. If the number of revolutions was fixed to a + certain value use the field 'fixed_revolutions' instead. - + - Minimum wavelength of the grating. + Define how many revolutions of the rotating element were taken + into account for each measurement (if number of revolutions was + fixed to a certain value, i.e. not averaged). - + - Maximum wavelength of the grating. + Specify the maximum value of revolutions of the rotating element + for each measurement. - + - Spectral resolution of the instrument. + The spectroscope element of the ellipsometer before the detector, + but often integrated to form one closed unit. Information on the + dispersive element can be specified in the subfield GRATING. Note + that different gratings might be used for different wavelength + ranges. The dispersion of the grating for each wavelength range can + be stored in grating_dispersion. - - - - Define the width of the monochromator slit in the subfield x_gap. - - - - Was the slit width fixed? - - - - - If slit width was not fixed, define the maximum slit width. - - - - Properties of the sample, its history, the sample environment and experimental - conditions (e.g. surrounding medium, temperature, pressure etc.), along with the - data (data type, wavelength array, measured data). - - - - Use Hill's system for listing elements of the periodic table which are inside or - attached to the surface of the specimen and thus relevant from a scientific - point. The purpose of this field is to allow material databases to parse the - relevant elements without having to interpret the sample history or other - fields. - - - - - Descriptive name of the sample - - - - - Ideally, a reference to the location or a unique (globally persistent) - identifier (e.g.) of e.g. another file which gives as many as possible details - of the material, its microstructure, and its thermo-chemo-mechanical - processing/preparation history. In the case that such a detailed history of the - sample is not available, use this field as a free-text description to specify - details of the sample and its preparation. - - - - - ISO8601 date with time zone (UTC offset) specified. - - - - - Qualitative description of the layer structure for the sample. For example: - Si/native oxide/thermal oxide/polymer/peptide - - - + - An identifier to correlate data to the experimental conditions, if several were - used in this measurement; typically an index of 0 - N + Was the backside of the sample roughened? Relevant for infrared + ellipsometry. - + + + - Select which type of data was recorded, for example Psi and Delta (see: - https://en.wikipedia.org/wiki/Ellipsometry#Data_acquisition). It is possible to - have multiple selections. Data types may also be converted to each other, e.g. a - Mueller matrix contains N,C,S data as well. This selection defines how many - columns (N_variables) are stored in the data array. + Select which type of data was recorded, for example Psi and Delta + (see: https://en.wikipedia.org/wiki/Ellipsometry#Data_acquisition). + It is possible to have multiple selections. Data types may also be + converted to each other, e.g. a Mueller matrix contains N,C,S data + as well. This selection defines how many columns (N_observables) are + stored in the data array. - - + + - - - Please list in this array the column names used in your actual data. That is - ['psi', 'delta'] or ['MM1', 'MM2', 'MM3', ..., 'MM16] for a full Mueller matrix, - etc. - - - - - - - - Resulting data from the measurement, described by data type. Minimum two columns - containing Psi and Delta, or for the normalized Mueller matrix it may be 16 (or - 15 if the element (1,1) is all 1). - - - - - - - - - - - - Specified uncertainties (errors) of the data described by data type. The - structure is the same as for the measured data. - - - - - - - - - - - - An array of relative time points if a time series was recorded. - - - - - - - - Specify external parameters that have influenced the sample. - - - - Describe what was the medium above or around the sample. The common model is - built up from the substrate to the medium on the other side. Both boundaries are - assumed infinite in the model. Here, define the name of the medium (e.g. water, - air, UHV, etc.). - - - - - Array of pairs of complex refractive indices of the medium for every measured - wavelength. Only necessary if the measurement was performed not in air, or - something very well known, e.g. high purity water. Specify the complex - refractive index: n + ik - - - - - - - - How many measurements were done varying the parameters? This forms an extra - dimension beyond incident angle, time points and energy/wavelength (this is the - length of the 4th dimension of the data). Defaults to 1. - - - - - Indicates which parameter was changed. Its definition must exist below. The - specified variable has to be number_of_runs long, providing the parameters for - each data set. If you vary more than one parameter simultaneously use one signal - instance for each. Record every parameter value in a linear manner, so N_p1 is - the number of measurements taken. For example, if you measure at two - temperatures and three pressures the temperature signal value looks like [T1, - T1, T1, T2, T2, T2] and the pressure signal value looks like [p1, p2, p3, p1, - p2, p3], and N_p1 = 6. - - - - - - - - - - - - - Was the sample modified using an optical source? Describe in this group the - parameters of the optical excitation used. - - - - Wavelength value(s) or the range used for excitation. In cases of continuous - laser radiation, a value or a set of values may do but for other illumination - types, such as pulsed lasers, or lamps, a range may describe the source better. - - - - - Specify the FWHM of the excitation - - - - - How long was the sample excited. - - - - - The integrated energy of light pulse. - - - - - - A sensor used to monitor an external condition. The value field contains the - measured values. If it is constant within an error for every run then use only - an array of length one. - - - - - - - What parameters are derived from the above data. - - - - Light loss due to depolarization as a value in [0-1]. - - - - - - A default view of the data, in this case Psi vs. wavelength and the angles of - incidence. If Psi does not exist, use other Mueller matrix elements, such as N, - C and S. - - - - We recommend to use wavelength as a default attribute, but it can be replaced in - the case of not full spectral ellipsometry to any suitable parameter along the - X-axis. - - + diff --git a/contributed_definitions/NXem.nxdl.xml b/contributed_definitions/NXem.nxdl.xml index d7567ab3c9..ffff5385b2 100644 --- a/contributed_definitions/NXem.nxdl.xml +++ b/contributed_definitions/NXem.nxdl.xml @@ -1,713 +1,435 @@ - + - + + - Characterization and session with one sample in an electron microscope. - - **The idea and aim of NXem**: - Electron microscopes (EM), whether it be a scanning electron microscope (SEM) - or a transmission electron microscope (TEM), are versatile tools for preparing - and characterizing samples and specimens. The term specimen is here understood - as a synonym for a sample. A specimen is a physical portion of material that - is studied/characterize in the microscope session, eventually in different - places on the specimen surface. - These places are named regions of interest (ROIs). - - Fundamentally, an EM is an electron accelerator. Experimentalists use an EM - in sessions during which they characterize as well as prepare specimens. - This application definition describes data and metadata about processes and - characterization tasks applied to one specimen. - - Multiple specimens have to be described with multiple NXentry instances. - - There are research groups who use an EM in a manner where it is exclusively - operated by a single, instrument-responsible scientists or a team of - (staff) scientists. These users perform analyses for other users as a service - task. Oftentimes, though, and especially for cutting-edge instruments, - the scientists and their team guide the process while operating the - microscope. Oftentimes the scientists operate the instrument themselves - either on-site or remotely and can ask technicians for support. - In all cases, these people are considered users. Users might have different - roles though. - - The rational behind a common EM schema rather than separate SEM or TEM - schemata are primarily the key similarities of SEM and TEM instruments: - Both have electro-magnetic lenses. These lens may differ in design, alignment, - number, and level of corrected-for aberrations. As an obvious difference, - a TEM is used mainly to measure the transmitted electron beam. - This demands thinner specimens as in SEM but offers capabilities for probing - of additional physical mechanisms of electron-matter interaction. - - Compared to SEMs, TEMs have a different relative arrangement between the - lenses and the specimen which is most obvious by the different relative - arrangement of the objective lens versus the specimen. - - Nevertheless, both types of electron microscopes use detector systems which - measure different types of signals that originate though from the same set of - radiation/specimen interactions. Consequently, detectors can also be similar. - - Given these physical and technical differences, different instruments have - been developed. This led to a coexistence of two broad interacting - communities: SEM and TEM users. From a data science perspective, we - acknowledge that the more specific a research question is and the narrower - the addressed user base is which develops or uses schemata for - research data management with EM, the more understandable it is - that scientists of either community (or sub-community) ask for - method-specific schemata. - - Researchers who have a single (main) microscope of some vendor in their lab, - may argue they need an NXem_vendor_name schema or an NXem_microscope_name or - an NXem_sem or a NXem_tem schema. - Scientists exclusively working with one technique or type of signal probed - (X-rays, electrons) may argue they wish to be pragmatic and store only - what is immediately relevant for their particular technique and - research questions. In effect, they may advocate for method-specific - schemata such as NXem_ebsd, NXem_eels, NXem_edx, or NXem_imaging. - - The development in the past has shown that these activities led to a zoo of - schemata and implementations of these into many data and file formats. - There is nothing which prevents the communities to make these schemata - open and interoperable. Open here means specifically not that all data are - compliant with/or use the schema and have to end up in the open-source domain. - There can be embargo periods first of all. Open means that the metadata and - associated schemata are documented in a manner that as many details as - possible are open in the sense that others can understand what the - (meta)data mean conceptually. - The `FAIR principles <https://doi.org/10.1038/sdata.2016.18>`_ guide all - decisions how data and metadata should be stored. - - EM instruments, software, and research are moving targets. Consequently, - there is a key challenge and inconvenience with having many different - schemata with associated representations of data and metadata in EM: - Each combination of schemata or an interoperable-made handshake between two - file formats or software packages has to be maintained by software developers. - This counts especially when data should be processed interoperably - between software packages. - - This brings two problems: Many software tools and parsers for the handshaking - between tools to maintain. This can result in usage of different terminology. - Which in turn results in representations and connections made between - different data representations and workflows that are not machine-actionable. - `There are community efforts to harmonize the terminology. <https://gitlab.hzdr.de/em_glossary/em_glossary>`_ - - A common vocabulary can serve interoperability as developers of schemata - and scientists can take for instance then these terms as closely as possible. - Ideally, they specialize the application definition only for the few very - specific additional quantities of their instruments and techniques. This is - better than reimplementing the wheel for descriptions of EM instruments. - This route of more standardization can support the EM community in that it - removes the necessity for having to maintain a very large number of schemata. - - Aiming for more standardization, i.e. a lower number of schemata rather than - a single standard for electron microscopy is a compromise that can serve - academia as it enables the EM community to focus their software development - efforts on those schemata, on fixing and discussing them, and on harmonize - their common vocabulary. These activities can be specifically relevant also - for vendors of EM hard- and software as it improves the longevity of certain - schema and thus can help to incentivize vendors to support the community with - implementing support for such schemata into their proprietary applications. - - In effect, everybody can gain from this as it will likely reduce the cases - in which scientists have to fix bugs in making their own tools compliant and - interoperable with tools of their colleagues and the wider community. - - The here proposed NXem application definition offers modular components - (EM-research specific base classes) for using NeXus to define schemata for - electron microscopy research. Working towards a common vocabulary is a - community activity that profits from everybody reflecting in detail whether - certain terms they have used are not eventually conceptually similar if not - the same as what this application definition and its base classes provide. - - We are happy for receiving your feedback. - - It is noteworthy to understand that (not only for) NeXus, schema differ - already if at least one field is required in one version of the schema, - but it is set optional in another version. If group(s), field(s), or - attributes are removed or added, or even a docstring is changed, schemata can - become inconsistent. An application definition here serves as a contract - between a data provider and a data consumer. These two can be software tools - (like the vendor software to drive the instrument or a scientific software - for doing artificial intelligence with EM data). - Such changes of a schema lead to new versions. - - Tools like NeXus do not avoid or protect against inconsistencies; however - NeXus offers a mechanism and toolset, through which schemata can be - documented and defined. In effect, having an openly documented - (at a case-specific level of technical detail) schema is a necessary but alone - not a sufficient step to take EM research on a route of machine-actionable - and interoperable FAIR data. - A common vocabulary and a machine-actionable knowledge representation/engine - is also required. Essentially when the docstrings are no longer needed - but can be replaced by a connection to an automated tool which understands - what a specific field represents conceptually, EM data have become more - generally interoperable EM data. - - This application definition takes a key step into this direction. - It offers a controlled vocabulary and relation between concepts and data - relevant for research with electron microscopes. To be most efficient and - offering reusability, the application definition should be understood as a - template that one should ideally use as is. This application definition - is called NXem. It can be considered a base for more specialized definitions - (ideally prefixed with NXem) *method*. - - **The use of NXem should be as follows:** - Offspring application definitions should not remove groups but make - them optional or, even better, propose changes in the application definition. - - A particular challenge with electron microscopes as physical instruments are - their dynamics. To make EM data understandable, repeatable, and eventually - corresponding experiments reproducible in general requires a documentation - of the spatio-temporal dynamics of the instrument in its environment. - For most commercial systems there is a specific accessibility beyond which - detailed settings like lens excitations and low-level hardware settings - may not be retrievable. - - EM experiments by design illuminate the specimen with electrons as a - consequence of which the specimen changes if not may get destroyed. - As such, repeatability of numerical processing and clear descriptions of - procedures and system setups should be addressed first. - - If especially a certain simulation package needs a detailed view of the - geometry of the lens system and its excitations during the course of the - experiment, it is difficult to fully abstract the technical details of the - hardware into a set of names for fields and groups that make for a compromise - between clarity and being vendor-agnostic. Settings of apertures are an - example where aperture modes are aliases behind which there is a set of - settings. These settings are difficult to retrieve, often undocumented in - detail. This serves users and makes EM experiments easier understandable and - conveniently executable for a broader user base. The opportunities for - application definitions to offer an abstraction layer are limited. - - Instead, currently it is for the docstring to specify what is conceptually - eventually behind such aliases. The design rule we followed while drafting - the application definition and base classes is that there are numerous - (technical) details about an EM which may warrant a very detailed technical - disentangling of settings and reflection of numerous settings as deeply - nested groups, fields and attributes. An application definition can offer a - place to hold these nested representations; however at the cost of generality. - - Which specific details matter for answering scientific research questions is - a difficult question to answer by a single team of scientists, especially - if the application definition is to speak for a number of vendors. What makes - it especially challenging if the application definition is expected to hold - all data that might be of relevance for future questions. - - We are skeptical if there is one representation that can fulfill all these - aims, while remaining at the same time approachable and executable by a large - number of scientists in a community. With this application definition we - would like to motivate the community to work towards such aim. While doing - so we found that existent terminology can be encoded into a more controlled - vocabulary. - - We have concluded that despite all these details of current EM research with - SEM, TEM, and focused-ion beam instruments, there a clearly identifiable - common components and generalizable settings of EM research use cases. - - **This application definition has the following components at the top-level:** - - * Generic experimental details (timestamp, identifiers, name); - conceptually these are session details. A session at a microscope may - involve the characterization of multiple specimens. For each specimen - an instance of an (NXentry) is created. Details of the instrument have to - be stored at least in an entry. Other entries should refer to these - metadata via links to reduce redundancies. - * Each signal, such as a spectrum or image taken at the microscope, should - have an associated time stamp and report of the specific settings at that - point in time when the image was taken. The reason is that EMs can be - highly dynamic, be used to illuminate the specimen differently - or show drift during signal acquisition, to name but a few effects. - What constitutes a single EM experiment/measurement? This can be the - collecting of a single diffraction pattern with a scanning TEM (STEM), - taking of a secondary electron image for fracture analysis, taking a set - of EBSD line scan and surface mappings in an SEM, or ion-beam-milling of a - specimen in preparation for an atom probe experiment. - * NXmonitor; - instances to keep track of time-dependent quantities - pertaining to specific components of the instrument. Alternatively - NXevent_data_em instances can be used to store timestamp states of the - components, which is relevant to document the exact settings when images - and spectra were taken. - * NXinstrument; - conceptually this is a container to store arbitrary level of detail of the - technical components of the microscope as a device and the lab in which - it is operated. - * NXuser; - conceptually, this is a set with at least one NXuser instance which details - who operated or performed the measurement. Additional NXusers can be - referred to in an NXevent_data_em instance to store - individualized details who executed an event. - * NXevent_data_em instances as an NXevent_data_em_set; - each NXevent_data_em instance is a container to group specific details - about the state of the microscope when a measurement was taken and - relevant data and eventual processing steps were taken (on-the-fly). - * NXdata; a the top-level, conceptually, this is a place for documenting - available default plottable data. A default plottable can be useful for - research data management systems to show a visual representation of some - aspect of the content of the EM session. - It is clear that what constitutes a useful default plot is a matter of - interpretation, somewhat of personal taste, and community standards. - - In effect, default plottables are case- and method-specific. - Usually a session at a microscope is used to collect multiple signals and - images. Examples for possible default plottables could be an arbitrarily - taken: secondary, back-scattered, electron image, diffraction pattern, - EELS spectra, composition, or orientation mappings to name but a few. - - **There are a few design choices to consider with sub-ordinate groups:** - - * Above images, spectra, and mappings should be stored as NXdata instances, - ideally formatted in such a way that they can be displayed with - visualization software that can be specific for the file format in which - the data are stored. NeXus specifies only the data model, i.e. the terms - and their relations. These descriptions can be implemented and stored in - JSON, HDF5, XML, or HSDS, file storage, or even other formats, although - HDF5 is the most commonly used. - * Consumable results of EM characterization tasks are usually a sub-set of - data artifacts, as there is not an infinite amount of possible - electron/ion beam-specimen interactions. - * Images of electron counts detected in specific operation modes (bright - field, dark field in TEM, secondary/back-scattered, Kikuchi in SEM) - * Spectra (X-ray quanta or auger electron counts) - * These data are in virtually all cases a result of some numerical - processing. It makes sense to name them with a controlled vocabulary, - e.g. SE (secondary electron), BSE (back-scattered electron), Kikuchi, - X-ray, Auger, Cathodolum(inescence) etc. - - A key question often asked with EM experiments is how the actual (meta)data - should be stored (in memory or on disk). To this end the schema, here makes no - specific assumptions, not even that all the fields/group of a schema instance - have to be stored into a single file. Instead, the schema specifies the - relations between metadata, constraints on how they should be formatted, what - they conceptually represent and which terms (controlled vocabulary) is - practical to store with the data. - - In effect, the application definition is a graph which describes how - (meta)data are related to one another. + Application definition for normalized representation of electron microscopy research. + + In line with the idea of NeXus application definitions, this schema is a + specialized version of NXem_base in that fields and groups are specifically + constrained. This has the effect that some quantities are required, so + that a research data management system (RDMS) can rely on the existence of + these pieces of information without demanding that RDMS to implement further + verification in its own source code or further harmonization or normalization + what each piece of information means conceptually. + + This application definition is thus an example of a general description + with which to normalize specific pieces of information and data collected + within electron microscopy research. + + This application definition is also a blueprint which shows how users + can build specific application definitions by reusing - instead of completely + reimplementing the wheel from scratch - em-specific base classes - and thus + represent electron-microscopy-specific content. + + The constraints of all these application definitions might be different + than for the here exemplified application definition NXem. + + Nevertheless, the key benefit remains: Many pieces of information are still + conceptually the same, named in the same way and found in the same place + in the hierarchy. This supports interoperability of electron microscopy data + and is advantageous compared to having everybody using own formatting and + conceptually not harmonized terms for describing their electron microscopy + research. + + For the detailed rationale and explanation of the concept behind the + NeXus electron microscopy class definitions please consult the preamble + of the NXem_base base class. - - - - An at least as strong as SHA256 hashvalue of the file - that specifies the application definition. - - + + + + + + + + + + + + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software which writes these NXprogram instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library <https://github.com/FAIRmat-NFDI/pynxtools>`_ + which is used by the `NOMAD <https://nomad-lab.eu/nomad-lab>`_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + + + + + + The configuration of the I/O writer software (e.g. `pynxtools <https://github.com/FAIRmat-NFDI/pynxtools>`_) + which was used to generate this NeXus file instance. + + + + + - - NeXus NXDL schema to which this file conforms. - - - - Ideally, a (globally) unique persistent identifier - for referring to this experiment. - - The identifier is usually defined/issued by the facility, laboratory, - or the principle investigator. - The identifier enables to link experiments to e.g. proposals. - - - - - Free-text description about the experiment. - - Users are strongly advised to detail the sample history in the respective - field and fill rather as completely as possible the fields of this - application definition rather than write details about the experiment - into this free-text description field. - - - - - ISO 8601 time code with local time zone offset to UTC information included - when the microscope session started. If the application demands that time - codes in this section of the application definition should only be used - for specifying when the experiment was performed - and the exact - duration is not relevant - this start time field should be used. - - Often though it is useful to specify a time interval with specifying - both start_time and end_time to allow for more detailed bookkeeping and - interpretation of the experiment. The user should be aware that even - with having both time instances specified, it may not be possible - to infer how long the experiment took or for how long data were acquired. - - More detailed timing data over the course of the experiment have - to be collected to compute this. These computations can take - advantage of individual time stamps in NXevent_em instances to - provide additional pieces of information. - - - - - ISO 8601 time code with local time zone offset to UTC included when - the microscope session ended. - - - + + + + + + - Commercial or otherwise given name to the program which was used to - create the file. - - Electron microscopy experiments are usually controlled/performed via - commercial integrated acquisition and instrument control software. - In many cases, an EM dataset is useful only if it gets post-processed - already during the acquisition, i.e. while the scientist is sitting - at the microscope. - Many of these processes are automated, while some demand GUI - interactions with the control software. Examples include collecting - of diffraction pattern and on-the-fly indexing of these. - - It is possible that different types of programs might be used to - perform these processing steps whether on-the-fly or not. If this is - the case the processing should be structured with individual NXprocess - instances. If the program and/or version used for processing referred - to in an NXprocess group is different to the program and version - mentioned in this field, the NXprocess needs - to hold an own program and version. + Either an identifier or an alias that is human-friendly so that + scientist find that experiment again - - - Program version plus build number, commit hash, or description of - an ever persistent resource where the source code of the program - and build instructions can be found so that the program can be - configured in such a manner that the result file is ideally - recreatable yielding the same results. - - - - - Binary container for a file or a compressed collection of files which - can be used to add further descriptions and details to the experiment. - The container can hold a compressed archive. - + + + + + + + + - - - A small image that is representative of the entry; this can be an - image taken from the dataset like a thumbnail of a spectrum. - A 640 x 480 pixel jpeg image is recommended. - Adding a scale bar to that image is recommended but not required - as the main purpose of the thumbnail is to provide e.g. thumbnail - images for displaying them in data repositories. - - + + + + + + - - - Contact information and eventually details of at least one person - involved in the taking of the microscope session. This can be the - principle investigator who performed this experiment. - Adding multiple users if relevant is recommended. - - - - Given (first) name and surname of the user. - - - - - Name of the affiliation of the user at the point in time when the experiment was - performed. - - - - - Postal address of the affiliation. - - - - - Email address of the user at the point in time when the experiment was - performed. Writing the most permanently used email is recommended. - - - - - Globally unique identifier of the user as offered by services like ORCID or - ResearcherID. - - - - - (Business) (tele)phone number of the user at the point in time when the - experiment was performed. - - - - - Which role does the user have in the place and at the point - in time when the experiment was performed? Technician operating - the microscope. Student, postdoc, principle investigator, guest - are common examples. - - - - - Account name that is associated with the user in social media platforms. - - - - - Name of the social media platform where the account under social_media_name is - registered. - - + + + + + + + - - - - A qualifier whether the sample is a real one or a virtual one (in a computer - simulation) - - - - - - - - A description of the material characterized in the experiment. - Sample and specimen are threaded as de facto synonyms. - - - - Descriptive name or ideally (globally) unique persistent identifier. - The name distinguishes the specimen from all others and especially - the predecessor/origin from where the specimen was cut. - - This field must not be used for an alias of the sample. - Instead, use short_title. - - In cases where multiple specimens have been loaded into the microscope - the name has to identify the specific one, whose results are stored - by this NXentry, because a single NXentry should be used only for - the characterization of a single specimen. - - Details about the specimen preparation should be stored in the - sample history. - - - - - Ideally, a reference to a (globally) unique persistent identifier, representing a data - artifact which documents ideally as many details of the material, its microstructure, - and its thermo-chemo-mechanical processing/preparation history as possible. - - The sample_history is the record what happened before the specimen was placed into the - microscope at the beginning of the session. - - In the case that such a detailed history of the sample/specimen is not available, use this field as - a free-text description to specify a sub-set of the entire sample history, i.e. what you would consider - are the key steps and relevant information about the specimen, its material, microstructure, - thermo-chemo-mechanical processing state, and the details of the preparation. - - Specific details about eventual physically-connected material like embedding resin should be - documented ideally also in the sample_history. If all fails, the description field - can be used but it is strongly discouraged because it leads to eventually non-machine-actionable - data. - - - - - ISO 8601 time code with local time zone offset to UTC information when the specimen was prepared. - - Ideally report the end of the preparation, i.e. the last known time the measured specimen surface - was actively prepared. Usually this should be a part of the sample history, i.e. the sample - is imagined handed over for the analysis. At the point it enters the microscope the session starts. - - Knowing when the specimen was exposed to e.g. specific atmosphere is especially required for - environmentally sensitive material such as hydrogen charged specimens or experiments - including tracers with a short half time. Further time stamps prior to preparation_date should - better be placed in resources which describe the sample_history. - - - - - Possibility to give an abbreviation or alias of the specimen name field. - - - - - Use Hill's system for listing elements of the periodic table which are inside or attached - to the surface of the specimen and thus relevant from a scientific point of view. - - The purpose of the field is to offer materials database systems an opportunity to parse - the relevant elements without having to interpret these from the sample history. - - - - - (Measured) sample thickness. The information is recorded to qualify - if the beam used was likely able to shine through the specimen. - - - - - Discouraged free-text field in case properly designed records for the - sample_history are not available. - - + + + + + + + + + + + + + + + + - - - Hard link to a location in the hierarchy of the NeXus file - where the data for default plotting are stored. - + + + + + + + + + + + - - - - - Metadata and numerical data of the microscope and the lab in which it stands. - - The em_lab section contains a description of the instrument and its components. - The component descriptions in this section differ from those inside individual - NXevent_em sections. These event instances take the role of time snapshot. - For an NXevent_em instance users should store only those settings for a - component which are relevant to understand the current state of the component. - Here, current means at the point in time, i.e. the time interval, - which the event represents. - - For example it is not relevant to store in each event's electron_gun group - again the details of the gun type and manufacturer but only the high-voltage - if for that event the high-voltage was different. If for all events - the high-voltage was the same it is not even necessary to include an electron_gun - section in the event. - - Individual sections of specific type should have the following names: - - * NXaperture: the name should match with the name of the lens - * NXlens_em: condenser_lens, objective_lens are commonly used names - * NXcorrector_cs: device for correcting spherical aberrations - * NXstage_lab: a collection of component for holding the specimen and - eventual additional component for applying external stimuli on the sample - * NXdetector: several possible names like secondary_electron, - backscattered_electron, direct_electron, ebsd, edx, wds, auger, - cathodoluminescence, camera, ronchigram - - - - Given name of the microscope at the hosting institution. This is an alias. - Examples could be NionHermes, Titan, JEOL, Gemini, etc. - - - - - Location of the lab or place where the instrument is installed. - Using GEOREF is preferred. - - - - - - - - - - - Description of the type of the detector. - - Electron microscopes have typically multiple detectors. - Different technologies are in use like CCD, scintillator, - direct electron, CMOS, or image plate to name but a few. - - - - - Free text option to write further details about the detector. - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + + + - A container to structure a set of NXevent_em instances. - - An event is a time point/interval during which the microscope - was configured in a specific way and the microscope was used - to take a measurement. - - Each NXevent_em holds an acquisition task with the microscope. - For instance the capturing of a secondary electron, backscattered - electron, diffraction image, or spectrum. - - An NXevent_em_data instance holds specific details about how raw data - from a detector were processed into consumable data like images, spectra, - etc. These on-the-fly data processing tasks are usually performed - by the control software, eventually realized with custom scripts. - - Furthermore, NXevent_em_state instances can document specific values - and settings of the microscope during the snapshot/event. + A region-of-interest analyzed either during or after the session. + For which specific processed data of the measured or simulated + data are available. - - - A container holding a specific result of the measurement and - eventually metadata how that result was obtained numerically. - - NXevent_em instances can hold several specific - NXimage_em or NXspectrum_em instances taken and considered as - one event, i.e. a point in time when the microscope had the - settings specified either in NXinstrument or in this NXevent_data_em - instance. - - The application definition is designed without an explicit need - an NXevent_data_em instance that contains an NXimage_em or - NXspectra_em instance. An NXevent_data_em can be used to document a - specific state of the microscope at a time without having it placed - into the NXinstrument group. - - In other words the NXinstrument group details primarily the more - static settings and components of the microscope as they are found - by the operator during the session. The NXevent_data_em samples - the dynamics. - - It is not necessary to store data in NXebeam, NXibeam instances - of NXevent_data_em but in this case it is assumed that the settings - were constant over the entire course of microscope session - and thus all relevant metadata inside the NXinstrument groups - are sufficient to understand the session. - - - - - - Reference to a specific state and setting of the microscope components. - - - - - - The detector or set of detectors that was used to collect this signal. - The name of the detector has to match one of the names of available - NXdetector instances e.g. if the instrument has an ebsd_camera - the detector for an NXimage_em_kikuchi should be the NXdetector - instance called ebsd_camera. - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_adf.nxdl.xml b/contributed_definitions/NXem_adf.nxdl.xml new file mode 100644 index 0000000000..1106424132 --- /dev/null +++ b/contributed_definitions/NXem_adf.nxdl.xml @@ -0,0 +1,65 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Base class method-specific for annular dark field imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. + + + + + Annulus inner (first value) and outer (second value) half angle. + + + + + + + + diff --git a/contributed_definitions/NXem_base.nxdl.xml b/contributed_definitions/NXem_base.nxdl.xml new file mode 100644 index 0000000000..2117081bac --- /dev/null +++ b/contributed_definitions/NXem_base.nxdl.xml @@ -0,0 +1,389 @@ + + + + + + + + Blue-print of a generic appdef for electron microscopy research formulated as a deep base class. + + This base class combines a method-specific and technical-design-level base class + instance to provide a template for storing parameterized descriptions of + pieces of information collected when performing electron microscopy research. + + The base class here shows all possible branches without making any statements + as to which of these have to be used in an instance. Thereby, the base class + provides a template how to name and structure concepts in a hierarchy + to support finding information and reducing the need for renaming and + restructuring information for a research field where many scientists perform + very specific research but who all also share commonalities like usage of + controlled electron beams, a focus on studies of electron beam matter interaction + to explore physical mechanisms and phenomena, or the desire to characterize materials + using electron microscopy. + + + + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software that writes these :ref:`NXprogram` instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library <https://github.com/FAIRmat-NFDI/pynxtools>`_ + which is used by the `NOMAD <https://nomad-lab.eu/nomad-lab>`_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + + + + + + The configuration of the I/O writer software (e.g. `pynxtools <https://github.com/FAIRmat-NFDI/pynxtools>`_) + which was used to generate this NeXus file instance. + + + + + + An at least as strong as SHA256 hashvalue of the file + which specifies the application definition. + + + + + NeXus NXDL schema to which this file conforms. + + + + + + + + Ideally, a (globally) unique persistent identifier + for referring to this experiment. + + An experiment should be understood in that this can be an experiment + in reality or a computer simulation because also the latter is an + experiment (see the Cambridge Dictionary experiment: + *a test done in order to find out something, eg if an idea is correct*). + + The identifier is usually issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments/simulations to e.g. proposals. + + + + + Free-text description about the experiment. + + Users are strongly advised to parameterize their description of the + experiment by using the respective base classes instead of writing prose + into this field. + + The reason is that such free-text field is difficult to machine-interpret. + The motivation behind keeping this field for now is to learn through + the information entered in this field in how far the current base + classes are incomplete. + + + + + ISO 8601 time code with local time zone offset to UTC information included + when the microscope session started. If the application demands that time + codes in this section of the application definition should only be used + for specifying when the experiment was performed - and the exact + duration is not relevant - this start_time field should be used. + + Often though it is useful to specify a time interval via setting both + a start_time and an end_time because this enables software tools and + users to collect a more detailed bookkeeping of the experiment. + + The user should be aware that even with having both time instances specified, + it may not be possible to infer how long the experiment took or for how + long data were acquired. + + More detailed timing data over the course of the experiment have + to be collected to compute this. These computations can take + advantage of individual time stamps start_time and end_time + in :ref:`NXevent_data_em` instances. + + + + + ISO 8601 time code with local time zone offset to UTC included when + the microscope session ended. See docstring of the start_time field + to see how the start_time and end_time should be used together. + + + + + + The program and eventual software libraries used with which the + NeXus instance was created. For the NOMAD OASIS research data + management system e.g. pynxtools and eventually all modules + if desired. + + + + + + Possibility to store a collection of data artifacts + associated with the experiment. + + + + + + Contact information and eventually details of at least one person + who performed or was involved in the session. This can be the + principle investigator who performed this experiment or the student + who performed the simulation. + Adding multiple users if relevant is recommended. + + + + Given (first) name and surname of the user. + + + + + Name of the affiliation of the user at the point in time + when the experiment was performed. + + + + + Postal address of the affiliation. + + + + + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + + + + + Service as another mean of identification of a user than by the name. + Examples could be details about an ORCID or social media account of + the user. + + + + + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + + + + + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope, student, postdoc, principle investigator, or guest + are common examples. + + + + + + + A description of the material characterized in the experiment. + Sample and specimen are threaded as de facto synonyms. + Samples can be real specimens or virtual (see method). + + + + A qualifier whether the sample is a real one or a + virtual one (in a computer simulation) + + + + + + + + + + Ideally, (globally) unique persistent identifier which distinguishes + the specimen from all others and especially the predecessor/origin + from where the specimen was cut. + + This field must not be used for an alias! Instead, use name. + + In cases where multiple specimens were loaded into the microscope, + the identifier has to resolve the specific sample, whose results are + stored by this :ref:`NXentry` instance, because a single NXentry should be + used only for the characterization of a single specimen. + + Details about the specimen preparation should be + stored in resources referring to parent_identifier. + + + + + Identifier of the sample from which the sample was cut or the string + *None*. The purpose of this field is to support functionalities + for tracking sample provenance via a research data management system. + + + + + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. Ideally, this + matches the last timestamp that is mentioned in the digital resource + pointed to by parent_identifier. + + Knowing when the specimen was exposed to e.g. specific atmosphere is + especially required for environmentally sensitive material such as + hydrogen charged specimens or experiments including tracers with a + short half time. Additional time stamps prior to preparation_date + should better be placed in resources which describe but which do not pollute + the description here with prose. Resolving these connected pieces of information + is considered within the responsibility of the research data management + system. + + + + + An alias used to refer to the specimen to please readability for humans. + + + + + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + `atom_types`. + + The purpose of the field is to offer research data management systems an + opportunity to parse the relevant elements without having to interpret + these from the resources pointed to by parent_identifier or walk through + eventually deeply nested groups in data instances. + + + + + + (Measured) sample thickness. + + The information is recorded to qualify if the beam used was likely + able to shine through the specimen. For scanning electron microscopy, + in many cases the specimen is typically thicker than what is + illuminatable by the electron beam. + + In this case the value should be set to the actual thickness of + the specimen viewed for an illumination situation where the nominal + surface normal of the specimen is parallel to the optical axis. + + + + + + + (Measured) density of the specimen. + + For multi-layered specimens this field should only be used to describe + the density of the excited volume. For scanning electron microscopy + the usage of this field is discouraged and instead an instance of an + :ref:`NXinteraction_vol_em` within individual :ref:`NXevent_data_em` + instances can provide a cleaner description of the relevant details + why one may wish to store the density of the specimen. + + + + + Discouraged free-text field to provide further detail although adding + parent_identifier and having a working research data management system + should provide this contextualization. + + + + + + + + + + + + A region-of-interest analyzed either during or after the session + for which specific processed data generated from the measured or the + simulated data are available. + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_conventions.nxdl.xml b/contributed_definitions/NXem_conventions.nxdl.xml new file mode 100644 index 0000000000..1c948affc4 --- /dev/null +++ b/contributed_definitions/NXem_conventions.nxdl.xml @@ -0,0 +1,534 @@ + + + + + + + + + + + Conventions for rotations and coordinate systems to interpret crystal orientation + and other data and results collected with electron microscopy research. + + Documenting explicitly all used conventions and coordinate systems is + the decisive context whereby many results from electron microscopy are + at all interpretable. + + + + + Mathematical conventions and materials-science-specific conventions + required for interpreting every collection of orientation data. + + + + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + + + + + + + + + + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + How are Euler angles interpreted given that there are several + choices (e.g. ZXZ, XYZ, etc.) according to convention 4 of + DOI: 10.1088/0965-0393/23/8/083501. + The most frequently used convention is ZXZ which is based on + the work of H.-J. Bunge but other conventions are possible. + + + + + + + + + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + Which sign convention is followed when converting orientations + between different parameterizations/representations according + to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + + Details about eventually relevant named directions that may + give reasons for anisotropies. The classical example is cold-rolling + where one has to specify which directions (rolling, transverse, and normal) + align how with the direction of the base vectors of the sample_reference_frame. + + + + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + Handedness of coordinate system. + + + + + + + + + Location of the origin of the processing_reference_frame. + This specifies the location Xp = 0, Yp = 0, Zp = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + + + + + + + + + + + + + + + + Name or alias assigned to the x-axis base vector, + e.g. rolling direction. + + + + + Direction of the positively pointing x-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + + + + + + + + + + + + + + Name or alias assigned to the y-axis base vector, + e.g. transverse direction. + + + + + Direction of the positively pointing y-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + + + + + + + + + + + + + + Name or alias assigned to the z-axis base vector, + e.g. normal direction. + + + + + Direction of the positively pointing z-axis base vector of + the processing_reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + + + + + + + + + + + + + + + Details about the sample/specimen reference frame. + + + + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + The reference frame for the sample surface reference is used for + identifying positions on a (virtual) image which is formed by + information collected from an electron beam scanning the + sample surface. We assume the configuration is inspected by + looking towards the sample surface from a position that is + located behind the detector. + Reference DOI: 10.1016/j.matchar.2016.04.008 + The sample surface reference frame has coordinates Xs, Ys, Zs. + In three dimensions these coordinates are not necessarily + located on the surface of the sample as there are multiple + faces/sides of the sample. Most frequently though the coordinate + system here is used to define the surface which the electron + beam scans. + + + + + + + + + Handedness of the coordinate system if it is a Cartesian. + + + + + + + + + Location of the origin of the sample surface reference frame. + This specifies the location Xs = 0, Ys = 0, Zs = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + + + + + + + + + + + + + + + + Name or alias assigned to the x-axis base vector, + e.g. longest edge. + + + + + Direction of the positively pointing x-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + + + + + + + + + + + + + + Name or alias assigned to the y-axis base vector, + e.g. long edge. + + + + + Direction of the positively pointing y-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + + + + + + + + + + + + + + Name or alias assigned to the z-axis base vector, + e.g. shortest edge. + + + + + Direction of the positively pointing z-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + + + + + + + + + + + + + + + Details about the detector reference frame for a specific detector. + + + + Reference to the specifically named :ref:`NXdetector` instance + for which these conventions in this :ref:`NXprocess` group apply + (e.g. /entry1/instrument/detector1). + + + + + Type of coordinate system/reference frame used for + identifying positions in detector space Xd, Yd, Zd, + according to DOI: 10.1016/j.matchar.2016.04.008. + + + + + + + + + Handedness of the coordinate system if it is a Cartesian. + + + + + + + + + Where is the origin of the detector space reference + frame located. This is the location of Xd = 0, Yd = 0, Zd = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + + + + + + + + + + + + + + + + Name or alias assigned to the x-axis base vector, + e.g. longest edge as some landmark on the detector. + + + + + Direction of the positively pointing x-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + + + + + + + + + + + + + + Name or alias assigned to the x-axis base vector, + e.g. long edge as some landmark on the detector. + + + + + Direction of the positively pointing y-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + Name or alias assigned to the x-axis base vector, + e.g. short edge as some landmark on the detector. + + + + + Direction of the positively pointing z-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_conventions_ebsd.nxdl.xml b/contributed_definitions/NXem_conventions_ebsd.nxdl.xml new file mode 100644 index 0000000000..d2d7456aaa --- /dev/null +++ b/contributed_definitions/NXem_conventions_ebsd.nxdl.xml @@ -0,0 +1,230 @@ + + + + + + + Base class for method-specific conventions EBSD. + + This base class is expected to be used with :ref:`NXem_conventions`. + + This is the main issue which currently is not in all cases documented + and thus limits the interoperability and value of collected EBSD data. + Not communicating EBSD data with such contextual pieces of information + and the use of file formats which do not store this information is the + key unsolved problem. + + + + Details about the gnomonic projection reference frame. + + + + Type of coordinate system/reference frame used for identifying + positions in the gnomonic projection space Xg, Yg, Zg + according to DOI: 10.1016/j.matchar.2016.04.008. + + + + + + + + + Handedness of coordinate system. + + + + + + + + + Is the origin of the gnomonic coordinate system located + where we assume the location of the pattern centre. + This is the location Xg = 0, Yg = 0, Zg = 0 according to + reference DOI: 10.1016/j.matchar.2016.04.008. + + + + + + + + + Direction of the positively pointing "gnomomic" x-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + + + + + + + + + + + + + + Direction of the positively pointing "gnomomic" y-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + Direction of the positively pointing "gnomomic" z-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + + Details about the definition of the pattern centre + as a special point in the gnomonic projection reference frame. + + + + From which border of the EBSP (in the detector reference frame) + is the pattern centre's x-position (PCx) measured? + Keywords assume the region-of-interest is defined by + a rectangle. We observe this rectangle and inspect the + direction of the outer-unit normals to the edges of + this rectangle. + + + + + + + + + + + + In which direction are positive values for PCx measured from + the specified boundary. Keep in mind that the gnomonic space + is in virtually all cases embedded in the detector space. + Specifically, the XgYg plane is defined such that it is + embedded/laying inside the XdYd plane (of the detector + reference frame). + When the normalization direction is the same as e.g. the + detector x-axis direction, we state that we effectively + normalize in fractions of the width of the detector. + + The issue with terms like width and height is that these + degenerate if the detector region-of-interest is square-shaped. + This is why we should better avoid talking about width and height but + state how we would measure distances practically with a ruler and + how we then measure positive distances. + + + + + + + + + + + + From which border of the EBSP (in the detector reference + frame) is the pattern centre's y-position (PCy) measured? + For further details inspect the help button of + xaxis_boundary_convention. + + + + + + + + + + + + In which direction are positive values for PCy measured from + the specified boundary. + For further details inspect the help button of + xaxis_normalization_direction. + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_correlation.nxdl.xml b/contributed_definitions/NXem_correlation.nxdl.xml new file mode 100644 index 0000000000..95a644b519 --- /dev/null +++ b/contributed_definitions/NXem_correlation.nxdl.xml @@ -0,0 +1,245 @@ + + + + + + Base class to combine different method-specific data in electron microscopy. + + This base class represent a template for documenting correlations + (spatial, temporal) between different method-specific results. + + + + Details about processing steps. + + + + + + Details about correlated or logically connected EBSD datasets. + + One important class of such correlated experiments are the so-called + (quasi) in-situ experiments. In this case the same or nearly the same ROI + gets analyzed via a repetitive sequence of thermomechanical treatment, + sample preparation, measurement, on-the-fly-indexing. Phenomena + investigated are recrystallization, strain accumulation, material damage. + Post-processing is required to correlate and reidentify eventual + microstructural features or local ROIs across several orientation maps. + + Another important class of correlated experiments are the so-called + serial-sectioning experiments. Here the same sample is measured + repetitively after polishing each time, to create a stack of + orientation data which can be reconstructed to a + three-dimensional volume ROI. + + Data can be correlated in time, position (spatial), or both (spatiotemporal). + + Spatial correlations between repetitively characterized regions-of-interests + are typically correlated using image registration and alignment algorithms. + For this typically so-called landmarks are used. These can be grains with + a very large size or specific shape, i.e. grains which are qualitatively + different enough to be used as a guide how images are shifted relative to + one another. Other commonly used landmarks are fiducial marks which are + milled into the specimen surface using focus-ion beam milling and/or various + types of indentation methods. + + As far as the same physical region-of-interest is just measured several times, + the additional issue of the depth increment is not a concern. However, correct + assumptions for the depth increment, amount of material removed along the milling + direction is relevant for accurate and precise three-dimensional (serial-sectioning) + correlations. For these studies it can be tricky though to assume or estimate + useful depth increments. Different strategies have been proposed like + calibrations, wedged-shaped landmarks and computer simulation assisted + assumption making. + + Despite the use of landmarks, there are many practical issues which make the + processing of correlations imprecise and inaccurate. Among these are drift + and shift of the specimen, instabilities of the holder, the beam, irrespective + of the source of the drift, charging effects, here specifically causing local + image distortions and rotations which may require special processing algorithms + to reduce such imprecisions. + + Time correlations face all of the above-mentioned issues surplus the challenge + that specific experimental protocols have to be used to ensure the material state + is observed at specific physical time. The example of quasi in-situ characterization + of crystal growth phenomena, a common topic in engineering or modern catalysis research + makes it necessary to consider that e.g. the target value for the desired annealing + temperature is not just gauged based on macroscopic arguments but considers + that transient effects take place. Heating or quenching a sample might thus might + not have been executed under conditions in the interaction volume as they are + documented and/or assumed. + + These issue cause that correlations have an error margin as to how accurately + respective datasets were not only just synced based on the geometry of the + region-of-interests and the time markers but also to asssure which physical + conditions the specimen experienced over the course of the measurements. + + The fourth example of the em_om reference implementation explores the use of the + correlation group with a serial-sectioning datasets that was collected by the + classical Inconel 100 dataset collected by M. D. Uchic and colleagues + (M. Groeber M, Haley BK, Uchic MD, Dimiduk DM, Ghosh S 3d reconstruction and + characterization of polycrystalline microstructures using a fib-sem system data set. + Mater Charac 2006, 57 259–273. 10.1016/j.matchar.2006.01.019M). + + This dataset was specifically relevant in driving forward the implementation + of the DREAM.3D software. DREAM.3D is an open-source software project for + post-processing and reconstructing, i.e. correlating sets of orientation + microscopy data foremost spatially. One focus of the software is the + (post-)processing of EBSD datasets. Another cutting edge tool with similar + scope but a commercial solution by Bruker is QUBE which was developed by + P. Konijnenberg and coworkers. + + Conceptually, software like DREAM.3D supports users with creating linear + workflows of post-processing tasks. Workflows can be instructed via the + graphical user interface or via so-called pipeline processing via command line + calls. DREAM.3D is especially useful because its internal system documents all + input, output, and parameter of the processing steps. This makes DREAM.3D a + good candidate to interface with tools like em_om parser. Specifically, DREAM.3D + documents numerical results via a customized HDF5 file format called DREAM3D. + Workflow steps and settings are stored as nested dictionaries in JSON syntax + inside a supplementary JSON file or alongside the data in the DREAM3D file. + DREAM.3D has a few hundred algorithms implemented. These are called filters + in DREAM.3D terminology. + + Users configure a workflow which instructs DREAM.3D to send the data through + a chain of predefined and configured filters. Given that for each analysis + the filter is documented via its version tags surplus its parameter and setting + via a controlled vocabulary, interpreting the content of a DREAM3D HDF5 file + is possible in an automated manner using a parser. This makes DREAM.3D analyses + repeatable and self-descriptive. A key limitation though is that most frequently + the initial set of input data come from commercial files like ANG. + This missing link between the provenance of these input files, their associated + creation as electron microscope session, is also what NXem_ebsd solves. + + Nevertheless, as this can be solved with e.g. NXem_ebsd we are convinced that + the DREAM.3D and the em_om parser can work productively together to realize + RDMS-agnostic parsing of serial-section analyses. + + The internal documentation of the DREAM.3D workflow also simplifies the + provenance tracking represented by an instance of NXem_ebsd as not every + intermediate results has to be stored. Therefore, the fourth example + focuses on the key result obtained from DREAM.3D - the reconstructed + and aligned three-dimensional orientation map. + + Usually, this result is the starting point for further post-processing + and characterization of structural features. As here orientation microscopy + is insofar scale invariant using DREAM.3D, NXem_ebsd, and em_om should + be useful for different characterization methods, such as EBSD, Transmission + Kikuchi Diffraction (TKD), Automated Crystal Orientation Mapping (ACOM), + Nanobeam Electron Diffraction (using commercial systems like NanoMegas ASTAR) + or open-source implementations of these techniques (such as via pyxem/orix). + + The result of orientation microscopy methods are maps of local orientation + and thermodynamic phase (crystal structure) pieces of information. Virtually + all post-processing of such results for structural features includes again + a workflow of steps which are covered though by the NXms partner application + definition. The respective source of the data in an instance of NXms can + again be a link or reference to an instance of NXem_ebsd to complete the + chain of provenance. + + + + + + Descriptor representing the image contrast. + + + + + + Title of the default plot. + + + + + Descriptor values displaying the ROI. + + + + + + + + + + Descriptor values. + + + + + + Calibrated coordinate along the z-axis. + + + + + + + Label for the z axis + + + + + + Calibrated coordinate along the y-axis. + + + + + + + Label for the y axis + + + + + + Calibrated coordinate along the x-axis. + + + + + + + Label for the x axis + + + + + + + diff --git a/contributed_definitions/NXem_ebsd.nxdl.xml b/contributed_definitions/NXem_ebsd.nxdl.xml new file mode 100644 index 0000000000..33c8b9cb3c --- /dev/null +++ b/contributed_definitions/NXem_ebsd.nxdl.xml @@ -0,0 +1,551 @@ + + + + + + + + Number of arguments per orientation for given parameterization. + + + + + Number of scan points. + + + + + Number of pixel along the slowest changing dimension for a rediscretized, + i.e. standardized default plot orientation mapping. + + + + + Number of pixel along slow changing dimension for a rediscretized i.e. + standardized default plot orientation mapping. + + + + + Number of pixel along fast changing dimension for a rediscretized i.e. + standardized default plot orientation mapping. + + + + + Base class method-specific for Electron Backscatter Diffraction (EBSD). + + The general procedure of an EBSD experiment is as follows: + Users load the specimen, collect first a coarse image of the surface. + Next, they set an approximate value for the calibrated working distance and + tilt the stage to set the desired diffraction conditions. + + Users then typically configure the microscope for collecting higher quality data + and push in the EBSD detector. Subsequently, they fine tune the illumination + and aberration corrector settings and select one or multiple ROIs for + the microscope to machine off automatically. They configure on-the-fly + indexing parameter and start the measurement queue. + + Nowadays, this is in most cases an automated process. The pattern + collection runs during the allocated microscope session until the + queue finishes or gets interrupted by errors or the next user terminates + sessions which run over time. + + Kikuchi pattern surplus eventually multi-modal detector signals are + collected and usually indexed on-the-fly. Patterns may be stored or not + so one should not assume that raw data are always stored. + + Results are stored in files, which afterwards are typically copied + automatically or manual for archival purposes to certain storage + locations or further consumption. The result of such an EBSD + measurement/experiment is a set of usually proprietary or open files + from technology partners. + + This :ref:`NXem_ebsd` base class is a proposal how to represent method-specific + data, metadata, and connections between these for the research field of + electron microscopy. + + More specifically, exemplified here for electron backscatter diffraction (EBSD) + we show how NeXus can be used to solve two key documentation issues so far + missing in the field of EBSD. + + Firstly, an instance of NXem_ebsd (such as a NeXus/HDF5 file which is formatted + according to NXem_ebsd) stores the connection between the microscope session and + the key datasets which are considered typically results of the various processing + steps involved when working with EBSD data. + + Different groups in NXem_ebsd make connections to data artifacts which were collected + when working with electron microscopes via the NXem application definition. + Using a file which stores information according to the NXem application definition + has the benefit that it connects the sample, references to the sample processing, + the user operating the microscope, details about the microscope session, + and details about the acquisition and eventual indexing of Kikuchi pattern, + associated overview images, like secondary electron or backscattered electron + images of the region-of-interest probed and many more pieces of information. + + Secondly, NXem_ebsd connects and stores the conventions and reference frames + which were used and which are the key to a correct mathematical interpretation + of every EBSD result. Otherwise, results would be ripped out of their context, + as it is the current situation with many traditional studies where EBSD data + were indexed on-the-fly and shared with the community only via sharing + the strongly processed results file in some technology-partner-specific file + format but without communicating all conventions or relying on the assumptions + that colleagues likely know these conventions even though multiple definitions + are possible. + + NXem_ebsd covers experiments with one-, two-dimensional, and so-called three- + dimensional EBSD datasets. The third dimension is either time (in the case of + quasi in-situ experiments) or space (in the case of serial-sectioning) methods + where a combination of mechanical or ion milling is used repetitively to measure + the same region-of-interest at different depth increments. Material removal + can be achieved with electron or ion polishing, using manual + steps or using automated equipment like a robot system. + + Three-dimensional experiments require to follow a sequence of specimen, surface + preparation, and data collection steps. By nature these methods are destructive + in that they either require the removal of the previously measured material region + or that the sample surface can degrade due to e.g. contamination or other + electron-matter interaction. + + For three-dimensional EBSD, multiple two-dimensional EBSD orientation mappings are + combined into one reconstructed stack. That is serial-sectioning is mainly a + computational workflow. Users collect data for each serial sectioning step + via an experiment. This assures that data for associated microscope sessions + and steps of data processing stay connected and contextualized. + + Eventual tomography methods also use such a workflow because first diffraction + images are collected (e.g. with X-ray) and then these imagres are indexed and + computed into a 3D orientation mapping. The here proposed NXem_ebsd application + definition contains conceptual ideas how this splitting between measurement and + post-processing can be granularized also for such X-ray-based techniques, whether + it be 3DXRD or HEDM. + + + + + + This group documents relevant details about the conditions and the tools + used for measuring a stack of Kikuchi diffraction pattern with an + electron microscope. + + The most frequently collected EBSD data are captured for rectangular + regions-of-interested which are sampled with regular square or + hexagon-shaped pixels. + + + + Physical time since the beginning of a timestamp that is required to be + same for all experiments in the set. The purpose of this marker is + to identify how all experiments in the set have have to be arranged + sequentially based on the time elapsed. + The time is relevant to sort e.g. experiments of consecutive quasi + in-situ experiments where a measurement was e.g. taken after 0 minutes + of annealing, 30 minutes, 6 hours, or 24 hours of annealing. + + + + Timestamp relative to which time was counted to aid + converting between time and timestamp. + + + + + + + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXdata` where the pattern are stored. + + + + + Reference (e.g. path and filename) to an existent data artifact which + stores either the measured pattern or input (already processed EBSD data). + + + + + + This group documents relevant details about the conditions and the tools + used for simulating a stack of Kikuchi diffraction pattern with some + physical model. + + This group should not be confused with a group named simulation that + is however an instance of NXem_sim. Instead, the simulation group here + should be used if (e.g. instead of a measurement) a stack of pattern + were simulated that one wishes to use for indexing patterns. + + In many practical cases where pattern are analyzed on-the-fly and dictionary + indexing strategies are used, so-called master pattern(s) are used to compare + measured or simulated pattern with the master pattern. In this case, + master pattern are the result of a computer simulation and thus should + be stored using an own properly documented entry within a simulation + group as an instance of :ref:`NXem_sim`. + + + + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXimage_r_set_diff` + where the simulated pattern are stored. + + + + + Reference (e.g. path and filename) to an existent digital resource which + stores either the pattern or input (already processed EBSD data) + which is now processed further as described by this NXem_ebsd instance. + + + + + + The EBSD system, including components like the electron gun, pole-piece, + stage tilting, EBSD detector, and the gnomonic projection have to be + calibrated to achieve reliable indexing results. + + Specifically, the gnomonic projection has to be calibrated. + Typically, silicon or quartz crystals are used for this purpose. + + Considering a system is well-calibrated, it is much more frequently the + case in practice that users assume the system is calibrated (and thus usable) + vs. they perform the calibration of the EBSD system. + + In the first case, the user assumes that the principle geometry of the + hardware components and the settings in the control and EBSD pattern + acquisition software has been calibrated. Consequently, users pick from + an existent library of phase candidates, i.e. + :ref:`NXcrystal_structure` instances. Examples are + reflector models as stored in CRY files (HKL/Channel 5/Flamenco). + + In the second case, users calibrate the system during the session + using standards (silicon, quartz, or other common specimens). + There is usually one person in each lab responsible for doing such + calibrations. Often this person or technician is also in charge of + configuring the graphical user interface and software with which most + users control and perform their analyses. + + For EBSD this has key implications: Taking TSL OIM/EDAX as an example, + the conventions how orientations are stored is affected by how the + reference frames are configured and this setup is made at the level + of the GUI software. + + Unfortunately, these pieces of information are not necessarily stored + in the results files. In effect, key conventions become disconnected + from the data so it remains the users' obligation to remember these + settings or write these down in a lab notebook. Otherwise, these metadata + get lost. All these issues are a motivation and problem which + :ref:`NXem_ebsd` solves in that all conventions can be specified explicitly. + + + + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXem_msr` where the calibration is + stored. + + + + + Reference to a digital resource where the calibration is stored. + + + + + + Indexing is a data processing step performed either after or while + (on-the-fly) the beam scans the specimen. The resulting method is also + known as orientation imaging microscopy (OIM). + + Different algorithms can be used to index EBSD pattern. Common to them + is the computational step where simulated reference pattern are compared + with measured or simulated patterns. These latter patterns are referred + to via the measurement or simulation groups of this base class. + + Quality descriptors are defined based on which an indexing algorithm + yields a quantitative measure of how similar measured and reference + pattern are, and thus if no, one, or multiple so-called solutions + were found. + + Assumed or simulated pattern are simulated using kinematic or dynamical + theory of electron diffraction delivering master pattern. + + The Hough transform is essentially a discretized Radon transform (for details see `M. van Ginkel et al. <https://www.semanticscholar.org/paper/A-short-introduction-to-the-Radon-and-Hough-and-how-Ginkel/fb6226f606cad489a15e38ed961c419037ccc858>`_). + Recently, dictionary-based indexing methods are increasingly becoming used + partly driven by the interest to use artificial intelligence algorithms. + + + + This group enables to establish a logical connection between previous + processing steps or on-the-fly-performed indexing of the EBSD map. + Typically these processing steps are performed with commercial software. + Therefore, in many cases a results file from this indexing is often + all that is communicated and saved. These are typically files in a format + specific to the instrument and its configuration. + + Typical file formats are CPR/CRC, ANG, OSC, HDF5, H5EBSD, EDAXH5. + + + + + Principal algorithm used for indexing. + + + + + + + + + + + + Details about the background correction applied to each Kikuchi pattern. + + + + + Binning i.e. downsampling of the pattern. + + + + + Specific parameter relevant only for certain algorithms used. + + + + + Details for each phase used as a model with which the patterns were + indexed. Instances of :ref:`NXcrystal_structure` in this group must + have the group name prefix phase. The identifier in the name is an + integer. We start counting from 1 because the value 0 is reserved for + the special phase that is the null-model, i.e. the null phase, notIndexed. + + + + + Which return value did the indexing algorithm yield for each scan point. + Practically useful is to use an uint8 mask. + + * 0 - Not analyzed + * 1 - Too high angular deviation + * 2 - No solution + * 100 - Success + * 255 - Unexpected errors + + + + + + + + How many phases i.e. crystal structure models were used to index each + scan point if any? Let's assume an example to explain how this field + should be used: In the simplest case users collected one pattern for + each scan point and have indexed using one phase, i.e. one instance + of an NXem_ebsd_crystal_structure_model. + + In another example users may have skipped some scan points (not indexed) + them at all) and/or used differing numbers of phases for different scan + points. + + The cumulated of this array decodes how phase_identifier and phase_matching + arrays have to be interpreted. In the simplest case (one pattern per scan + point, and all scan points indexed using that same single phase model), + phase_identifier has as many entries as scan points + and phase_matching has also as many entries as scan points. + + + + + + + + The array n_phases_per_scan_point details how the phase_identifier + and the phase_matching arrays have to be interpreted. + + For the example with a single phase phase_identifier has trivial + values either 0 (no solution) or 1 (solution matching + sufficiently significant with the model for phase 1). + + When there are multiple phases, it is possible (although not frequently + needed) that a pattern matches eventually (not equally well) sufficiently + significant with multiple pattern. This can especially happen in cases of + pseudosymmetry and more frequently with an improperly calibrated system + or false or inaccurate phase models e.g. (ferrite, austenite). + Having such field is especially relevant for recent machine learning + or dictionary based indexing schemes because in combination with + phase_matching these fields communicate the results in a model-agnostic + way. + + Depending on the n_phases_per_scan_point value phase_identifier and + phase_matching arrays represent a collection of concatenated tuples, + which are organized in sequence: The solutions for the 0-th scan point, + the 1-th scan point, the n_sc - 1 th scan point and omitting tuples + for those scan points with no phases according to n_phases_per_scan_point + + + + + + + + One-dimensional array, pattern by pattern labelling the solutions found. + The array n_phases_per_scan_point has to be specified because it details + how the phase_identifier and the phase_matching arrays have to be interpreted. + See documentation of phase_identifier for further details. + + + + + + + + Phase_matching is a descriptor for how well the solution matches or not. + Examples can be confidence_index, mean_angular_deviation, some AI-based + matching probability (other), i.e. the details are implementation-specific. + + + + + + + + + + + + + + Calibrated center positions of each scan point + in the sample surface reference system. + + + + + + + + + Fraction of successfully indexed pattern with a phase + not the null-phase vs the number_of_scan_points. + + + + + Number of scan points in the original mapping. + + + + + + + + + An overview of the entire ROI. + + + + Descriptor representing the image contrast. + + + + + + + + + + + + Title of the default plot. + + + + + Descriptor values displaying the ROI. + + + + + + + + + Descriptor values. + + + + + + Calibrated coordinate along the y-axis. + + + + + + + Label for the y axis + + + + + + Calibrated coordinate along the x-axis. + + + + + + + Label for the x axis + + + + + + diff --git a/contributed_definitions/NXem_eds.nxdl.xml b/contributed_definitions/NXem_eds.nxdl.xml new file mode 100644 index 0000000000..68a61d57ec --- /dev/null +++ b/contributed_definitions/NXem_eds.nxdl.xml @@ -0,0 +1,144 @@ + + + + + + + + + + Number of pixel along the y direction, the slow direction + + + + + Number of pixel along the x direction, the fast direction + + + + + Number of X-ray photon energy (bins), the fastest direction. + + + + + Number of identified elements + + + + + Number of peaks detected + + + + + Base class method-specific for energy-dispersive X-ray spectroscopy (EDS/EDX). + + `IUPAC instead of Siegbahn notation <https://doi.org/10.1002/xrs.1300200308>`_ should be used. + + + + + Details about computational steps how peaks were indexed as elements. + + + + The program with which the indexing was performed. + + + + + Name and location of each X-ray line which was indexed as a known ion. + For each ion, an NXion instance should be created which specifies + the origin of the signal. For each ion also the relevant IUPAC notation + X-ray lines should be specified. + + + + + Associated lower :math:`[e_{min}, e_{max}]` bounds of the + energy which is assumed associated with this peak. + + + + + + + + Theoretical energy of the line according to IUPAC. + + + + + IUPAC notation identifier of the line which the peak represents. + + This can be a list of IUPAC notations for (the seldom) case that + multiple lines are grouped with the same peak. + + + + + + + + + + List of the names of identified elements. + + + + + + + + Individual element-specific EDS/EDX/EDXS/SXES mapping + + A composition map is an image whose intensities for each pixel are the + accumulated X-ray quanta *under the curve(s)* of a set of peaks. + + These element-specific EDS maps are NXimage_r_set instances + and need to be named with the name of the element from the + element_names field. + + + + + A list of NXpeak instance names whose X-ray quanta + where accumulated for each pixel which yields an element-specific + EDS map. + + + + + + + + + + diff --git a/contributed_definitions/NXem_eels.nxdl.xml b/contributed_definitions/NXem_eels.nxdl.xml new file mode 100644 index 0000000000..d42af5a476 --- /dev/null +++ b/contributed_definitions/NXem_eels.nxdl.xml @@ -0,0 +1,79 @@ + + + + + + + + Number of electron energy loss bins. + + + + + Base class method-specific for Electron Energy Loss Spectroscopy (EELS). + + + + + NXspectrum_set_em specialized for EELS. + + + + + + + + + + Energy loss. + + + + + + + + + Energy loss. + + + + + + + Energy loss. + + + + + + + diff --git a/contributed_definitions/NXem_img.nxdl.xml b/contributed_definitions/NXem_img.nxdl.xml new file mode 100644 index 0000000000..79574ecaa4 --- /dev/null +++ b/contributed_definitions/NXem_img.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Base class for method-specific generic imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. + + + + Which imaging mode was used? + + + + + + + + diff --git a/contributed_definitions/NXem_method.nxdl.xml b/contributed_definitions/NXem_method.nxdl.xml new file mode 100644 index 0000000000..0034919dd4 --- /dev/null +++ b/contributed_definitions/NXem_method.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + + Base class to describe specific analysis methods in electron microscopy. + + This base class represent a template how specialized, deep, and method-specific + base classes can be defined with which an (NXem) application + definition gets equipped with specific groups to document method-specific + processing steps and report analyzed quantities. + + The template base class name :ref:`NXem_method` needs to be changed for each + method e.g. :ref:`NXem_adf`, :ref:`NXem_ebsd`, :ref:`NXem_eels`, :ref:`NXem_eds`. + + + + Details about processing steps. + + + + + + + diff --git a/contributed_definitions/NXem_msr.nxdl.xml b/contributed_definitions/NXem_msr.nxdl.xml new file mode 100644 index 0000000000..aff5c9b71f --- /dev/null +++ b/contributed_definitions/NXem_msr.nxdl.xml @@ -0,0 +1,96 @@ + + + + + + Base class for collecting a session with a real electron microscope. + + For collecting data and experiments which are simulations of an + electron microscope use the :ref:`NXem_sim` base class. + + + + (Meta)data of the microscope and the lab in which it stands. + + This em_lab group differs from potential em_lab groups inside + :ref:`NXevent_data_em` instances in that here the more static descriptions + are kept while changing, i.e. time-dependent pieces of information are + logged, via the em_lab group inside the desired number of instances + of NXevent_data_em. + + While using an :ref:`NXevent_data_em` instance, users should store only those + settings about a component which are relevant to understand the current + state of the component. Here, current means for the time interval which + the event covers (as it is detailed via start_time and end_time) timestamps. + + For example it is not relevant to store in each :ref:`NXevent_data_em` + electron_source group again the details of the gun type and the manufacturer + but only the high-voltage value and that only if it is different from the value + that is specified in the em_lab section for the static settings. + + In effect, this defines an information inference hierarchy which starts + in an individual :ref:`NXevent_data_em` instance followed by a probing of the + static section. + + + + Given name of the microscope at the hosting institution. + This is an alias. Examples could be NionHermes, Titan, JEOL, + Gemini, etc. + + + + + Location of the lab or place where the instrument is installed. + Using GEOREF is preferred. + + + + + + + + + + Description of the type of the detector. + + Electron microscopes have typically multiple detectors. + Different technologies are in use like CCD, scintillator, + direct electron, CMOS, or image plate to name but a few. + + + + Instrument-specific alias/name + + + + + + + + + + diff --git a/contributed_definitions/NXem_sim.nxdl.xml b/contributed_definitions/NXem_sim.nxdl.xml new file mode 100644 index 0000000000..66282e001d --- /dev/null +++ b/contributed_definitions/NXem_sim.nxdl.xml @@ -0,0 +1,60 @@ + + + + + + + Base class for simulating electron microscopy relevant beam-matter interaction. + + The concept behind this base class is to keep it as generic as possible + that simulations of electron/ion beam interaction with matter can be + represented. This base class is envisioned as the twin of the :ref:`NXem_msr` + base class. + + It is an attempt to test the idea if at some point one might even use the + same base class template to describe measurements and computer simulations + of electron microscopy. This idea is attractive because the only practical + difference between a description of a measurement with a microscope and a + computer simulation is that the latter is typically a substantially simplified + representation of the real microscope surplus the focus of the research + in such cases on specific questions. + + Such simplification can be with respect to the optical setup, typically the + ignoring of the fact that the electron beam is produced by a complex setup + of lenses while in simulations often single Einzel lenses are considered. + Dynamics of the environment like temperature fluctuation in a lab, vibrations, + users, and multiple detectors are typically either ignored or reduced in + complexity and number and coming with idealizations to keep the simulations + focused on the specific reason questions and efficiently numerically executable. + + + + Details about the simulation. + + + + + + + diff --git a/contributed_definitions/NXenergydispersion.nxdl.xml b/contributed_definitions/NXenergydispersion.nxdl.xml index def450232e..364f0be756 100644 --- a/contributed_definitions/NXenergydispersion.nxdl.xml +++ b/contributed_definitions/NXenergydispersion.nxdl.xml @@ -1,6 +1,27 @@ - + - + + Subclass of NXelectronanalyser to describe the energy dispersion section of a photoelectron analyser. @@ -15,6 +36,10 @@ Energy of the electrons on the mean path of the analyser. Pass energy for hemispherics, drift energy for tofs. + + This concept is related to term `12.63`_ of the ISO 18115-1:2023 standard. + + .. _12.63: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.63 @@ -31,12 +56,6 @@ measurement point. - - - Size, position and shape of a slit in dispersive analyzer, e.g. entrance and - exit slits. - - Diameter of the dispersive orbit @@ -44,11 +63,78 @@ - Way of scanning the energy axis (fixed or sweep). + Way of scanning the energy axis - - + + + constant :math:`\Delta E` mode, where the electron retardation (i.e., the fraction of pass energy to + kinetic energy, :math:`R = (E_K - W/E_p)`, is scanned, but the pass energy :math:`E_p` is kept constant. + Here, :math:`W = e \phi` is the spectrometer work function (with the potential difference :math:`\phi_{\mathrm{sample}}` + between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the + vacuum just outside the surface). + + This mode is often used in XPS/UPS because the energy resolution does not change with + changing energy (due to the constant pass energy). + + Synonyms: constant :math:`\Delta E` mode, constant analyser energy mode, CAE + mode, FAT mode + + This concept is related to term `12.64`_ of the ISO 18115-1:2023 standard. + + .. _12.64: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.64 + + + + + constant :math:`\Delta E/E` mode, where the pass energy is scanned such that the electron retardation + ratio is constant. In this mode, electrons of all energies are decelerated with this same + fixed factor. Thus, the pass energy is proportional to the kinetic energy. This mode is often + used in Auger electron spectroscopy (AES) to improve S/N for high-KE electrons, but this + leads to a changing energy resolution (:math:`\Delta E \sim E_p`) at different kinetic energies. + It can however also be used in XPS. + + Synonyms: constant :math:`\Delta E/E` mode, constant retardation ratio mode, CRR + mode, FRR mode + + This concept is related to term `12.66`_ of the ISO 18115-1:2023 standard. + + .. _12.66: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.66 + + + + + In the fixed energy (FE) mode, the intensity for one single kinetic energy is measured for a + specified time. This mode is particulary useful during setup or alignment of the + electron analyzer, for analysis of stability of the excitation source or for sample + alignment. + + Since the mode measures intensity as a function of time, the difference in channel signals + is not of interest. Therefore, the signals from all channels are summed. + + Synonyms: FE mode + + + + + Snapshot mode does not involve an energy scan and instead collects data from all channels of + the detector without averaging. The resulting spectrum reflects the energy distribution of + particles passing through the analyzer using the current settings. This mode is commonly used + to position the detection energy at the peak of a peak and record the signal, enabling faster + data acquisition within a limited energy range compared to FAT. Snapshot measurements are + particularly suitable for CCD and DLD detectors, which have multiple channels and can accurately + display the peak shape. While five or nine-channel detectors can also be used for snapshot + measurements, their energy resolution is relatively lower. + + + + + In dither acquisition mode, the kinetic energy of the analyzer is randomly varied by a small value + around a central value and at fixed pass energy. This allows reducing or removing inhomogeneities + of the detector efficiency, such as e.g. imposed by a mesh in front of the detector. + Mostly relevant for CCD/DLD type of detectors. + + @@ -56,6 +142,12 @@ Length of the tof drift electrode + + + Size, position and shape of a slit in dispersive analyzer, e.g. entrance and + exit slits. + + Deflectors in the energy dispersive section @@ -66,4 +158,23 @@ Individual lenses in the energy dispersive section + + + + Specifies the position of the energy dispesive elemeent by pointing to the last + transformation in the transformation chain in the NXtransformations group. + + + + + Collection of axis-based translations and rotations to describe the location and + geometry of the energy dispersive element as a component in the instrument. + Conventions from the NXtransformations base class are used. In principle, + the McStas coordinate system is used. The first transformation has to point + either to another component of the system or . (for pointing to the reference frame) + to relate it relative to the experimental setup. Typically, the components of a system + should all be related relative to each other and only one component should relate to + the reference coordinate system. + + diff --git a/contributed_definitions/NXevent_data_em.nxdl.xml b/contributed_definitions/NXevent_data_em.nxdl.xml index f650af3648..eecaf041f6 100644 --- a/contributed_definitions/NXevent_data_em.nxdl.xml +++ b/contributed_definitions/NXevent_data_em.nxdl.xml @@ -1,165 +1,171 @@ - + - + + - Metadata and settings of an electron microscope for scans and images. - - The need for such a structuring of data is evident from the fact that - electron microscopes are dynamic. Oftentimes it suffices to calibrate the - instrument at the start of the session. Subsequently, data - (images, spectra, etc.) can be collected. Users may wish to take only - a single scan or image and complete their microscope session; however - - frequently users spend much longer at the microscope, recalibrate, - and take multiple data items (scans, images, spectra) each coming - with own detector and on-the-fly processing settings and calibration. - - For the single data item use case one may argue that the need for additional - grouping is redundant. Instead, the metadata could equally be stored inside - the respective groups of the top-level mandatory NXinstrument group. - On the flip side, even for a session with a single image it would also not - harm to nest the data. - - In fact, oftentimes scientists feel that there is a need to store details - about eventual drift of the specimen in its holder (if such data is available) - or record changes to the lens excitations caused or apertures used. - Although current microscopes are usually equipped with stabilization - systems for many of the individual components, it can still be useful - to store time-dependent data in detail. - - Another reason if not a need for more finely granularizable options for - storing time-dependent data, is that over the course of a session one may - reconfigure the microscope. What is a reconfiguration? This could be the - change of an aperture mode because a scientist may first collect an image - with some aperture and then choose a different one. As the aperture affects - the electron beam it will affect the system. - - Let aside for a moment the technology and business models, an EM could be - monitored (and will likely become so more in the future) for streaming out - spatio-temporal details about its components, locations of objects - and eventually applied stimuli and positioning of the specimen. - - Some snapshot or integrated data from this stream are relevant for - understanding signal genesis and electron/ion beam paths. In such a generic - case it might be necessary to sync these streaming data with those intervals - in time when specific measurements are taken (spectra collected, - images taken, diffraction images indexed on-the-fly). - - Theoretically, an instrument and specimen should be considered as dynamic. - Scientists often report or feel (difficult to quantify) observations that - microscopes *perform differently* across sessions, without sometimes being - able to identify clear root causes. Users of the instrument may consider - such conditions impractical and thus either abort their session or try to - bring the microscope first into a state where conditions are considered - stable and of high enough quality for collecting data. - - In all these cases it is practical to store time-dependent data of the - instrument state not in the respective instrument component groups - of the top-level NXinstrument but in a sort of a log of event data. - This is the idea behind the NXevent_data_em snapshot containers. - - The base class requires a start time and an optional end time. - The end time should be added to represent a time interval - (remind the idea of the instrument state stream) during which the - scientist considered the microscope (especially ebeam and specimen) - as stable enough. + Base class to store state and (meta)data of events with an electron microscopy. + + Electron microscopes are dynamic. Scientists often report that microscopes + *perform differently* across sessions, that they perform differently from + one day or another. In some cases, root causes for performance differences + are unclear. Users of the instrument may consider such conditions impractical, + or *too poor*, and thus abort their session. Alternatively, users may try to + bring the microscope into a state where conditions are considered better + or of whatever high enough quality for continuing the measurement. + + In all these use cases in practice it would be useful to have a mechanism + whereby time-dependent data of the instrument state can be stored and + documented with an interoperable representation. Indeed, how a session on an + electron microscope is spent depends strongly on the research question, + the user, and the imaging modalities used. + + :ref:`NXevent_data_em` represents an instance to describe and serialize flexibly + whatever is considered a time interval during which the instrument is + considered as stable enough for performing a task with the microscope. + Examples of such tasks are the collecting of data (images and spectra) or + the calibrating of some component of the instrument. Users may wish to take + only a single scan or image and complete their microscope session thereafter. + Alternatively, users are working for much longer time at the microscope, + perform recalibrations in between and take several scans (of different + regions-of-interest of the specimen), or they explore the state of the + microscope for service or maintenance tasks. + + :ref:`NXevent_data_em` serves the harmonization and documentation of this situation + with providing three key sections: Firstly, there is a header section whose + purpose is to contextualize and identify the event instance in time. + Secondly, there is a data and metadata section where individual data collections + can be stored using a standardized representation. + Finally, there is a section called em_lab which mirrors the structure of the + em_lab(NXinstrument) section in :ref:`NXem_base`. + + The idea of the first, the event-based em_lab section, is to document the + state of the microscope as it was during the event. The idea of the other, + the NXem application based em_lab(NXinstrument) section is to keep all those + pieces of information which are static in the sense that they are the same + across multiple :ref:`NXevent_data_em` instance. This reduces the amount of pieces of + information that have to be stored repetitively. + + We are aware of the fact that given the variety how an electron microscope + is used, there is a need for a flexible and adaptive documentation system. + At the same time we are also convinced though that just because one has + different requirements for some specific aspect under the umbrella of settings + to an electron microscope, this does not necessarily warrant that one has to + cook up an own schema. + + Instead, the electron microscopy community should work towards reusing schema + components as frequently as possible. This will enable that there is at all + not only a value of harmonizing electron microscopy research content but also + the technical possibility to build services around such harmonized + pieces of information. + + Arguably it is oftentimes tricky to specify a clear time interval when the + microscope is *stable enough*. Take for instance the acquisition of an image + or a stack of spectra. Having to deal with instabilities is a common theme in + electron microscopy practice. Numerical protocols can be used during data + post-processing to correct for some of the instabilities. + A few exemplar references to provide an overview on the subject is + available in the literature: + + * `C. Ophus et al. <https://dx.doi.org/10.1016/j.ultramic.2015.12.002>`_ + * `B. Berkels et al. <https://doi.org/10.1016/j.ultramic.2018.12.016>`_ + * `L. Jones et al. <https://link.springer.com/article/10.1186/s40679-015-0008-4>`_ For specific simulation purposes, mainly in an effort to digitally repeat - or simulate the experiment, it is tempting to consider dynamics of the - instrument, implemented as time-dependent functional descriptions of - e.g. lens excitations, beam shape functions, trajectories of groups of - electrons, or detector noise models. - - For now the preferred strategy to handle these cases is through - customizations of the specific fields within NXevent_data_em instances. - - Another alternative could be to sample finer, eventually dissimilarly along - the time axis; however this may cause situations where an NXevent_data_em - instance does not contain specific measurements - (i.e. images, spectra of scientific relevance). - - In this case one should better go for a customized application definition - with a functional property description inside members (fields or groups) - in NXevent_data_em instances or resort to a specific application definition - which documents metadata for tracking explicitly electrons - (with ray-tracing based descriptors/computational geometry descriptors) - or tracking of wave bundles. - - This perspective on more subtle time-dependent considerations of electron - microscopy can be advantageous also for storing details of time-dependent - additional components that are coupled to and/or synced with instrument. - - Examples include cutting-edge experiments where the electron beam gets - coupled/excited by e.g. lasers. In this case, the laser unit should be - registered under the top-level NXinstrument section. Its spatio-temporal - details could be stored inside respective groups of the NXinstrument. + or simulate the experiment, it is tempting to consider dynamics of the instrument, + implemented as time-dependent functional descriptions of e.g. lens excitations, + beam shape functions, trajectories of groups of electrons and ions, + or detector noise models. This warrants to document the time-dependent + details of individual components of the microscope + as is implemented in :ref:`NXevent_data_em`. - ISO 8601 time code with local time zone offset to UTC information included when the snapshot time interval started. - If the user wishes to specify an interval of time that the snapshot should represent during which the - instrument was stable and configured using specific settings and calibrations, the start_time is the - start (left bound of the time interval) while the end_time specifies the end (right bound) of the time interval. + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval started. If the user wishes to specify an + interval of time that the snapshot should represent during which the instrument + was stable and configured using specific settings and calibrations, + the start_time is the start (left bound of the time interval) while + the end_time specifies the end (right bound) of the time interval. - ISO 8601 time code with local time zone offset to UTC included when the snapshot time interval ended. - If the user does not wish to specify a time interval, end_time should have the same value as start_time. + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval ended. - + - Reference to a specific state and setting of the microscope components. + Identifier of a specific state and setting of the microscope. Which specific event/measurement type. Examples are: - * In-lens/backscattered electron, usually has quadrants - * Secondary_electron, image, topography, fractography, overview images - * Backscattered_electron, image, Z or channeling contrast (ECCI) - * Bright_field, image, TEM - * Dark_field, image, crystal defects - * Annular dark field, image (medium- or high-angle), TEM - * Diffraction, image, TEM, or a comparable technique in the SEM - * Kikuchi, image, SEM EBSD and TEM diffraction - * X-ray spectra (point, line, surface, volume), composition EDS/EDX(S) - * Electron energy loss spectra for points, lines, surfaces, TEM - * Auger, spectrum, (low Z contrast element composition) - * Cathodoluminescence (optical spectra) - * Ronchigram, image, alignment utility specifically in TEM - * Chamber, e.g. TV camera inside the chamber, education purposes. + * In-lens/backscattered electron, usually has quadrants + * Secondary_electron, image, topography, fractography, overview images + * Backscattered_electron, image, Z or channeling contrast (ECCI) + * Bright_field, image, TEM + * Dark_field, image, crystal defects + * Annular dark field, image (medium- or high-angle), TEM + * Diffraction, image, TEM, or a comparable technique in the SEM + * Kikuchi, image, SEM EBSD and TEM diffraction + * X-ray spectra (point, line, surface, volume), composition EDS/EDX(S) + * Electron energy loss spectra for points, lines, surfaces, TEM + * Auger, spectrum, (low Z contrast element composition) + * Cathodoluminescence (optical spectra) + * Ronchigram, image, alignment utility specifically in TEM + * Chamber, e.g. TV camera inside the chamber, education purposes. + + This field may also be used for storing additional information + about the event. For which there is at the moment no other place. + + In the long run such free-text field description should be avoided as + they are difficult to machine-interpret. Instead, reference should be given + to refactoring these descriptions into structured metadata. + The reason why in this base class the field event_type is nonetheless kept + is to offer a place whereby practically users may enter data for + follow-up modifications to support arriving at an improved :ref:`NXevent_data_em` base class. - + + + + + - The detector or set of detectors that was used to collect this signal. - The name of the detector has to match the names used for available - detectors, i.e. if the instrument has an *ebsd_camera* - named detector, instances of NXimage_em_kikuchi should use - *ebsd_camera* as the detector name. + (Meta)data of the dynamics and changes of the microscope during the event. - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + diff --git a/contributed_definitions/NXevent_data_em_set.nxdl.xml b/contributed_definitions/NXevent_data_em_set.nxdl.xml index 030f21c18c..5d5a3a986c 100644 --- a/contributed_definitions/NXevent_data_em_set.nxdl.xml +++ b/contributed_definitions/NXevent_data_em_set.nxdl.xml @@ -1,11 +1,49 @@ - + - + + - Container to hold NXevent_data_em instances of an electron microscope session. + Base class for a set of :ref:`NXevent_data_em` instances. - An event is a time interval during which the microscope was configured, - considered stable, and used for characterization. + Members of the set are instances of :ref:`NXevent_data_em`. These have an associated + time interval during which the conditions were considered stable and + fit enough for purpose. + + Which temporal granularity is adequate depends on the situation and + research question. Using a model which enables a collection of events offers + the most flexible way to cater for both experiments with controlled electron + beams in a real microscope or the simulation of such experiments or + individual aspects of such experiments. + + diff --git a/contributed_definitions/NXfabrication.nxdl.xml b/contributed_definitions/NXfabrication.nxdl.xml new file mode 100644 index 0000000000..dd1f7f5dce --- /dev/null +++ b/contributed_definitions/NXfabrication.nxdl.xml @@ -0,0 +1,50 @@ + + + + + + Details about a component as it is defined by its manufacturer. + + + + Company name of the manufacturer. + + + + + Version or model of the component named by the manufacturer. + + + + + Ideally, (globally) unique persistent identifier, i.e. + a serial number or hash identifier of the component. + + + + + Free-text list with eventually multiple terms of + functionalities which the component offers. + + + diff --git a/contributed_definitions/NXfiber.nxdl.xml b/contributed_definitions/NXfiber.nxdl.xml new file mode 100644 index 0000000000..ef32b14a45 --- /dev/null +++ b/contributed_definitions/NXfiber.nxdl.xml @@ -0,0 +1,217 @@ + + + + + + + + + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the core material is given. + + + + + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the cladding material is given. + + + + + Length of the spectrum vector (e.g. wavelength or energy) for which the + attenuation curve is given. + + + + + An optical fiber, e.g. glass fiber. + + Specify the quantities that define the fiber. Fiber optics are described in + detail [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4), for + example. + + + + Descriptive name or brief description of the fiber, e.g. by stating its + dimension. The dimension of a fiber can be given as 60/100/200 which + refers to a core diameter of 60 micron, a clad diameter of 100 micron, + and a coating diameter of 200 micron. + + + + + Type/mode of the fiber. Modes of fiber transmission are shown in + Fig. 5 [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4). + + + + + + + + + + Type of dispersion. + + + + + + + + + + Spectrum-dependent (or refractive index-dependent) dispersion of the + fiber. Specify in ps/nm*km. + + + + + + + + Core of the fiber, i.e. the part of the fiber which transmits the light. + + + + Specify the material of the core of the fiber. + + + + + Core diameter of the fiber (e.g. given in micrometer). + + + + + Complex index of refraction of the fiber. Specify at given wavelength + (or energy, wavenumber etc.) values. + + + + + + + + + + Core of the fiber, i.e. the part of the fiber which transmits the light. + + + + Specify the material of the core of the fiber. + + + + + Clad diameter of the fiber (e.g. given in micrometer). + + + + + Complex index of refraction of the fiber. Specify at given wavelength + (or energy, wavenumber etc.) values. + + + + + + + + + + Coating of the fiber. + + + + Specify the material of the coating of the fiber. + + + + + Outer diameter of the fiber (e.g. given in micrometer). + + + + + + Length of the fiber. + + + + + Spectral range for which the fiber is designed. Enter the minimum and + maximum values (lower and upper limit) of the wavelength range. + + + + + + + Unit of spectral array (e.g. nanometer or angstrom for wavelength, or + electronvolt for energy etc.). + + + + + + Transfer rate of the fiber (in GB per second). + + + + GB/s + + + + + + Numerical aperture (NA) of the fiber. + + + + + Wavelength-dependent attenuation of the fiber (specify in dB/km). + + + + + + + Use dB/km. + + + + + + + + + Power loss of the fiber in percentage. + + + + + Acceptance angle of the fiber. + + + diff --git a/contributed_definitions/NXgraph_edge_set.nxdl.xml b/contributed_definitions/NXgraph_edge_set.nxdl.xml new file mode 100644 index 0000000000..bd59185528 --- /dev/null +++ b/contributed_definitions/NXgraph_edge_set.nxdl.xml @@ -0,0 +1,121 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The number of edges. + + + + + A set of (eventually directed) edges which connect nodes of a graph. + + Use as a direct child of an instance of :ref:`NXgraph_root`. + Alternatively, use depends_on to specify which instance + of :ref:`NXgraph_root` is defined by this instance. + + + + Specify which instance of :ref:`NXgraph_root` this :ref:`NXgraph_edge_set` + refers to. + + + + + Total number of edges, counting eventual bidirectional edges only once. + + + + + Integer which specifies the first index to be used for distinguishing + edges. Identifiers are defined either implicitly or explicitly. + + For implicit indexing the identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + For explicit indexing use the field identifier. For implicit indexing, + consult :ref:`NXcg_primitive_set` to get guidance how to set identifier_offset. + + + + + Integer used to distinguish edges for explicit indexing. + + + + + + + + Specifier whether each edge is non-directional, one-directional, + or bidirectional. Use the smallest available binary representation + which can store three different states: + + * 0 / state 0x00 is non-directional + * 1 / state 0x01 is one-directional + * 2 / state 0x02 is bi-directional + + + + + + + + Pairs of node/vertex identifier. Each pair represents the connection + between two nodes. The order in the pair encodes eventual directionality. + + In the case that an edge is non- or bi-directional, storing + node identifier in ascending order is preferred. + + In the case that an edge is one-directional, node identifier should be + stored such that the identifier of the source node is the first entry + and the identifier of the target is the second entry in the pair. + + + + + + + + + A human-readable qualifier which type or e.g. class instance the + edge is an instance of. + + + + + + + + A human-readable label/caption/tag of each edge. + + + + + + diff --git a/contributed_definitions/NXgraph_node_set.nxdl.xml b/contributed_definitions/NXgraph_node_set.nxdl.xml new file mode 100644 index 0000000000..d234097946 --- /dev/null +++ b/contributed_definitions/NXgraph_node_set.nxdl.xml @@ -0,0 +1,118 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of nodes of the graph. + + + + + The dimensionality of the graph. Eventually use one for categorical. + + + + + A set of nodes representing members of a graph. + + Use as a direct child of an instance of :ref:`NXgraph_root`. + Alternatively, use depends_on to specify which instance + of NXgraph_root is defined by this instance. + + + + Specify which instance of :ref:`NXgraph_root` this :ref:`NXgraph_node_set` + refers to. + + + + + About which space does the graph make statements. + + + + + + + + + Dimensionality of the space about which the graph makes statements. + Use only when value of the field space is euclidean. + + + + + + + + + + Number of nodes of the graph. + + + + + Integer which specifies the first index to be used for distinguishing + nodes. Identifiers are defined either implicitly or explicitly. + + For implicit indexing the identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + For explicit indexing use the field identifier. For implicit indexing, + consult :ref:`NXcg_primitive_set` to get guidance how to set identifier_offset. + + + + + Integer used to distinguish nodes for explicit indexing. + + + + + + + + A human-readable qualifier which type or e.g. class instance the + node is an instance of. An example: a NeXus application definition is a + graph, more specifically a hierarchical directed labelled property graph. + Instances which are groups like :ref:`NXgraph_node_set` could have an is_a + qualifier reading :ref:`NXgraph_node_set`. + + + + + + + + A human-readable label/caption/tag of each node. + + + + + + diff --git a/contributed_definitions/NXgraph_root.nxdl.xml b/contributed_definitions/NXgraph_root.nxdl.xml new file mode 100644 index 0000000000..2459a00695 --- /dev/null +++ b/contributed_definitions/NXgraph_root.nxdl.xml @@ -0,0 +1,35 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + An instance of a graph. + + + + diff --git a/contributed_definitions/NXibeam_column.nxdl.xml b/contributed_definitions/NXibeam_column.nxdl.xml index 43c53282ed..949635731f 100644 --- a/contributed_definitions/NXibeam_column.nxdl.xml +++ b/contributed_definitions/NXibeam_column.nxdl.xml @@ -1,31 +1,59 @@ - + - + + + + - Container for components of a focused-ion-beam (FIB) system. + Base class for a set of components equipping an instrument with FIB capabilities. - FIB capabilities turn especially scanning electron microscopes - into specimen preparation labs. FIB is a material preparation - technique whereby portions of the sample are illuminated with a - focused ion beam with controlled intensity intense enough and with - sufficient ion momentum to remove material in a controllable manner. + Focused-ion-beam (FIB) capabilities turn especially scanning electron microscopes + into specimen preparation labs. FIB is a material preparation technique whereby + portions of the sample are illuminated with a focused ion beam with controlled + intensity. The beam is intense enough and with sufficient ion momentum to + remove material in a controlled manner. The fact that an electron microscope with FIB capabilities has needs a - second gun with own relevant control circuits, focusing lenses, and - other components, warrants an own base class to group these components - and distinguish them from the lenses and components for creating and - shaping the electron beam. + second gun with own relevant control circuits, focusing lenses, and other + components, warrants the definition of an own base class to group these + components and distinguish them from the lenses and components for creating + and shaping the electron beam. For more details about the relevant physics and application examples consult the literature, for example: - * `L. A. Giannuzzi et al. <https://doi.org/10.1007/b101190>`_ - * `E. I. Preiß et al. <https://link.springer.com/content/pdf/10.1557/s43578-020-00045-w.pdf>`_ - * `J. F. Ziegler et al. <https://www.sciencedirect.com/science/article/pii/S0168583X10001862>`_ - * `J. Lili <https://www.osti.gov/servlets/purl/924801>`_ + * `L. A. Giannuzzi et al. <https://doi.org/10.1007/b101190>`_ + * `E. I. Preiß et al. <https://link.springer.com/content/pdf/10.1557/s43578-020-00045-w.pdf>`_ + * `J. F. Ziegler et al. <https://www.sciencedirect.com/science/article/pii/S0168583X10001862>`_ + * `J. Lili <https://www.osti.gov/servlets/purl/924801>`_ - - + + + The source which creates the ion beam. @@ -57,43 +85,72 @@ Which ionized elements or molecular ions form the beam. - Examples are gallium, helium, neon, argon, krypton, + Examples are gallium, helium, neon, argon, krypton, or xenon, O2+. - + + + Average/nominal flux + + + Average/nominal brightness - + + Charge current - + + + Ion acceleration voltage upon source exit and + entering the vacuum flight path. + + + - Ion acceleration voltage upon source exit and entering the vacuum flight path. + To be defined more specifically. Community suggestions are welcome. - - Affine transformation which detail the arrangement in the microscope relative to - the optical axis and beam path. + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. + + Individual characterization results for the position, shape, and characteristics of the ion beam. - NXtransformations should be used to specify the location or position + :ref:`NXtransformations` should be used to specify the location or position at which details about the ion beam are probed. + diff --git a/contributed_definitions/NXidentifier.nxdl.xml b/contributed_definitions/NXidentifier.nxdl.xml new file mode 100644 index 0000000000..1639d1dfaf --- /dev/null +++ b/contributed_definitions/NXidentifier.nxdl.xml @@ -0,0 +1,59 @@ + + + + + + An identifier for a (persistent) resource, e.g., a DOI or orcid. + + + + The service by which the resouce can be resolved. + If the service is not in the list a simple `url` may be used. + The `url` can either be a resolving service for the `identifier` + or a fully qualified identification in itself. + + + + + + + + + + + + + + The unique code, IRI or hash to resolve this reference. + Typically, this is stated by the service which is considered a complete + identifier, e.g., for a DOI it's something of the form `10.1107/S1600576714027575` + or `https://doi.org/10.1107/S1600576714027575`, which are both resolvable. + + + + + True if the identifier is persistent (i.e., unique and available indefinetely), + False otherwise. + + + diff --git a/contributed_definitions/NXimage_c_set.nxdl.xml b/contributed_definitions/NXimage_c_set.nxdl.xml new file mode 100644 index 0000000000..a5fd36a7ca --- /dev/null +++ b/contributed_definitions/NXimage_c_set.nxdl.xml @@ -0,0 +1,247 @@ + + + + + + + + Number of images in the (hyper)stack. + + + + + Number of pixel per image in the slowest direction. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Specialized base class container for reporting a set of images in reciprocal space. + + In practice, complex numbers are encoded via some formatted pair of real values. + Typically, fast Algorithms for computing Fourier Transformations (FFT) are + used to encode images in reciprocal (frequency) space. FFT libraries are used + for implementing the key functionalities of these mathematical operations. + + Different libraries use different representations and encoding of the + image computed. Details can be found in the respective sections of the + typical FFT libraries: + + * `FFTW by M. Frigo and S. G. Johnson <https://www.fftw.org/fftw3_doc/Tutorial.html#Tutorial>`_ + * `Intel MKL by the Intel Co. <https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2023-0/fourier-transform-functions.html>`_ + * `cuFFT by the NVidia Co. <https://docs.nvidia.com/cuda/cufft/index.html>`_ + + Users are strongly advised to inspect carefully which specific conventions + their library uses to be able to store and modify the implementation of their + code so that the serialized representations as it is detailed + here for NeXus matches with their intention. + + One- and two-dimensional FFTs should use the stack(NXdata) instances. + Three-dimensional FFTs should use the hyperstack(NXdata) instances. + + + + + Image stack. + + + + Image intensity of the real part. + + + + + + + + + + Image intensity of the imaginary part. + + + + + + + + + + Magnitude of the image intensity. + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + + Pixel coordinate center along j direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along i direction. + + + + + + + Coordinate along i direction. + + + + + + + Image hyperstack. + + + + Image intensity of the real part. + + + + + + + + + + + Image intensity of the imaginary part. + + + + + + + + + + + Magnitude of the image intensity. + + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + Pixel coordinate center along k direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along j direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along i direction. + + + + + + + Coordinate along i direction. + + + + + diff --git a/contributed_definitions/NXimage_r_set.nxdl.xml b/contributed_definitions/NXimage_r_set.nxdl.xml new file mode 100644 index 0000000000..86a6c6311e --- /dev/null +++ b/contributed_definitions/NXimage_r_set.nxdl.xml @@ -0,0 +1,100 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Specialized base class container for reporting a set of images in real space. + + + + + Image (stack). + + + + Image intensity values. + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + Pixel coordinate center along y direction. + + + + + + + Coordinate along y direction. + + + + + + Pixel coordinate center along x direction. + + + + + + + Coordinate along x direction. + + + + + diff --git a/contributed_definitions/NXimage_r_set_diff.nxdl.xml b/contributed_definitions/NXimage_r_set_diff.nxdl.xml new file mode 100644 index 0000000000..98919c2ed9 --- /dev/null +++ b/contributed_definitions/NXimage_r_set_diff.nxdl.xml @@ -0,0 +1,179 @@ + + + + + + + + Number of scanned points. Scan point may have none, one, or more pattern. + + + + + Number of diffraction pattern. + + + + + Number of pixel per pattern in the slow direction. + + + + + Number of pixel per pattern in the fast direction. + + + + + Base class specialized for reporting a cuboidal stack of diffraction pattern. + + Diffraction pattern, whether they were simulated or measured are the raw data + for computational workflows to characterize the phase and orientation + of crystalline regions in matter. + + Steps of post-processing the diffraction patterns should be documented using + method-specific specialized base classes. All eventual post-processing of + resulting orientation maps (2D or 3D) should be documented via :ref:`NXms_recon`. + + To implement an example how this base class can be used we focused in FAIRmat + on Kikuchi diffraction pattern here specifically the research community + of Electron Backscatter Diffraction (EBSD). + + For this reason, this base class and related :ref:`NXem_base` classes extend the + work of `M. A. Jackson et al. <https://doi.org/10.1186/2193-9772-3-4>`_ + (one of the developers of DREAM.3D) and the H5OINA public file format developed by + `P. Pinard et al. <https://doi.org/10.1017/S1431927621006103>`_ with Oxford Instruments. + + Kikuchi pattern are typically collected with FIB/SEM microscopes, + for two- and three-dimensional orientation microscopy. + + For a detailed overview of these techniques see e.g. + + * `M. A. Groeber et al. <https://doi.org/10.1186/2193-9772-3-5>`_ + * `A. J. Schwartz et al. <https://doi.org/10.1007/978-1-4757-3205-4>`_ + * `P. A. Rottman et al. <https://doi.org/10.1016/j.mattod.2021.05.003>`_ + + Serial-sectioning demands a recurrent sequence of ion milling and measuring. + This suggests that each serial section is at least an own NXevent_data_em + instance. The three-dimensional characterization as such demands a computational + step where the maps for each serial section get cleaned, aligned, and registered + into an image stack. This image stack represents a digital model of the + inspected microstructural volume. Often this volume is called a (representative) + volume element (RVE). Several software packages exists for performing + these post-processing tasks. + + This example may inspire users of other types of diffraction methods. + + + + Category which type of diffraction pattern is reported. + + + + + + + + Collected diffraction pattern as an image stack. As raw and closest to the + first retrievable measured data as possible, i.e. do not use this + container to store already averaged, filtered or whatever post-processed + pattern unless these are generated unmodifiably in such manner by the + instrument given the way how the instrument and control software + was configured for your microscope session. + + + + Array which resolves the scan point to which each pattern belongs. + + Scan points are evaluated in sequence starting from scan point zero + until scan point n_sc - 1. Evaluating the cumulated of this array + decodes which pattern in intensity belongs to which scan point. + + Take an example with three scan points: The first scan point has one + pattern, the second has three pattern, the last scan point has no + pattern. In this case the scan_point_identifier are 0, 1, 1, 1. + The length of the scan_point_identifier array is four because four + pattern were measured in total. + + In most cases usually one pattern is averaged by the detector for + some amount of time and then reported as one pattern. + + + + + + + + Intensity of the diffraction pattern. + + + + + + + + + + Pattern intensity + + + + + + + Pattern are enumerated starting from 0 to n_p - 1. + + + + + + + Pattern identifier + + + + + + + diff --git a/contributed_definitions/NXimage_set.nxdl.xml b/contributed_definitions/NXimage_set.nxdl.xml new file mode 100644 index 0000000000..24b397f91b --- /dev/null +++ b/contributed_definitions/NXimage_set.nxdl.xml @@ -0,0 +1,75 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Base class for reporting a set of images. + + This class provides a base vocabulary to be used for specialized :ref:`NXimage_set` + base classes like :ref:`NXimage_r_set` and :ref:`NXimage_c_set`. + + + + Details how NXdata instance inside instance of (specialized) + :ref:`NXimage_set` were processed from the detector readings/raw data. + + + + Resolvable data artifact (e.g. filename) from which the all values in + the :ref:`NXdata` instances in this :ref:`NXimage_set` were loaded + during parsing. + + + + + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXimage_set` instance. + + + + + Link or name of an :ref:`NXdetector` instance with which the data were + collected. + + + + + + diff --git a/contributed_definitions/NXimage_set_em_adf.nxdl.xml b/contributed_definitions/NXimage_set_em_adf.nxdl.xml deleted file mode 100644 index a9658fe2a9..0000000000 --- a/contributed_definitions/NXimage_set_em_adf.nxdl.xml +++ /dev/null @@ -1,113 +0,0 @@ - - - - - - - Number of images - - - - - Number of pixel per image in the slow direction - - - - - Number of pixel per image in the fast direction - - - - - Container for reporting a set of annular dark field images. - - - - Details about how the images were processed from the detector readings. - - - - Commercial or otherwise given name to the program which was used - to process detector data into the adf image(s). - - - - Program version plus build number, commit hash, or description - of an ever persistent resource where the source code of the program - and build instructions can be found so that the program - can be configured in such a manner that the result file - is ideally recreatable yielding the same results. - - - - - - Annulus inner half angle - - - - - Annulus outer half angle - - - - - - Annular dark field images. - - - - Image intensity values. - - - - - - - - - - Image intensities - - - - - Image identifier - - - - - - - Image ID. - - - - - - Pixel center of mass position y-coordinates. - - - - - - - Label for the y axis. - - - - - - Pixel center of mass position x-coordinates. - - - - - - - Label for the x axis. - - - - - diff --git a/contributed_definitions/NXimage_set_em_bf.nxdl.xml b/contributed_definitions/NXimage_set_em_bf.nxdl.xml deleted file mode 100644 index 066b2b3e46..0000000000 --- a/contributed_definitions/NXimage_set_em_bf.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of images taken in bright field mode. - - - - diff --git a/contributed_definitions/NXimage_set_em_bse.nxdl.xml b/contributed_definitions/NXimage_set_em_bse.nxdl.xml deleted file mode 100644 index 6c99db5649..0000000000 --- a/contributed_definitions/NXimage_set_em_bse.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of back-scattered electron images. - - - - diff --git a/contributed_definitions/NXimage_set_em_chamber.nxdl.xml b/contributed_definitions/NXimage_set_em_chamber.nxdl.xml deleted file mode 100644 index 09973347dc..0000000000 --- a/contributed_definitions/NXimage_set_em_chamber.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for images recorded with e.g. a TV camera in the microscope chamber. - - - - diff --git a/contributed_definitions/NXimage_set_em_df.nxdl.xml b/contributed_definitions/NXimage_set_em_df.nxdl.xml deleted file mode 100644 index f9c37cab96..0000000000 --- a/contributed_definitions/NXimage_set_em_df.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of images taken in dark field mode. - - - - diff --git a/contributed_definitions/NXimage_set_em_diffrac.nxdl.xml b/contributed_definitions/NXimage_set_em_diffrac.nxdl.xml deleted file mode 100644 index 7065a8a981..0000000000 --- a/contributed_definitions/NXimage_set_em_diffrac.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of diffraction images. - - - - diff --git a/contributed_definitions/NXimage_set_em_ecci.nxdl.xml b/contributed_definitions/NXimage_set_em_ecci.nxdl.xml deleted file mode 100644 index 820ec8869f..0000000000 --- a/contributed_definitions/NXimage_set_em_ecci.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting back-scattered electron channeling contrast images. - - - - diff --git a/contributed_definitions/NXimage_set_em_kikuchi.nxdl.xml b/contributed_definitions/NXimage_set_em_kikuchi.nxdl.xml deleted file mode 100644 index 42cfa824a7..0000000000 --- a/contributed_definitions/NXimage_set_em_kikuchi.nxdl.xml +++ /dev/null @@ -1,327 +0,0 @@ - - - - - - - Number of scan points, one pattern per scan point. - - - - - Number of pixel per Kikuchi pattern in the slow direction - - - - - Number of pixel per Kikuchi pattern in the fast direction - - - - - Electron backscatter diffraction (EBSD) Kikuchi pattern. - - The container can also store data related to a post-processing of these - Kikuchi pattern, which is the backbone of orientation microscopy - especially in materials science and materials engineering. - - Based on a fuse of the `M. A. Jackson et al. <https://doi.org/10.1186/2193-9772-3-4>`_ - of the DREAM.3D community and the open H5OINA format of Oxford Instruments - `P. Pinard et al. <https://doi.org/10.1017/S1431927621006103>`_ - - EBSD can be used, usually with FIB/SEM microscopes, for three-dimensional - orientation microscopy. So-called serial section analyses. For a detailed - overview of these techniques see e.g. - - * `M. A. Groeber et al. <https://doi.org/10.1186/2193-9772-3-5>`_ - * `A. J. Schwartz et al. <https://doi.org/10.1007/978-1-4757-3205-4>`_ - * `P. A. Rottman et al. <https://doi.org/10.1016/j.mattod.2021.05.003>`_ - - With serial-sectioning this involves however always a sequence of - measuring, milling. In this regard, each serial section (measuring) and milling - is an own NXevent_data_em instance and thus there such a three-dimensional - characterization should be stored as a set of two-dimensional data, - with as many NXevent_data_em instances as sections were measured. - - These measured serial sectioning images need virtually always post-processing - to arrive at the aligned and cleaned image stack respective digital - microstructure representation as (a representative) volume element. - Several software packages are available for this post-processing. - For now we do not consider metadata of these post-processing steps - as a part of this base class. - - - - Collected Kikuchi pattern as an image stack. - - - - - - - - - - Kikuchi pattern intensity - - - - - - - - - - Kikuchi pattern identifier - - - - - - - - - - Label for the y axis - - - - - - - - - - Label for the x axis - - - - - - - Which pixel primitive shape is used. - - - - - - - - - The prescribed step size. First value is for the slow changing, - second value is for the fast changing dimension. - - - - - - - - - OIM, orientation imaging microscopy. - Post-processing of the Kikuchi pattern to identify orientations. - - - - - - - - - - - - - - - - - - - Details about the background correction applied to each Kikuchi pattern. - - - - - - How are Kikuchi bands detected - - - - - - - - - - - - - - - - - - How many bands were detected in the pattern. - - - - - - - - - - Lattice planes used as reflectors for indexing pattern - in electron-backscatter diffraction (EBSD). - One collection for each reflector. - - - - Crystallography unit cell parameters a, b, and c - - - - - - - - Crystallography unit cell parameters alpha, beta, and gamma - - - - - - - - - - - - - - - - - - - Crystallographic space group - - - - - Laue group - - - - - Numeral identifier for each phase. The value 0 is reversed for the unknown - phase. - - - - - Name of the phase/alias. - - - - - - Miller indices :math:`(hkl)[uvw]`. - - - - - - - - - - How are pattern being indexed? - - - - - - - - Minimum number of bands required to index the pattern - - - - - - - - Which return value did the indexing algorithm yield for each pattern. - - * Details about bad pixels - * Too high angular deviation - * No solution - * Not analyzed - * Success - * Unexpected errors - - - - - - - - Labels referring to the phase_identifier for each pattern (from reflectors) that - matched best. - - - - - - - - - - - - - - - - - - - - - Free-text description for instrument specific settings - - - - - How is the camera signal binned. - First the number of pixel along the slow direction. - Second the number of pixel along the fast direction. - - - - - - - - - - - - - Average number of patterns taken on average. - - - - - Wall-clock time the acquisition took. - - - - - Fraction of successfully indexed pattern of the set. - - - - diff --git a/contributed_definitions/NXimage_set_em_ronchigram.nxdl.xml b/contributed_definitions/NXimage_set_em_ronchigram.nxdl.xml deleted file mode 100644 index 8ab388cf25..0000000000 --- a/contributed_definitions/NXimage_set_em_ronchigram.nxdl.xml +++ /dev/null @@ -1,12 +0,0 @@ - - - - - Container for reporting a set of images related to a ronchigram. - - Ronchigrams are specifically used in transmission electron microscopy - to judge the settings for the aberration corrections and alignment. - - - - diff --git a/contributed_definitions/NXimage_set_em_se.nxdl.xml b/contributed_definitions/NXimage_set_em_se.nxdl.xml deleted file mode 100644 index a5ab12200b..0000000000 --- a/contributed_definitions/NXimage_set_em_se.nxdl.xml +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - - Number of images. - - - - - Number of pixels along the slow scan direction (often y). - - - - - Number of pixels along the fast scan direction (often x). - - - - - Container for reporting a set of secondary electron images. - - Secondary electron images are one of the most important signal especially - for scanning electron microscopy in materials science and engineering, for - analyses of surface topography, getting an overview of the analysis region, - or fractography. - - - - Collected secondary electron images (eventually as an image stack). - - - - - - - - - - Secondary electron image intensity - - - - - - - - - - Image identifier - - - - - - - - - - Label for the y axis - - - - - - - - - - Label for the x axis - - - - - - - Physical dimensions of the region-of-interest on - the specimen surface which the image covers. - The first and second number are the coordinates for the - minimum edge, the third and fourth number are the coordinates - for the maximum edge of the rectangular ROI. - - - - - - - - - - How many frames were averaged to obtain the image. - - - - - - - - Bias voltage applied to the e.g. Faraday cage in front of the - SE detector to attract or repell secondary electrons below - a specific kinetic energy. - - - - - Container to store relevant settings affecting beam path, - magnification, and working_distance - - - - - Scan rotation is an option offer by most control software. - - - - - Tilt correction is an option offered by most control software of SEMs - to apply an on-the-fly processing of the image to correct for - the excursion of objects when characterized with SE images - on samples whose surface normal is tilted about an axis perpendicular - to the optical axis. - - - - Was the option switched active or not. - - - - - - Dynamic focus is an option offered by most control software of SEMs - to keep the image also focused when probing locations on the specimens - beyond those for which the lens system was calibrated. - - - - Was the option switched active or not. - - - - diff --git a/contributed_definitions/NXinteraction_vol_em.nxdl.xml b/contributed_definitions/NXinteraction_vol_em.nxdl.xml index a6beeb6482..f8d8a669f2 100644 --- a/contributed_definitions/NXinteraction_vol_em.nxdl.xml +++ b/contributed_definitions/NXinteraction_vol_em.nxdl.xml @@ -1,36 +1,56 @@ - + - + + - Base class for storing details about a modelled shape of interaction volume. + Base class for describing the interaction volume of particle-matter interaction. - The interaction volume is mainly relevant in scanning electron microscopy - when the sample is thick enough so that the beam is unable to illuminate - through the specimen. - Computer models like Monte Carlo or molecular dynamics / electron beam - interaction simulations can be used to qualify and/or quantify the shape of - the interaction volume. + Computer models like Monte Carlo or molecular dynamics / electron- or ion-beam + interaction simulations can be used to qualify and (or) quantify the shape of + the interaction volume. Results of such simulations can be summary statistics + or single-particle resolved sets of trajectories. Explicit or implicit descriptions are possible. - * An implicit description is via a set of electron/specimen interactions - represented ideally as trajectory data from the computer simulation. - * An explicit description is via an iso-contour surface using either - a simulation grid or a triangulated surface mesh of the approximated - iso-contour surface evaluated at specific threshold values. - Iso-contours could be computed from electron or particle fluxes through - an imaginary control surface (the iso-surface). - Threshold values can be defined by particles passing through a unit control - volume (electrons) or energy-levels (e.g. the case of X-rays). - Details depend on the model. - * Another explicit description is via theoretical models which may - be relevant e.g. for X-ray spectroscopy + * An implicit description is via a set of electron/specimen interactions + represented ideally as trajectory data from the computer simulation. + * An explicit description is via an iso-contour surface using either + a simulation grid or a triangulated surface mesh of the approximated + iso-contour surface evaluated at specific threshold values. + Iso-contours could be computed from electron or particle fluxes through + an imaginary control surface (the iso-surface). + Threshold values can be defined by particles passing through a unit control + volume (electrons) or energy-levels (e.g. the case of X-rays). + Details depend on the model. + * Another explicit description is via theoretical models which may + be relevant e.g. for X-ray spectroscopy Further details on how the interaction volume can be quantified is available in the literature for example: - * `S. Richter et al. <https://doi.org/10.1088/1757-899X/109/1/012014>`_ - * `J. Bünger et al. <https://doi.org/10.1017/S1431927622000083>`_ + * `S. Richter et al. <https://doi.org/10.1088/1757-899X/109/1/012014>`_ + * `J. Bünger et al. <https://doi.org/10.1017/S1431927622000083>`_ + * `J. F. Ziegler et al. <https://doi.org/10.1007/978-3-642-68779-2_5>`_ diff --git a/contributed_definitions/NXion.nxdl.xml b/contributed_definitions/NXion.nxdl.xml index a066144821..fd2fbf03e2 100644 --- a/contributed_definitions/NXion.nxdl.xml +++ b/contributed_definitions/NXion.nxdl.xml @@ -1,14 +1,34 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays. - Maximum number of atoms/isotopes allowed per (molecular) ion - (fragment). + Maximum number of atoms/isotopes allowed per (molecular) ion (fragment). @@ -20,18 +40,33 @@ Set of atoms of a molecular ion or fragment in e.g. ToF mass spectrometry. + + + A unique identifier whereby such an ion can be referred to + via the service offered as described in identifier_type. + + + + + How can the identifier be resolved? + + + + + - Ion type (ion species) identifier. The identifier zero - is reserved for the special unknown ion type. + Ion type (ion species) identifier. + + The identifier zero is reserved for the special unknown ion type. - A vector of isotope hash values. - These values have to be stored in an array, sorted in decreasing order. - The array is filled with zero hash values indicating unused places. - The individual hash values are built with the following hash function: + A vector of isotope hash values. These values have to be stored in an array, + sorted in decreasing order. The array is filled with zero hash values + indicating unused places. The individual hash values are built with the + following hash function: The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` the number of protons and :math:`N` the number of neutrons @@ -40,11 +75,51 @@ Z and N have to be 8-bit unsigned integers. For the rationale behind this `M. Kühbach et al. (2021) <https://doi.org/10.1017/S1431927621012241>`_ - - + + + - + + + A supplementary row vector which decodes the isotope_vector into + a human-readable matrix of nuclids with the following formatting: + + The first row specifies the isotope mass number, i.e. using the hashvalues + from the isotope_vector this is :math:`Z + N`. As an example for a + carbon-14 isotope the number is 14. + The second row specifies the number of protons :math:`Z`, e.g. 6 for the + carbon-14 example. This row matrix is thus mapping the notation of + using superscribed isotope mass and subscripted number of protons + to identify isotopes. + Unused places filling up to n_ivecmax need to be filled with zero. + + + + + + + + + Color code used for visualizing such ions. + + + + + Assumed volume of the ion. + + In atom probe microscopy this field can be used to store the reconstructed + volume per ion (average) which is typically stored in range files and will + be used when building a tomographic reconstruction of an atom probe + dataset. + + + + + Charge of the ion. + + + Signed charge state of the ion in multiples of electron charge. @@ -58,9 +133,9 @@ These file formats do not document the charge state explicitly. They report the number of atoms of each element per molecular ion surplus the mass-to-charge-state-ratio interval. - With this it is possible to recover the charge state only for - specific molecular ions as the accumulated mass of the molecular ion - is defined by the isotopes, which without knowing the charge leads + With this information it is possible to recover the charge state only + for specific molecular ions as the accumulated mass of the molecular ion + is defined by the isotopes, which without knowing the charge, leads to an underconstrained problem. Details on ranging can be found in the literature: `M. K. Miller <https://doi.org/10.1002/sia.1719>`_ @@ -68,20 +143,21 @@ Human-readable ion type name (e.g. Al +++) - The string should consists of ASCII UTF-8 characters, - ideally using LaTeX notation to specify the isotopes, ions, and charge - state. Examples are 12C + or Al +++. - Although this name may be human-readable and intuitive, parsing such - names becomes impractical for more complicated cases. Therefore, the - isotope_vector should be the preferred machine-readable format to use. + The string should consists of UTF-8 characters, ideally using LaTeX + notation to specify the isotopes, ions, and charge state. + Examples are 12C + or Al +++. + + To ease automated parsing isotope_vector should be the + preferred machine-readable information used. - + - Associated lower (mqmin) and upper (mqmax) bounds of + Associated lower (mqmin) and upper (mqmax) bounds of the mass-to-charge-state ratio interval(s) [mqmin, mqmax] - (boundaries included) for which the respective ion is labelled - as an ion of the here referred to ion_type. + (boundaries inclusive). This field is primarily of interest + for documenting :ref:`NXprocess` steps of indexing a ToF/mass-to-charge + state histogram. diff --git a/contributed_definitions/NXisocontour.nxdl.xml b/contributed_definitions/NXisocontour.nxdl.xml new file mode 100644 index 0000000000..9c8e030913 --- /dev/null +++ b/contributed_definitions/NXisocontour.nxdl.xml @@ -0,0 +1,72 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the description. + + + + + Computational geometry description of isocontouring/phase-fields in Euclidean space. + + Iso-contouring algorithms such as MarchingCubes and others are frequently + used to segment d-dimensional regions into regions where intensities are + lower or higher than a threshold value, the so-called isovalue. + + Frequently in computational materials science phase-field methods are + used which generate data on discretized grids. Isocontour algorithms + are often used in such context to pinpoint the locations of microstructural + features from this implicit phase-field-variable-based description. + + One of the key intentions of this base class is to provide a starting point + for scientists from the phase-field community (condensed matter physicists, + and materials engineers) to incentivize that also phase-field simulation + data could be described with NeXus, provided base classes such as the this one + get further extend according to the liking of the phase-field community. + + + + The dimensionality of the space in which the isocontour is embedded. + + + + + + + + + The discretized grid on which the iso-contour algorithm operates. + + + + + The threshold or iso-contour value. + + + diff --git a/contributed_definitions/NXiv_bias.nxdl.xml b/contributed_definitions/NXiv_bias.nxdl.xml new file mode 100644 index 0000000000..a23dd89762 --- /dev/null +++ b/contributed_definitions/NXiv_bias.nxdl.xml @@ -0,0 +1,192 @@ + + + + + + Application definition for bias devices. + + + + Applied a voltage between tip and sample. + + + + + The ratio between the tunneling current at the sample surface and the bias voltage + applied between the sample and the tip. + + + + + Calibration of the Bias output (V/V). + + + + + Allows compensating for an offset in Bias. Hardware parameter offset. + + + + + Sets the amplitude (in physical units of the modulated signal) of the sine + modulation. + + + + + Bias sweeps while measuring arbitrary channels with I(V) curves. + + + + + Select the channels to record. + + + + + When selected, the Bias voltage returns to the initial value (before starting the sweep) at + the end of the spectroscopy measurement (default). When not selected, Bias remains at the + last value of the sweep. This is useful e.g. when combining several sweep segments. Example + for an automated measurement (using Programming Interface): switch off Z-Controller, start + spectroscopy sweep segments (only fwd sweep, no reset bias), set bias back to initial value, + switch on Z-Controller. + + + + + Select whether to record the Z position during Z averaging time at the end of + the sweep (after Z control time) and store the average value in the header of + the file when saving. Using this option increases the sweep time by Z averaging + time. + + + + + Select whether to set the Lock-In to run during the measurement. When using this + feature, make sure the Lock-In is configured correctly and settling times are + set to twice the Lock-In period at least. This option is ignored when Lock-In is + already running. This option is disabled if the Sweep Mode is MLS and the flag + to configure the Lock-In per segment in the Multiline segment editor is set. + + + + + Time during which the spectroscopy data are acquired and averaged. + + + + + Number of sweeps to measure and average. + + + + + The first bias values of the sweep. + + + + + The last bias values of the sweep. + + + + + Define the sweep number of points, that is, the maximum spectrum resolution eq. + Bias window divide by Num Pixel. + + + + + Duration over which the Z position is recorded and averaged before and after the + sweep (the latter only if Record final Z position is selected in the Advanced + section). After the initial Z averaging time, if Z-Controller to Hold is + selected in the Advanced section, the Z-Controller is set to hold and the tip is + placed at the previously averaged Z position (plus Z offset). + + + + + Select a filter to smooth the displayed data. When saving, if any filter + selected, filtered data are saved to file along with the unfiltered data. + + + + + Filter order of a dynamic filter or width (in number of points) for the gaussian + filter. + + + + + Cutoff frequency for dynamic filters. + + + + + Offset added to the initial averaged position Zaver before starting to sweep. + This parameter is disabled when Z-Controller to Hold is deselected in the + Advanced section. The LED “Alt” next to the Z offset indicates if an alternate + Z-controller setpoint is enabled. + + + + + time to wait after changing the bias to the next level and before starting to + acquire data. + + + + + Time to wait after the sweep has finished and the bias is ramped to the initial + value. + + + + + Time during which the Z-Controller is enabled once a sweep has finished. When + averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled for this + duration between each sweep. After the last sweep, it will wait the specified + time before continuing a running scan. This ensures each sweep reliably starts + from the same position. This parameter is disabled when Z-Controller to Hold is + deselected in the Advanced section. + + + + + Maximum rate at which the bias changes (before, during and after sweeping). + (V/s) + + + + + Select whether to measure the backward (return) sweep or the forward only. + + + + + Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. + It is selected by default. When deselected, Z-offset and Z-control time + parameters are disabled. + + + diff --git a/contributed_definitions/NXiv_temp.nxdl.xml b/contributed_definitions/NXiv_temp.nxdl.xml new file mode 100644 index 0000000000..d61426c0c3 --- /dev/null +++ b/contributed_definitions/NXiv_temp.nxdl.xml @@ -0,0 +1,103 @@ + + + + + + + + Number of different temperature setpoints used in the experiment. + + + + + Number of different voltage setpoints used in the experiment. + + + + + Application definition for temperature-dependent IV curve measurements. + + In this application definition, times should be specified always together + with an UTC offset. + + This is the application definition describing temperature dependent IV curve + measurements. For this a temperature is set. After reaching the temperature, + a voltage sweep is performed. For each voltage a current is measured. + Then, the next desired temperature is set and an IV measurement is performed. + + + + + + + + + + + Descriptive name or ideally (globally) unique persistent identifier. + + + + + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + + The purpose of the field is to offer materials database systems an + opportunity to parse the relevant elements without having to interpret + these from the sample history or from other data sources. + + + + + + + Describes an environment setup for a temperature-dependent IV measurement experiment. + + The temperature and voltage must be present as independently scanned controllers and + the current sensor must also be present with its readings. + + + + + + + + + This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. + There should also be two more fields called temperature and voltage containing the setpoint values. + There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension + equal to the number of voltage setpoints. + + + + + + + + + + + + diff --git a/contributed_definitions/NXlab_electro_chemo_mechanical_preparation.nxdl.xml b/contributed_definitions/NXlab_electro_chemo_mechanical_preparation.nxdl.xml new file mode 100644 index 0000000000..c34bb25db5 --- /dev/null +++ b/contributed_definitions/NXlab_electro_chemo_mechanical_preparation.nxdl.xml @@ -0,0 +1,188 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Grinding and polishing of a sample using abrasives in a wet lab. + Manual procedures, electro-chemical, vibropolishing. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + + + + + + + + + + A preparation step performed by a human or a robot/automated system. + + + + + + + + Carrier/plate used on which the abrasive/(lubricant) mixture was applied. + + + + + + Medium on the abrasive_medium_carrier (cloth or grinding plate) + whereby material is abrasively weared. + + + + + + Lubricant + + + + + + Qualitative statement how the revelation of the machine was configured. + If the rotation was controlled manually, e.g. by turning knobs + choose manual and estimate the nominal average rotation. + If the rotation was controlled via choosing from a fixed set + of options offered by the machine choose fixed and + specify the nominal rotation. + If programmed use rotation_history (e.g. for automated/robot systems). + + + + + + + + + + + Qualitative statement how the (piston) force with which the sample + was pressed into/against the abrasive medium was controlled if at all. + If the force was controlled manually e.g. by turning knobs + choose manual and estimate nominal average force. + If the force was controlled via choosing from a fixed set + of options offered by the machine choose fixed and + specify the nominal force. + If programmed use force_history (e.g. for automated/robot systems). + + + + + + + + + + + Qualitative statement for how long (assuming regular uninterrupted) + preparation at the specified conditions the preparation step was + applied. + + + + + + + + + + + Turns per unit time. + + + + + + Force exerted on the sample to press it into the abrasive. + + + + + + Seconds + + + + + Qualitative statement how the material removal was characterized. + + + + + + + + + + How thick a layer was removed. + + + + + + + A preparation step performed by a human or a robot/automated system + with the aim to remove residual abrasive medium from the specimen surface. + + + + + diff --git a/contributed_definitions/NXlab_sample_mounting.nxdl.xml b/contributed_definitions/NXlab_sample_mounting.nxdl.xml new file mode 100644 index 0000000000..98dc044ce2 --- /dev/null +++ b/contributed_definitions/NXlab_sample_mounting.nxdl.xml @@ -0,0 +1,93 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Embedding of a sample in a medium for easing processability. + + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + + + + + + + + + + Qualitative statement how the sample was mounted. + + + + + + + + + Type of material. + + + + + + + + + Electrical conductivity of the embedding medium. + + + + + diff --git a/contributed_definitions/NXlens_em.nxdl.xml b/contributed_definitions/NXlens_em.nxdl.xml index 1fdfbb4e41..1d44e5f5f4 100644 --- a/contributed_definitions/NXlens_em.nxdl.xml +++ b/contributed_definitions/NXlens_em.nxdl.xml @@ -1,15 +1,39 @@ - + - + + + - Description of an electro-magnetic lens or a compound lens. + Base class for an electro-magnetic lens or a compound lens. - For NXtransformations the origin of the coordinate system is placed - in the center of the lens - (its polepiece, pinhole, or another point of reference). - The origin should be specified in the NXtransformations. + For :ref:`NXtransformations` the origin of the coordinate system is placed + in the center of the lens (its polepiece, pinhole, or another + point of reference). The origin should be specified in the :ref:`NXtransformations`. - For details of electro-magnetic lenses in the literature see e.g. `L. Reimer <https://doi.org/10.1007/978-3-540-38967-5>`_ + For details of electro-magnetic lenses in the literature + see e.g. `L. Reimer <https://doi.org/10.1007/978-3-540-38967-5>`_ @@ -29,42 +53,58 @@ For manufacturer names and identifiers use respective manufacturer fields. - - - Name of the manufacturer who built/constructed the lens. - - - - - - Hardware name, hash identifier, or serial number that was given by the - manufacturer to identify the lens. - - + + + - Ideally an identifier, persistent link, or free text which gives further details - about the lens. + Ideally an identifier, persistent link, or free text which + gives further details about the lens. - Excitation voltage of the lens. For dipoles it is a single number. For higher - orders, it is an array. + Excitation voltage of the lens. + + For dipoles it is a single number. + For higher order multipoles, it is an array. - Excitation current of the lens. For dipoles it is a single number. For higher - orders, it is an array. + Excitation current of the lens. + + For dipoles it is a single number. + For higher order multipoles, it is an array. - + + + This field should be used when the exact voltage or current of the lens + is not directly controllable as the control software of the microscope + does not enable or was not configured to display these values. + + In this case this value field should be used and the value + from the control software stored as is. + + Although this value does not document the exact physical voltage or + excitation, it can still give useful context to reproduce the lens setting, + which, provided a properly working instrument and software sets the lens + into a similar state to the technical level possible when no more information + is available physically or accessible legally. + + + Specifies the position of the lens by pointing to the last transformation in the transformation chain in the NXtransformations group. - + Collection of axis-based translations and rotations to describe the diff --git a/contributed_definitions/NXlens_opt.nxdl.xml b/contributed_definitions/NXlens_opt.nxdl.xml new file mode 100644 index 0000000000..e3bf121dac --- /dev/null +++ b/contributed_definitions/NXlens_opt.nxdl.xml @@ -0,0 +1,185 @@ + + + + + + + + + Size of the wavelength array for which the refractive index of the material + is given. + + + + + Size of the wavelength array for which the refractive index of the coating + is given. + + + + + Size of the wavelength array for which the reflectance or transmission of + the lens is given. + + + + + Description of an optical lens. + + + + Type of the lens (e.g. concave, convex etc.). + + + + + + + + + + + + + + + If you chose 'other' as type specify what it is. + + + + + Is it a chromatic lens? + + + + + Diameter of the lens. + + + + + Properties of the substrate material of the lens. If the lens has a + coating specify the coating material and its properties in 'coating'. + + + + Specify the substrate material of the lens. + + + + + Thickness of the lens substrate at the optical axis. + + + + + Complex index of refraction of the lens material. Specify at given + wavelength (or energy, wavenumber etc.) values. + + + + + + + + + + + If the lens has a coating describe the material and its properties. + Some basic information can be found e.g. [here] + (https://www.opto-e.com/basics/reflection-transmission-and-coatings). + If the back and front side of the lens are coated with different + materials, use separate COATING(NXsample) fields to describe the coatings + on the front and back side, respectively. For example: + coating_front(NXsample) and coating_back(NXsample). + + + + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + + + + + Describe the coating material (e.g. MgF2). + + + + + Thickness of the coating. + + + + + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + + + + + + + + + + Reflectance of the lens at given spectral values. + + + + + + + + Transmission of the lens at given spectral values. + + + + + + + + Focal length of the lens on the front side (first value), i.e. where the + beam is incident, and on the back side (second value). + + + + + + + + Curvature radius of the lens. + Instead of 'FACE' in the name of this field, the user is advised to + specify for which surface (e.g. front or back) the curvature is provided: + e.g. curvature_front or curvature_back. The front face is the surface on + which the light beam is incident, while the back face is the one from + which the light beam exits the lens. + + + + + Abbe number (or V-number) of the lens. + + + diff --git a/contributed_definitions/NXlockin.nxdl.xml b/contributed_definitions/NXlockin.nxdl.xml new file mode 100644 index 0000000000..2484b5007c --- /dev/null +++ b/contributed_definitions/NXlockin.nxdl.xml @@ -0,0 +1,151 @@ + + + + + + Base classes definition for lock in devices. + + + + Hardware manufacturers and type of lockin amplifier. + + + + + By mixing the input signal (STS signal) with the modulated signal (such as Bias) + and comparing it with the reference signal, they are enhanced and the effects of + noise interference are reduced, resulting in more accurate measurements. + + + + + if Lock-in -- Bias Divider 1/10 or 1/100, Bias divider = + V(ref)/[V(ref)+V(input)] + + + + + Switch the lock-in moulation on or off. + + + + + A modulation signal (such as bias, current et.al.) is a periodic voltage signal, + usually applied to the surface of a sample, which serves to modify the physical + properties of the sample surface and generate weak AC current signals that can + be detected and analysed by instruments such as lock-in amplifiers. + + + + + + Sets the amplitude (in physical units of the modulated signal) of the sine + modulation. + + + + + Sets the frequency of the sine modulation added to the signal to modulate. + + + + + The input signal (STS signal) will be demodulated, in order to determine the amplitude + and phase at the frequency set in the Frequency field or harmonics, such as current, + bias, et.al. + + + + + + The number of signals which will be demodulated. + + + + + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) + + + + + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) + + + + + Sets the cut-off frequency of the low-pass filter (affects the displayed TC (s) + value) for D1. The filter is applied to the demodulated signals (X,Y). + + + + + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Reducing the bandwidth or increasing the order reduces noise on + the demodulated signals, but will require longer settling and measurement times. + + + + + Sets the cut-off frequency of the high-pass filter (affects the displayed TC (s) + value) for D1. The filter is applied to the demodulated signals (X,Y). + + + + + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal of D!. This is used mainly to suppress a DC component of the demodulation + signal, which would lead to a component at modulation frequency in the + demodulated signals. + + + + + Switch on/off the Sync filter on the demodulated signals (X,Y) on or off. + (foreach DemodulatorChannels) + + + + + Reference phase for the sine on the demodulated signal with respect to the + modulation signal. (foreach DemodulatorChannels) + + + + + Time during which the data are acquired and averaged. (for the input filter) + + + + + The order of the harmonic oscillation to detect on the demodulated signals. + (with respect to the modulation frequency) + + + + + Ratio of output signal amplitude to input signal amplitue (V/V). (input gain) + + + diff --git a/contributed_definitions/NXmanipulator.nxdl.xml b/contributed_definitions/NXmanipulator.nxdl.xml index d961e331bc..b76ff14250 100644 --- a/contributed_definitions/NXmanipulator.nxdl.xml +++ b/contributed_definitions/NXmanipulator.nxdl.xml @@ -1,6 +1,27 @@ - + - + + Extension of NXpositioner to include fields to describe the use of manipulators in photoemission experiments. @@ -17,42 +38,185 @@ - Type of manipulator, Hexapod, Rod, etc. + Type of manipulator, Hexapod, Rod, etc. - + - Is cryocoolant flowing through the manipulator? + Cryostat for cooling the sample. - - + + + + + + + + + In case of a fixed or averaged cooling temperature, this is the scalar temperature setpoint. + It can also be a 1D array of temperature setpoints (without time stamps). + + + + + + In the case of an experiment in which the temperature is changed and the setpoints are + recorded with time stamps, this is an array of length m of temperature setpoints. + + + + + + - Temperature of the cryostat (coldest point) + Temperature sensor measuring the sample temperature. - - + + + + + + + + In case of a single or averaged temperature measurement, this is the scalar temperature measured + by the sample temperature sensor. It can also be a 1D array of measured temperatures + (without time stamps). + + + + + + In the case of an experiment in which the temperature changes and is recorded with time stamps, + this is an array of length m of temperatures. + + + + + - Power in the heater for temperature control. + Device to heat the sample. - - + + + + + + + + In case of a fixed or averaged heating power, this is the scalar heater power. + It can also be a 1D array of heater powers (without time stamps). + + + + + + In the case of an experiment in which the heater power is changed and recorded with time stamps, + this is an array of length m of temperature setpoints. + + + + + + + In case of a fixed or averaged temperature, this is the scalar temperature setpoint. + It can also be a 1D array of temperature setpoints (without time stamps). + + + + + + In the case of an experiment in which the temperature is changed and the setpoints are + recorded with time stamps, this is an array of length m of temperature setpoints. + + + + + + - Temperature at the closest point to the sample. This field may also be found in - NXsample if present. + Amperemeter measuring the drain current of the sample and sample holder. - - + + + + + + + + In case of a single or averaged drain current measurement, this is the scalar drain current measured between + the sample and sample holder. It can also be an 1D array of measured currents (without time stamps). + + + + + + In the case of an experiment in which the current changes and is recorded with + time stamps, this is an array of length m of currents. + + + + + - Current to neutralize the photoemission current. This field may also be found in - NXsample if present. + Actuator applying a voltage to sample and sample holder. - - + + + + + + + + + In case of a fixed or averaged applied bias, this is the scalar voltage applied between + sample and sample holder. It can also be an 1D array of voltage setpoints (without time stamps). + + + + + + In the case of an experiment in which the bias is changed and the setpoints are + recorded with time stamps, this is an array of length m of voltage setpoints. + + + + + + - Possible bias of the sample with trespect to analyser ground. This field may - also be found in NXsample if present. + Sensor measuring the voltage applied to sample and sample holder. - + + + + + + + + In case of a single or averaged bias measurement, this is the scalar voltage measured between + sample and sample holder. It can also be an 1D array of measured voltages (without time stamps). + + + + + + In the case of an experiment in which the bias changes and is recorded with + time stamps, this is an array of length m of voltages. + + + + + + + Any additional actuator on the manipulator used to control an external + condition. + + + + + Any additional sensors on the manipulator used to monitor an external condition. + + Class to describe the motors that are used in the manipulator @@ -76,4 +240,5 @@ the reference coordinate system. + diff --git a/contributed_definitions/NXmanufacturer.nxdl.xml b/contributed_definitions/NXmanufacturer.nxdl.xml deleted file mode 100644 index 54f1c8fd22..0000000000 --- a/contributed_definitions/NXmanufacturer.nxdl.xml +++ /dev/null @@ -1,29 +0,0 @@ - - - - - Details about a component as defined by its manufacturer. - - - - Company name of the manufacturer. - - - - - Version or model of the component named by the manufacturer. - - - - - Ideally, (globally) unique persistent identifier, i.e. a serial number or hash - identifier of the component. - - - - - Free-text list with eventually multiple terms of functionalities which the - component offers. - - - diff --git a/contributed_definitions/NXmatch_filter.nxdl.xml b/contributed_definitions/NXmatch_filter.nxdl.xml new file mode 100644 index 0000000000..235169910d --- /dev/null +++ b/contributed_definitions/NXmatch_filter.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + How many different match values does the filter specify. + + + + + Settings of a filter to select or remove entries based on their value. + + + + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + + + + + + + + + Array of values to filter according to method. For example if the filter + specifies [1, 5, 6] and method is whitelist, only entries with values + matching 1, 5 or 6 will be processed. All other entries will be filtered + out. + + + + + + diff --git a/contributed_definitions/NXmpes.nxdl.xml b/contributed_definitions/NXmpes.nxdl.xml index 8f20886ee0..c5f5a45ef3 100644 --- a/contributed_definitions/NXmpes.nxdl.xml +++ b/contributed_definitions/NXmpes.nxdl.xml @@ -1,33 +1,155 @@ - + - + + + + + The symbols used in the schema to specify e.g. dimensions of arrays + + + + Number of data points in the transmission function. + + + This is the most general application definition for multidimensional photoelectron spectroscopy. + + Groups and fields are named according to the + `ISO 18115-1:2023`_ specification as well as the `IUPAC Recommendations 2020`_. + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _IUPAC Recommendations 2020: https://doi.org/10.1515/pac-2019-0404 - + + + + + + + Datetime of the start of the measurement. + Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, + otherwise the local time zone is assumed per ISO8601. - - - - - + + + Datetime of the end of the measurement. + Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, + otherwise the local time zone is assumed per ISO8601. + + + + + Name of the experimental method. + + If applicable, this name should match the terms given by `Clause 11`_ of + the `ISO 18115-1:2023`_ specification. + + Examples include: + * X-ray photoelectron spectroscopy (XPS) + * angle-resolved X-ray photoelectron spectroscopy (ARXPS) + * ultraviolet photoelectron spectroscopy (UPS) + * angle-resolved photoelectron spectroscopy (ARPES) + * hard X-ray photoemission spectroscopy (HAXPES) + * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) + * photoelectron emission microscopy (PEEM) + * electron spectroscopy for chemical analysis (ESCA) + * time-resolved angle-resolved X-ray photoelectron spectroscopy (trARPES) + * spin-resolved angle-resolved X-ray photoelectron spectroscopy (spin-ARPES) + * momentum microscopy + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 + + + + Contact information of at least the user of the instrument or the investigator + who performed this experiment. Adding multiple users if relevant is recommended. + + + + Name of the user. + + + + + Name of the affiliation of the user at the time when the experiment was + performed. + + + - - + + Description of the MPES spectrometer and its individual parts. + + This concept is related to term `12.58`_ of the ISO 18115-1:2023 standard. + + .. _12.58: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 + + + + Overall energy resolution of the MPES instrument + + This concept is related to term `10.7 ff.`_ of the ISO 18115-1:2023 standard. + + .. _10.7 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.7 + + This concept is related to term `10.24`_ of the ISO 18115-1:2023 standard. + + .. _10.24: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 + + + + + + + + + + + + + + + - The source used to generate the primary photons. Properties refer strictly to - parameters of the source, not of the output beam. For example, the energy of the - source is not the optical power of the beam, but the energy of the electron beam - in a synchrotron and so on. + A source used to generate a beam. Properties refer strictly to parameters of the + source, not of the output beam. For example, the energy of the source is not the + optical power of the beam, but the energy of the electron beam in a synchrotron + or similar. + + Note that the uppercase notation in source_TYPE means that multiple sources can + be provided. For example, in pump-probe experiments, it is possible to have both + a `source_probe` and a `source_pump` - + @@ -38,72 +160,128 @@ + + + - - + - Type of probe. In photoemission it's always photons, so the full NIAC list is - restricted. + Specification of type, may also go to name. - - - - - - - - + + + + + + + + - Distance of the point of evaluation of the beam from the sample surface. + The beam emitted by this source. + Should be named with the same appendix, e.g., + for `source_probe` it should refer to `beam_probe`. + Refers to the same concept as /NXentry/NXinstrument/beam_TYPE + and may be linked. - - - - + - - - + + + Properties of the photon beam at a given location. + Should be named with the same appendix as source_TYPE, e.g., + for `source_probe` it should refer to `beam_probe`. + + - Energy resolution of the analyser with the current setting. May be linked from a - NXcalibration. + Distance between the point where the current NXbeam instance is evaluating + the beam properties and the point where the beam interacts with the sample. + For photoemission, the latter is the point where the the centre of the beam + touches the sample surface. - - + + + + + + + The source that emitted this beam. + Should be named with the same appendix, e.g., + for `beam_probe` it should refer to `source_probe`. + Refers to the same concept as /NXentry/NXinstrument/source_TYPE + and may be linked. + Should be specified if an associated source exists. + + + + + + + + + + + + + + + + + + + + + + + - + Scheme of the electron collection column. - - - - - - + + + + - - - + + + + + The size and position of the field aperture inserted in the column. To add additional or other apertures use the APERTURE group of NXcollectioncolumn. - + The size and position of the contrast aperture inserted in the column. To add additional or other apertures use the APERTURE group of NXcollectioncolumn. + + + Size, position and shape of the iris inserted in the column. + + The iris is an aperture in the lens with a variable diameter which can reduce the number of + electrons entering the analyzer. + + To add additional or other slits use the APERTURE group of NXcollectioncolumn. + + + + + + + - + @@ -113,23 +291,30 @@ - - - + + + - Size, position and shape of the entrance slit in dispersive analyzers. To add - additional or other slits use the APERTURE group of NXenergydispersion. + Size, position and shape of the entrance slit in dispersive analyzers. + + To add additional or other slits use the APERTURE group of NXenergydispersion. - + - Size, position and shape of the exit slit in dispersive analyzers. To add - additional or other slits use the APERTURE group of NXenergydispersion. + Size, position and shape of the exit slit in dispersive analyzers. + + To add additional or other slits use the APERTURE group of NXenergydispersion. + + + + + - + Type of electron amplifier in the first amplification step. @@ -138,7 +323,7 @@ - + Description of the detector type. @@ -151,7 +336,46 @@ - + + + + + + + + Contains the raw data collected by the detector before calibration. + The data which is considered raw might change from experiment to experiment + due to hardware pre-processing of the data. + This field ideally collects the data with the lowest level of processing + possible. + + The naming of fields should follow a convention to ensure compatibility. + It is recommend to use the following field names: + + - **pixel_x**: Detector pixel in x direction. + - **pixel_y**: Detector pixel in y direction. + - **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). + - **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). + - **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). + - **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). + - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). + Unit category: NX_ANGLE + - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_ANGLE + - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) + Unit category: NX_LENGTH + - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_LENGTH + - **delay**: Calibrated delay time. Unit category: NX_TIME (s). + - **polarization_angle**: Linear polarization angle of the incoming or + outgoing beam. + Unit category: NX_ANGLE (° or rad) + - **ellipticity**: Ellipticity of the incoming or outgoing beam. + Unit category: NX_ANGLE (° or rad) + - **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT + - **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. + - **external_AXIS**: Describes an axis which is coming from outside the detectors scope. + @@ -164,112 +388,294 @@ - + + + + Manipulator for positioning of the sample. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Device to measure the gas pressure around the sample. + + + + + + + + + - Manipulator for positioning of the sample. + In case of a single or averaged gas pressure measurement, this is the scalar gas pressure around + the sample. It can also be an 1D array of measured pressures (without time stamps). - - - + + + + + In the case of an experiment in which the gas pressure changes and is recorded, + this is an array of length m of gas pressures. + + + + + + + Device to bring low-energy electrons to the sample for charge neutralization + + + + + + + + + + + In case of a fixed or averaged electron current, this is the scalar current. + It can also be an 1D array of output current (without time stamps). + + + + + + In the case of an experiment in which the electron current is changed and + recorded with time stamps, this is an array of length m of current setpoints. + + - + Document an event of data processing, reconstruction, or analysis for this data. Describe the appropriate axis calibrations for your experiment using one or more of the following NXcalibrations - - + + + Calibration event on the energy axis. + + For XPS, the calibration should ideally be performed according to + `ISO 15472:2010`_ specification. + + .. _ISO 15472:2010: https://www.iso.org/standard/74811.html + + - Has an energy calibration been applied? + This is the calibrated energy axis to be used for data plotting. - + + + - This is the calibrated energy axis to be used for data plotting. + This is the calibrated angular axis to be used for data plotting. - - + + - Has an angular calibration been applied? + This is the calibrated spatial axis to be used for data plotting. - + + + - This is the calibrated angular axis to be used for data plotting. + This is the momentum axis to be used for data plotting. - - + + + For energy referencing, the measured energies are corrected for the charging potential + (i.e., the electrical potential of the surface region of an insulating sample, caused by + irradiation) such that those energies correspond to a sample with no surface charge. + Usually, the energy axis is adjusted by shifting all energies uniformally until one + well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. + + This concept is related to term `12.74 ff.`_ of the ISO 18115-1:2023 standard. + + .. _12.74 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 + + - Has an spatial calibration been applied? + Electronic core or valence level that was used for the calibration. + + + + + Reference peak that was used for the calibration. + + For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level - + - This is the calibrated spatial axis to be used for data plotting. + The binding energy (in units of eV) that the specified emission line appeared at, + after adjusting the binding energy scale. + + This concept is related to term `12.16_ ff.`_ of the ISO 18115-1:2023 standard. + + .. _12.16_ ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 - - - + - Has an momentum calibration been applied? + Offset between measured binding energy and calibrated binding energy of the + emission line. - + - This is the momentum axis to be used for data plotting. + This is the calibrated energy axis to be used for data plotting. + + This should link to /entry/data/energy. - - - - + - The chemical formula of the sample. For mixtures use the NXsample_component - group in NXsample instead. - - - - - A descriptor to keep track of the treatment of the sample before entering the - photoemission experiment. Ideally, a full report of the previous operations, in - any format (NXnote allows to add pictures, audio, movies). Alternatively, a - reference to the location or a unique identifier or other metadata file. In the - case these are not available, free-text description. + In the transmission correction, each intensity measurement for electrons of a given + kinetic energy is multiplied by the corresponding value in the relative_intensity + field of the transmission_function. This calibration procedure is used to account for + the different tranmsission efficiencies when using different lens modes. + + + Transmission function of the electron analyser. + + The transmission function (TF) specifies the detection efficiency for electrons of + different kinetic energy passing through the electron analyser. + This can be a link to /entry/instrument/electronanalyser/transmission_function. + + + + + + + + + + + + + + Kinetic energy values + + + + + + + + Relative transmission efficiency for the given kinetic energies + + + + + + - - - Date of preparation of the sample for the XPS experiment (i.e. - cleaving, last annealing). - - - + + + + - Description of the surface preparation technique for the XPS experiment, i.e. - UHV cleaving, in-situ growth, sputtering/annealing etc. Ideally, a full report - of the previous operations, in any format(NXnote allows to add pictures, audio, - movies). Alternatively, a reference to the location or a unique identifier or - other metadata file. In the case these are not available, free-text description. + For samples containing a single pure substance. For mixtures use the + NXsample_component_set and NXsample_component group in NXsample instead. + + + The chemical formula of the sample (using CIF conventions). + + - + - In the case of a fixed temperature measurement this is the scalar temperature of - the sample. In the case of an experiment in which the temperature is changed and - recoded, this is an array of length m of temperatures. This should be a link to - /entry/instrument/manipulator/sample_temperature. + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. - + + @@ -277,15 +683,147 @@ - + + + A set of activities that occurred to the sample prior to/during photoemission + experiment. + + + + Details about the sample preparation for the MPES experiment (e.g. UHV cleaving, + in-situ growth, sputtering/annealing, etc.). + + + + + + Details about the method of sample preparation before the MPES experiment. + + + + + + + Sample temperature (either controlled or just measured). + + + + Temperature sensor measuring the sample temperature. + This should be a link to /entry/instrument/manipulator/temperature_sensor. + + + + + Device to heat the sample. + This should be a link to /entry/instrument/manipulator/sample_heater. + + + + + Cryostat for cooling the sample. + This should be a link to /entry/instrument/manipulator/cryostat. + + + + + + Gas pressure surrounding the sample. + + + + Gauge measuring the gas pressure. + + This should be a link to /entry/instrument/pressure_gauge. + + + + + + Bias of the sample with respect to analyser ground. + + This concept is related to term `8.41`_ of the ISO 18115-1:2023 standard. + + .. _8.41: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:8.41 + + + + Sensor measuring the applied voltage. + + This should be a link to /entry/instrument/manipulator/sample_bias_voltmeter. + + + + + Actuator applying a voltage to sample and sample holder. + + This should be a link to /entry/instrument/manipulator/sample_bias_potentiostat. + + + + + + Drain current of the sample and sample holder. + + + + Amperemeter measuring the drain current of the sample and sample holder. + + This should be a link to /entry/instrument/manipulator/drain_current_amperemeter. + + + + + + Current of low-energy electrons to the sample for charge neutralization. + + + + Flood gun creating a current of low-energy electrons. + + This should be a link to /entry/instrument/flood_gun. + + + - + + + The default NXdata field containing a view on the measured data. + This NXdata field contains a collection of the main relevant fields (axes). + In NXmpes, it is required to provide an energy axis. + If you want to provide additional views on your data, you can additionally use + the generic NXdata group of NXentry. + The other data fields inside this NXdata group should be named according to conventions + to ensure compatibility. We recommened the following field names + for common data fields: + + - **kx**: Calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). + - **ky**: Calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). + - **kz**: Calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). + - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). + Unit category: NX_ANGLE + - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_ANGLE + - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) + Unit category: NX_LENGTH + - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_LENGTH + - **delay**: Calibrated delay time. Unit category: NX_TIME (s). + - **polarization_angle**: Linear polarization angle of the incoming or + outgoing beam. This could be a link to + /entry/instrument/beam/incident_polarization_angle or + /entry/instrument/beam/final_polarization_angle if they exist. + Unit category: NX_ANGLE (° or rad) + - **ellipticity**: Ellipticity of the incoming or outgoing beam. + Could be a link to /entry/instrument/beam/incident_ellipticity or + /entry/instrument/beam/final_ellipticity if they exist. + Unit category: NX_ANGLE (° or rad) + - + Represents a measure of one- or more-dimensional photoemission counts, where the varied axis may be for example energy, momentum, spatial coordinate, pump-probe @@ -293,6 +831,54 @@ actual encoder position in NXinstrument or calibrated axes in NXprocess. + + + Calibrated energy axis. + + This could be a link to either + /entry/process/energy_calibration/calibrated_axis or + /entry/process/energy_correction/calibrated_axis. + + + + The energy can be either stored as kinetic or as binding energy. + + + + + Calibrated kinetic energy axis. + + In case the kinetic energy axis is referenced to the Fermi level :math:`E_F` + (e.g., in entry/process/energy_referencing), kinetic energies :math:`E` are + provided as :math:`E-E_F`. + + This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. + + .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + + + + + Calibrated binding energy axis. + + This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. + + .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + + + + + + + + + The energy can be dispersed according to different strategies. ``energy_depends`` points to + the path of a field defining the calibrated axis on which the energy axis depends. + + For example: + @energy_depends: 'entry/process/energy_calibration' + + diff --git a/contributed_definitions/NXms.nxdl.xml b/contributed_definitions/NXms.nxdl.xml new file mode 100644 index 0000000000..32ab2191b7 --- /dev/null +++ b/contributed_definitions/NXms.nxdl.xml @@ -0,0 +1,532 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of boundaries of the bounding box or primitive to domain. + + + + + Number of parameter required for the chosen orientation parameterization. + + + + + Number of texture components identified. + + + + + Application definition, spatiotemporal characterization of a microstructure. + + + + + An at least as strong as SHA256 hashvalue of the file + that specifies the application definition. + + + + + + NeXus NXDL schema to which this file conforms. + + + + + + + + Ideally, a (globally) unique persistent identifier + for referring to this experiment or computer simulation. + + The identifier is usually defined/issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments to e.g. proposals. + + + + + Free-text description about the workflow (experiment/analysis/simulation). + + Users are strongly advised to detail the sample history in the + respective field and fill rather as completely as possible the fields + of this application definition rather than write details about the + experiment into this free-text description field. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the characterization started. + + + + + ISO 8601 time code with local time zone offset to UTC included + when the characterization ended. + + + + + + + + + + Specify if the (characterization) results/data of this instance of an + application definition are based on the results of a simulation or the + results of a post-processing of measured data to describe + a microstructure. + + The term microstructure is used to describe the spatial arrangement of + crystal defects inside a sample/specimen without demanding necessarily + that this structure is mainly at the micron length scale. + Nanostructure and macrostructure are close synonyms. + Material architecture is a narrow synonym. + + Given that microstructure simulations nowadays more and more consider + the atomic arrangement, this application definition can also be used + to describe features at the scale of atoms. + + + + + + + + + Contact information and eventually details of at least one person + involved in creating this result. This can be the principle investigator + who performed this experiment. Adding multiple users if relevant is recommended. + + + + Given (first) name and surname of the user. + + + + + Name of the affiliation of the user at the point in time + when the experiment was performed. + + + + + Postal address of the affiliation. + + + + + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + + + + + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific service + should also be written in orcid_platform + + + + + Name of the OrcID or ResearcherID where the account + under orcid is registered. + + + + + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + + + + + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope. Student, postdoc, principle investigator, guest + are common examples. + + + + + Account name that is associated with the user in social media platforms. + + + + + Name of the social media platform where the account + under social_media_name is registered. + + + + + + + + Descriptive name or ideally (globally) unique persistent identifier. + + + + + + + Hard link to a location in the hierarchy of the NeXus file + where the data for default plotting are stored. + + + + + Container to hold different coordinate systems conventions. + A least a right-handed Cartesian coordinate system with base vectors + named x, y, and z has to be specified. Each base vector of the + coordinate system should be described with an NXtransformations instance. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The simulated or characterized material volume element aka domain. + At least one instance of geometry required either NXcg_grid, + NXcg_polyhedron_set, or NXcg_point_set. This geometry group needs + to contain details about the boundary conditions. + + + + + + + + A boundary to the volume element. + Either an instance of NXcg_hexahedron_set or of NXcg_ellipsoid_set. + + + + + How many distinct boundaries are distinguished. Value required equal to n_b. + + + + + Name of the boundaries. E.g. left, right, front, back, bottom, top, + + + + + + + + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + + + + + + + + + Collection of microstructural data observed/simulated. + + + + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate + if the identifiers are expected to start from 1 (referred to as + Fortran-/Matlab-) or from 0 (referred to as C-, Python-style index + notation) respectively. + + + + + + Summary quantities which are the result of some post-processing of + the snapshot data (averaging, integrating, interpolating). + Frequently used descriptors from continuum mechanics and thermodynamics + can be used here. A few examples are given. Each descriptor is currently + modelled as an instance of an NXprocess because it is relevant to + understand how the descriptors are computed. + + + + + + + + + + + + + + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + + + + + Iteration or increment counter. + + + + + + + + + + Conceptually distinguished object/feature in the ROI/ + system with some relevance. Instances of NXms_feature_set can + be nested to build a hierarchy of logically-related objects. + + A typical example for MD simulations is to have one + ms_feature_set for the atoms which is the parent to another + ms_feature_set for monomers/molecules/proteins which is then the + parent to another ms_feature_set for the secondary, another feature_set + for the tertiary, and the parent for another feature_set for the + quaternary structure. + + Another typical example from materials engineering is to have + one ms_feature_set for crystals (grains/phases) which serves as + the parent to another ms_feature_set for interfaces between these + crystals which then is the parent for another ms_feature_set to + describe the triple junctions which is then the parent for the + quadruple/higher-order junctions between which connect the + triple lines. + + Another example from discrete dislocation dynamics could be to + have one ms_feature_set for the dislocations (maybe separate + sets for each dislocation type or family) which are then + parents to other ms_feature_set which describe junctions between + dislocations or features along the dislocation line network. + + + + + + Details about the orientation distribution function + within the entire domain. + + + + With which method was the ODF approximated? + + + + + + TO BE DEFINED + + + + + TO BE DEFINED + + + + + Collection of texture components commonly referred to. + + + + Reference to or definition of a coordinate system with + which the definitions are interpretable. + + + + + + + + + + + Parameterized orientations. + + + + + + + + + Name of each texture component, e.g. Cube, Dillamore, Y. + + + + + + + + The portion of orientation space integrated over + to compute the volume fraction. + + + + + + + + The volume fraction of each texture component. + + + + + + + + + + + Details about the disorientation distribution function + within the entire domain. + + + + + Details about the grain boundary character distribution + within the entire domain. + + + + + + + + + + + + + + + + + + diff --git a/contributed_definitions/NXms_feature_set.nxdl.xml b/contributed_definitions/NXms_feature_set.nxdl.xml new file mode 100644 index 0000000000..9938c3b9c6 --- /dev/null +++ b/contributed_definitions/NXms_feature_set.nxdl.xml @@ -0,0 +1,316 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Dimensionality + + + + + Cardinality/number of members/features in the feature set. + + + + + Number of types in the dictionary of human-readable types of features. + + + + + Total number of parent identifier. + + + + + Set of topological/spatial features in materials build from other features. + + + + + + Name (or link?) to another NXms_feature_set which defines features what are + assumed as the parents/super_features of all members in this feature set. + If depends_on is set to "." or this attribute is not defined in an instance + of this application definition, assume that this feature_set instance + represents the root feature_set of the feature tree/graph. + + + + + + + What is the best matching description how dimensional the feature is. + + + + + + + + + + + How many features/members are in this set? + + + + + + The keywords of the dictionary of human-readable types of features. + Using terms from a community-agreed upon controlled vocabulary, e.g. + atom, solute, vacancy, monomer, molecule, anti-site, crowd_ion, + quadruple junction, triple line, disconnection, dislocation, + kink, jog, stacking_fault, homo_phase_boundary, hetero_phase_boundary, + surface, thermal_groove_root, precipitate, dispersoid, pore, crack + is recommended. + + + + + + + + + The integer identifier used to resolve of which type each feature is, + i.e. the values of the dictionary of human-readable types of features. + + + + + + + + For each feature in the set specify the associated number of identifier + to parent features as are resolvable via depends_on. + This array enables to compute the array interval from which details for + specific features can be extracted as if they would be stored in an own + group. + + + + + + + + Concatenated array of parent identifier for each feature (in the sequence) + according to identifier and how the identifier of features in the here + described feature set are defined (implicitly from 0, to c-1 or via explicit + identifier. + + + + + + + + + Integer which specifies the first index to be used for distinguishing + features. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate if the + identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) + or from 0 (referred to as C-, Python-style index notation) respectively. + + + + + Integer used to distinguish features for explicit indexing. + + + + + + + + + Assumptions and parameter to arrive at geometric primitives + to locate zero-dimensional/point-(like) features which are + discretized/represented by points. + + + + + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + + + + + + + Assumptions and parameters to arrive at geometric primitives + to locate one-dimensional/line-like features which are + discretized by polylines. + + + + + + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + + + + + + Assumptions and parameters to arrive at geometric primitives + to locate two-dimensional/interface features which are + discretized by triangulated surface meshes. + + + + + + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + + + + + + Assumptions and parameters to arrive at geometric primitives + to locate three-dimensional/volumetric features which are + discretized by triangulated surface meshes of polyhedra. + + + + + + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + + + + + + + + + + diff --git a/contributed_definitions/NXms_ipf.nxdl.xml b/contributed_definitions/NXms_ipf.nxdl.xml new file mode 100644 index 0000000000..0be3dc81e4 --- /dev/null +++ b/contributed_definitions/NXms_ipf.nxdl.xml @@ -0,0 +1,383 @@ + + + + + + + + + Number of pixel along the z slowest direction. + + + + + Number of pixel along the y slow direction. + + + + + Number of pixel along the x fast direction. + + + + + Number of RGB values along the fastest direction, always three. + + + + + Dimensionality of the mapping (either 2 or 3). + + + + + Base class to store an inverse pole figure (IPF) mapping (IPF map). + + + + Reference to the coordinate system whereby the projection_direction is defined. + + If the field depends_on is not provided but a parent of the instance + of this base class or its specialization defines an :ref:`NXcoordinate_system_set` + and exactly one :ref:`NXcoordinate_system`, the reference points to this system. + + If nothing is provided and none of the above-mentioned references pointing + in a parent, McStas is assumed. + + + + + The direction along which orientations are projected. + + + + + + + + Details about the original grid. + + Here original grid means the one onto which the IPF map was computed + when exported from the tech partner's file format representation. + + + + + Details about the grid onto which the IPF is recomputed. + + Rescaling the visualization of the IPF map may be needed to enable + visualization in specific software tools like H5Web. + The value specifies the fractional change of the spacing between + the original mapping and the scaled one. + + + + + How where orientation values at the location of the output grid + positions computed. + + Nearest neighbour means the orientation of the closed (Euclidean distance) + grid point of the input_grid was taken. + + + + + + + + Inverse pole figure mapping. + + Default inverse pole figure (IPF) plot of the data specific for each + phase. No ipf_mapID instances for non-indexed scan points as these are + by definition assigned the null phase with phase_identifier 0. + Inspect the definition of :ref:`NXcrystal_structure` and its field + phase_identifier for further details. + + Details about possible regridding and associated interpolation + during the computation of the IPF map visualization can be stored + using the input_grid, output_grid, and interpolation fields. + + The main purpose of this map is to offer a normalized default representation + of the IPF map for consumption by a research data management system (RDMS). + This is aligned with the first aim of :ref:`NXms_ipf`, to bring colleagues and + users of IPF maps together to discuss which pieces of information + need to be stored together. We are convinced a step-by-step design and + community-driven discussion about which pieces of information should + and/or need to be included is a practical strategy to work towards an + interoperable description and data model for exchanging IPF maps as specific + community-accepted tools to convey orientation maps. + + With this design the individual RDMS solutions and tools can still continue + to support specific custom data analyses workflow and routes but at least + there is one common understanding which enables also those users who are + not necessarily experts in all the details of the underlying techniques + can understand and thus eventually judge if the dataset is worth to be + reused or repurposed. + + + + + + Inverse pole figure color code for each map coordinate. + + + + + + + + + + Pixel center coordinate calibrated for step size along the z axis of the map. + + + + + + + + + Pixel center coordinate calibrated for step size along the y axis of the map. + + + + + + + + + Pixel center coordinate calibrated for step size along the x axis of the map. + + + + + + + + + + The color code which maps colors into orientation into the fundamental zone. + + For each stereographic standard triangle (SST), i.e. a rendering of the + fundamental zone of the crystal-symmetry-reduced orientation space + SO3, it is possible to define a color model which assigns each point in + the fundamental zone a color. + + Different mapping models are used. These implement (slightly) different + scaling relations. Differences exist across representations of tech partners. + + Differences are which base colors of the RGB color model are placed in + which extremal position of the SST and where the white point is located. + + For further details see: + + * [G. Nolze et al.](https://doi.org/10.1107/S1600576716012942) + * Srikanth Patala and coworkers"'" work and of others. + + Details are implementation-specific and not standardized yet. + + Given that the SST has a complicated geometry, it cannot yet be + visualized using tools like H5Web, which is why for now the matrix + of a rasterized image which is rendered by the backend tool gets + copied into an RGB matrix to offer a default plot. + + + + + + Inverse pole figure color code for each map coordinate. + + + + + + + + + + Pixel along the y-axis. + + + + + + + + + Pixel along the x-axis. + + + + + + + + + diff --git a/contributed_definitions/NXms_ipf_set.nxdl.xml b/contributed_definitions/NXms_ipf_set.nxdl.xml new file mode 100644 index 0000000000..7f490dd84b --- /dev/null +++ b/contributed_definitions/NXms_ipf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_ipf` instances. + + A collection of inverse pole figure approximations. + + + diff --git a/contributed_definitions/NXms_mtex_config.nxdl.xml b/contributed_definitions/NXms_mtex_config.nxdl.xml new file mode 100644 index 0000000000..90e4132bee --- /dev/null +++ b/contributed_definitions/NXms_mtex_config.nxdl.xml @@ -0,0 +1,310 @@ + + + + + + Base class to store the configuration when using the MTex/Matlab software. + + MTex is a Matlab package for texture analysis used in the Materials and Earth Sciences. + See `R. Hielscher et al. <https://mtex-toolbox.github.io/publications>`_ and + the `MTex source code <https://github.com/mtex-toolbox>`_ for details. + + + + Reference frame and orientation conventions. + Consult the `MTex docs <https://mtex-toolbox.github.io/EBSDReferenceFrame.html>`_ for details. + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + + + + + + Settings relevant for generating plots. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + True if MTex renders a scale bar with figures. + + + + + True if MTex renders a grid with figures. + + + + + Code for the function handle used for annotating pole figure plots. + + + + + TODO with MTex developers + + + + + + + + + TODO with MTex developers + + + + + + + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Miscellaneous other settings of MTex. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + + Miscellaneous settings relevant for numerics. + + + + Return value of the Matlab eps command. + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Miscellaneous settings relevant of the system where MTex runs. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Collection of paths from where MTex reads information and code. + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + List of file type suffixes for which MTex assumes + texture/pole figure information. + + + + + List of file type suffixes for which MTex assumes EBSD content. + + + + + diff --git a/contributed_definitions/NXms_odf.nxdl.xml b/contributed_definitions/NXms_odf.nxdl.xml new file mode 100644 index 0000000000..3e9d11dd70 --- /dev/null +++ b/contributed_definitions/NXms_odf.nxdl.xml @@ -0,0 +1,171 @@ + + + + + + + + Number of pixel per varphi section plot along the varphi_one fastest direction. + + + + + Number of pixel per varphi section plot along the capital_phi slow direction. + + + + + Number of pixel per varphi section plot along the varphi_two slowest direction. + + + + + Number of local maxima evaluated in the component analysis. + + + + + Base class to store an orientation distribution function (ODF) computation. + + + + Details about the algorithm used for computing the ODF. + + + + Point group of the crystal structure (International Table of Crystallography) + of the phase for which the here documented phase-dependent ODF was computed. + + + + + Point group assumed for processing-induced *sample symmetries*. + (according to International Table of Crystallography). + + + + + Halfwidth of the kernel. + + + + + Name of the kernel. + + + + + Resolution of the kernel. + + + + + + + Number of local maxima evaluated for the ODF. + + + + + + Euler angle representation of the kth-most maxima of the ODF + in decreasing order of the intensity maximum. + + + + + + + + + Disorientation threshold within which intensity of the ODF + is integrated for the component analysis. + + + + + Integrated ODF intensity within a theta-ball of SO3 about + each location as specified for each location in the order + and reported in the order of these locations. + + + + + + + + + Visualization of the ODF intensity as orthogonal sections through Euler space. + + This is one example of typical default plots used in the texture + community in Materials Engineering. + + Mind that the Euler space is a distorted space. Therefore, equivalent + orientations show intensity contributions in eventually multiple + locations. + + + + + ODF intensity at probed locations relative to + null model of a completely random texture. + + + + + + + + + + Pixel center angular position along the :math:`\varphi_1` direction. + + + + + + + + + Pixel center angular position along the :math:`\varphi_2` direction. + + + + + + + + + Pixel center angular position along the :math:`\Phi` direction. + + + + + + + + diff --git a/contributed_definitions/NXms_odf_set.nxdl.xml b/contributed_definitions/NXms_odf_set.nxdl.xml new file mode 100644 index 0000000000..c21aa36985 --- /dev/null +++ b/contributed_definitions/NXms_odf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_odf` instances. + + A collection of orientation distribution function approximations. + + + diff --git a/contributed_definitions/NXms_pf.nxdl.xml b/contributed_definitions/NXms_pf.nxdl.xml new file mode 100644 index 0000000000..44db61d7b3 --- /dev/null +++ b/contributed_definitions/NXms_pf.nxdl.xml @@ -0,0 +1,111 @@ + + + + + + + + Number of pixel per pole figure in the slow direction. + + + + + Number of pixel per pole figure in the fast direction. + + + + + Base class to store a pole figure (PF) computation. + + + + Details about the algorithm that was used to compute the pole figure. + + + + Point group of the crystal structure of the phase for which the + here documented phase-dependent pole figure was computed + (according to International Table of Crystallography). + + + + + Point group assumed for processing induced *sample symmetries* + (according to International Table of Crystallography). + + + + + Halfwidth of the kernel. + + + + + Miller indices (:math:`(hkl)[uvw]`) to specify the pole figure. + + + + + Resolution of the kernel. + + + + + + Pole figure. + + + + + Pole figure intensity. + + + + + + + + + Pixel center along y direction in the equatorial plane of + a stereographic projection of the unit sphere. + + + + + + + + + Pixel center along x direction in the equatorial plane of + a stereographic projection of the unit sphere. + + + + + + + + diff --git a/contributed_definitions/NXms_pf_set.nxdl.xml b/contributed_definitions/NXms_pf_set.nxdl.xml new file mode 100644 index 0000000000..14a4061d64 --- /dev/null +++ b/contributed_definitions/NXms_pf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_pf` instances. + + A collection of pole figure approximations. + + + diff --git a/contributed_definitions/NXms_recon.nxdl.xml b/contributed_definitions/NXms_recon.nxdl.xml new file mode 100644 index 0000000000..f44d34239a --- /dev/null +++ b/contributed_definitions/NXms_recon.nxdl.xml @@ -0,0 +1,454 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + + The number of crystal projections. + + + + + The number of interface projections. + + + + + The number of assumed triple junction projections aka triple points. + + + + + + The number of crystals. + + + + + The number of interfaces + + + + + The number of triple lines + + + + + The number of quadruple junctions. + + + + + Base class to describe discretized (micro)structural features of a material. + + One instance of this base class can be used to describe the current configuration + the base class does not include time-dependent descriptions for the sake of + clarity and because of the fact that virtually all simulations or experiments + probe time by sampling. Therefore, time-dependent state descriptions should + be realized with creating a set of :ref:`NXms_snapshot_set` with instances of + :ref:`NXms_snapshot` using e.g. :ref:`NXms_recon` base class instances. + + + + + The configuration and parameterization of the reconstruction algorithm + whereby the microstructural features were identified. + + + + + Dimensionality of the analysis. + + This field can be used e.g. by a research data management system + to identify if the described feature set specifies a + one-, two-, or three-dimensional feature set. + + + + + + + + + + Which algorithm is used to reconstruct the features. + + + + + + + + + + + Threshold to define at which disorientation angle to assume + two crystalline regions have a significant orientation difference + which warrants to argue that there is an interface between the + two regions. + + + + + + + + + + + + + Projections of crystals on the sample surface as typically + characterized with optical or electron microscopy. + + + + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Most microscopy techniques support to generate only a two-dimensional + representation (projection) of the characterized material. + + For true volumetric techniques use the specifically + specialized crystals :ref:`NXms_feature_set` instead. + See stereology literature for more details e.g. + E.E. Underwood's book entitled Quantitative Stereology + + + + + Number of crystals. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier used for crystals for explicit indexing. + + + + + + + + How many phases are distinguished + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + + + + + Identifier used for phase for explicit indexing. + + + + + + + + + True, if the crystal makes contact with the edge of the ROI, + false otherwise. + + + + + + + + Average disorientation angle between individual orientation of the + crystal at probed positions (weighted by area of that position) versus + the average disorientation of the crystal. + + + + + + + + + Calibrated area of surrounded by the polyline about each crystal. + + + + + + + + + + Projections of grain or phase boundaries as typically sectioned + with optical or electron microscopy characterization. + + + + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Set of tuples of polyline segments which build the interface. + + + + + + Set of pairs of crystal_identifier resolved via depends_on which + are adjacent to each interface. + + + + + + + + The specific crystal_projections(NXms_feature_set) instance + to resolve crystal identifier. + + + + + + + Set of pairs of triple_point_identifier which the interface connects. + For 2D projections of 3D microstructural features a triple point is + physically only the projection of a triple line. + + + + + + + + The specific triple_line_projections(NXms_feature_set) instance + whereby to resolve triple_point identifier. + + + + + + + The length of the interface. + + This is not necessarily the same as the length of the individual + polyline segments whereby the interface is discretized. + + The actual coordinate system whereby the geometry is calibrated + with real physical dimensions is typically documented by the + depends_on attribute of the respective NXcg_primitive_set. + This depends_on attribute should point explicitly to an + instance of a :ref:`NXcoordinate_system` to support users as + much as possible with interpreting how and where the lines are + located in the reference frame. + + + + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier for each interface using explicit indexing. + + + + + + + + + + Projections of triple lines as typically characterized with optical + or electron microscopy. + + Mind that most specimens are thermo-chemo-mechanically treated before + they are characterized. Therefore, the projected crystal defects are + have physically no longer the same structure as in the bulk. + + Examples are manifest as effects such as thermal grooving, or relaxation + effects of an intersection between a triple line that is cut + by the specimen surface as these defects are then exposed typically + to a different atmosphere and hence have different thermodynamic boundary + conditions than of their true volumetric defects in the bulk. + + + + Reference to points(NXcg_point_set) which supports the + locations of these triple points. + + + + + + Number of triple points. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier for each triple point using explicit indexing. + + + + + + + + Set of triple point identifiers. + + + + + + + The relevant points(NXcg_point_set) instance whereby to + resolve interface identifiers. + + + + + + Set of triplets of identifier of line-like features. + Each triplet resolves which three interface projections + the triple point connects. + + + + + + + + The specific interface_projections(NXms_feature_set) + instance whereby to resolve interface identifiers. + + + + + + + Triplet of identifier of polyline segments. Each triplet resolves + which three segments of polyline segments the triple junction connects. + + + + + + + + The specific lines(NXcg_polyline_set) instance to resolve + polyline segments. + + + + + + diff --git a/contributed_definitions/NXms_score_config.nxdl.xml b/contributed_definitions/NXms_score_config.nxdl.xml new file mode 100644 index 0000000000..30573be7e9 --- /dev/null +++ b/contributed_definitions/NXms_score_config.nxdl.xml @@ -0,0 +1,452 @@ + + + + + + + + Number of Bunge-Euler angle triplets for deformed grains. + + + + + Number of Bunge-Euler angle triplets for recrystallization nuclei. + + + + + Number of solitary unit domains to export. + + + + + Application definition to control a simulation with the SCORE model. + + + + + Version specifier of this application definition. + + + + + Official NeXus NXDL schema with which this file was written. + + + + + + + + + + + + + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + + + + + Possibility for leaving a free-text description about this analysis. + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + + + + + Relevant data to instantiate a starting configuration that is typically + a microstructure in deformed conditions where stored (elastic) energy + is stored in the form of crystal defects, which in the SCORE model are + is considered as mean-field dislocation content. + + + + Which model should be used to generate a starting microstructure. + + + + + + + + + + + Edge length of the cubic cells of each CA domain. + + + + + Extend of each CA domain in voxel along the x, y, and z direction. + Deformation of sheet material is assumed. + The x axis is assumed pointing along the rolling direction. + The y axis is assumed pointing along the transverse direction. + The z axis is assumed pointing along the normal direction. + + + + + + + + Extent of each deformed grain along the x, y, and z direction when type is + cuboidal. + + + + + + + + Average spherical diameter when type is poisson_voronoi. + + + + + Set of Bunge-Euler angles to sample orientations randomly from. + + + + + + + + + The EBSD dataset from which the initial microstructure is instantiated + if initial_microstructure/type has value ebsd. + + + + Path and name of the EBSD dataset from which to generate the starting + microstructure. + + + + SHA256 checksum of the file which contains the EBSD dataset. + + + + + + Size of the EBSD. The EBSD orientation mapping has to be on a + regular grid of square-shaped pixels. + + + + + + + + + + Phenomenological model according to which it nuclei are placed + into the domain and assumed growing. + + + + According to which model will the nuclei become distributed spatially. + CSR means complete spatial randomness. + Custom is implementation specific. + GB places nuclei at grain boundaries. + + + + + + + + + + According to which model will the nuclei start to grow. + + + + + + + + According to which model will the nuclei get their orientation assigned. + + + + + + + + Set of Bunge-Euler angles to sample orientations of nuclei randomly from. + + + + + + + + + + (Mechanical) properties of the material which scale the amount + of stored (elastic) energy in the ROI/system. + + + + Shear modulus at zero Kelvin. + + + + + Magnitude at the Burgers vector at zero Kelvin. + + + + + + Melting temperature in degrees Celsius. + + + + + + Model for the assumed mobility of grain boundaries with different + disorientation. + + + + Which type of fundamental model for the grain boundary mobility: + For the Sebald-Gottstein model the following equation is used. + For the Rollett-Holm model the following equation is used. + + + + + + + + + + + + + + + + + + + + + + + + + Simulated evolution of the dislocation density as the stored + (elastic) energy assumed stored in each grain. + + + + Which type of recovery model. + + + + + + + + + Simulated reduction of the grain boundary speed due to + the presence of dispersoids through which the total grain boundary + area of the recrystallization front can be reduced. + + + + Which type of drag model. + + + + + + + + + + + + Support point of the linearized curve of simulated time matching + a specific support point of the average dispersoid radius. + + + + + + + + Support point of the linearized curve of the average dispersoid radius. + + + + + + + + + + Simulated time temperature profile + + + + Support point of the linearized curve of simulated time matching + a specific support point of the temperature. + + + + + + + + Support point of the linearized curve of the temperature. + + + + + + + + + Criteria which enable to stop the simulation in a controlled manner. + Whichever criterion is fulfilled first stops the simulation. + + + + Maximum recrystallized volume fraction. + + + + + Maximum simulated physical time. + + + + + Maximum number of iteration steps. + + + + + + Settings relevant for stable numerical integration. + + + + Maximum fraction equivalent to the migration of the + fastest grain boundary in the system how much a cell + may be consumed in a single iteration. + + + + + Fraction of the total number of cells in the CA which + should initially be allocated for offering cells in the + recrystallization front. + + + + + By how much more times should the already allocated memory + be is increased to offer space for storing states of cells + in the recrystallization front. + + + + + Should the cache for cells in the recrystallization front + be defragmented on-the-fly. + + + + + Heuristic recrystallized volume target values at which + the cache for cells in the recrystallization front + will be defragmented on-the-fly. + + + + + + + + List of recrystallized volume target values at which a + snapshot of the CA state should be exported for. + + + + + + + + + + Perform a statistical analyses of the results as it was + proposed by M. Kühbach (solitary unit model ensemble approach). + + + + + How many independent cellular automaton domains + should be instantiated. + + + + + Into how many time steps should the real time interval be discretized upon + during post-processing the results with the solitary unit modeling approach. + + + + + List of identifier for those domain which should be rendered. + Identifier start from 0. + + + + + + + + + + + diff --git a/contributed_definitions/NXms_score_results.nxdl.xml b/contributed_definitions/NXms_score_results.nxdl.xml new file mode 100644 index 0000000000..55c4d0eb98 --- /dev/null +++ b/contributed_definitions/NXms_score_results.nxdl.xml @@ -0,0 +1,729 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of boundaries of the bounding box or primitive to domain. + + + + + Number of parameter required for chosen orientation parameterization. + + + + + Number of texture components identified. + + + + + Dimensionality. + + + + + Cardinality. + + + + + Number of active cells in the (recrystallization) front. + + + + + Number of grains in the computer simulation. + + + + + Application definition for storing results of the SCORE cellular automaton. + + The SCORE cellular automaton model for primary recrystallization is an + example of typical materials engineering applications used within the field + of so-called Integral Computational Materials Engineering (ICME) whereby + one can simulate the evolution of microstructures. + + Specifically the SCORE model can be used to simulate the growth of static + recrystallization nuclei. The model is described in the literature: + + * `M. Kühbach et al. <https://doi.org/10.1016/j.actamat.2016.01.068>`_ + * `C. Haase et al. <https://doi.org/10.1016/j.actamat.2015.08.057>`_ + * `M. Diehl et al. <https://doi.org/10.1088/1361-651X/ab51bd>`_ + + + + + An at least as strong as SHA256 hashvalue of the file + that specifies the application definition. + + + + + + NeXus NXDL schema to which this file conforms. + + + + + + + + Ideally, a (globally) unique persistent identifier + for referring to this computer simulation. + + The identifier is usually defined/issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments to e.g. proposals. + + + + + Free-text description about the workflow (analysis/simulation). + + Users are strongly advised to detail the sample history in the + respective field and fill rather as completely as possible the fields + of this application definition rather than write details about the + experiment into this free-text description field. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the characterization started. + + + + + ISO 8601 time code with local time zone offset to UTC included + when the characterization ended. + + + + + + + + + + Specify if the (characterization) results/data of this instance of an + application definition are based on the results of a simulation or the + results of a post-processing of measured data to describe a microstructure. + The term microstructure is used to describe the spatial arrangement of + crystal defects inside a sample/specimen without demanding necessarily + that this structure is mainly at the micron length scale. + Nanostructure and macrostructure are close synonyms. + Material architecture is a narrow synonym. + + + + + + + + + + The path and name of the config file for this analysis. + + + + At least SHA256 strong hash of the specific config_file for + tracking provenance. + + + + + + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + + + + + A statement whether the SCORE executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + + + + + + + + + Contact information and eventually details of at least one person + involved in creating this result. This can be the principle investigator + who performed this experiment. Adding multiple users if relevant is recommended. + + + + Given (first) name and surname of the user. + + + + + Name of the affiliation of the user at the point in time + when the experiment was performed. + + + + + Postal address of the affiliation. + + + + + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + + + + + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific service + should also be written in orcid_platform + + + + + Name of the OrcID or ResearcherID where the account + under orcid is registered. + + + + + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + + + + + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope. Student, postdoc, principle investigator, guest + are common examples. + + + + + Account name that is associated with the user in social media platforms. + + + + + Name of the social media platform where the account + under social_media_name is registered. + + + + + + + + Descriptive name or ideally (globally) unique persistent identifier. + + + + + + + Hard link to a location in the hierarchy of the NeXus file + where the data for default plotting are stored. + + + + + Container to hold different coordinate systems conventions. + A least a right-handed Cartesian coordinate system with base vectors + named x, y, and z has to be specified. Each base vector of the + coordinate system should be described with an NXtransformations instance. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The simulated or characterized material volume element aka domain. + At least one instance of geometry required either NXcg_grid, + NXcg_polyhedron_set, or NXcg_point_set. This geometry group needs + to contain details about the boundary conditions. + + + + + + + + + + + + + A tight bounding box or sphere or bounding primitive about the grid. + + + + + How many distinct boundaries are distinguished? + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + + + + + Name of the boundaries. E.g. left, right, front, back, bottom, top, + The field must have as many entries as there are number_of_boundaries. + + + + + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + + + + + + + + + Collection of microstructural data observed/simulated. + + + + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate + if the identifiers are expected to start from 1 (referred to as + Fortran-/Matlab-) or from 0 (referred to as C-, Python-style index + notation) respectively. + + + + + + Summary quantities which are the result of some post-processing of + the snapshot data (averaging, integrating, interpolating). + Frequently used descriptors from continuum mechanics and thermodynamics + can be used here. A few examples are given. Each descriptor is currently + modelled as an instance of an NXprocess because it is relevant to + understand how the descriptors are computed. + + + + Evolution of the physical time. + + + + + Evolution of the simulated temperature over time. + + + + + + Evolution of the recrystallized volume fraction over time. + + + + + + + + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + + + + + Simulated temperature. + + + + + Iteration or increment counter. + + + + + + + Grain identifier for each cell. + + + + + + + + + + Identifier of the OpenMP thread which processed this part of the grid. + + + + + + + + + + + + Details about those cells which in this time step represent + the discretized recrystallization front. + + + + Which cells are currently in a halo region of threads. + + + + + + + + So-called mobility weight which is a scaling factor to + control the mobility of the grain boundary which is assumed + to sweep currently this volume. + + + + + + + + Grid coordinates of each cell in the recrystallization front. + + + + + + + + + Grain identifier assigned to each cell in the recrystallization front. + + + + + + + + Grain identifier assigned to each nucleus which affected that cell in the + recrystallization front. + + + + + + + + Relative volume transformed as a measure of infection progress. + + + + + + + + Identifier of the OpenMP thread processing each cell in the recrystallization + front. + + + + + + + + Hint about the direction from which the cell was infected. + + + + + + + + + Current grain-related quantities. + + + + Bunge-Euler angle triplets for each grain. + + + + + + + + + Discrete volume of each grain accounting also for partially + transformed cells. + + + + + + + + Current value for the dislocation density as a measure of + the remaining stored energy in assumed crystal defects inside + each grain. The difference between these values scales the + driving force of grain boundary migration. + + + + + + + + Is the grain deformed. + + + + + + + + Is the grain recrystallized. + + + + + + + + + Current recrystallized volume fraction. + + + + Currently evaluated actual recrystallized volume fraction. + This takes into account partially recrystallized cells. + + + + + Currently desired target recrystallized volume fraction at + which the user requested to log a snapshot. + + + + + + + + Currently assumed globally applied Cauchy stress tensor on the ROI. + + + + + + + + + + + Currently assumed globally applied Cauchy strain tensor on the ROI. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + + + + + + + + + diff --git a/contributed_definitions/NXms_snapshot.nxdl.xml b/contributed_definitions/NXms_snapshot.nxdl.xml new file mode 100644 index 0000000000..b2b0e26f18 --- /dev/null +++ b/contributed_definitions/NXms_snapshot.nxdl.xml @@ -0,0 +1,54 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Base class for data on the state of the microstructure at a given + time/iteration. + + + + Is this time for a measurement or a simulation. + + + + + + + + + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + + + + + Iteration or increment counter. + + + diff --git a/contributed_definitions/NXms_snapshot_set.nxdl.xml b/contributed_definitions/NXms_snapshot_set.nxdl.xml new file mode 100644 index 0000000000..4bc9269763 --- /dev/null +++ b/contributed_definitions/NXms_snapshot_set.nxdl.xml @@ -0,0 +1,62 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + A collection of spatiotemporal microstructure data. + + + + Is this set describing a measurement or a simulation? + + + + + + + + + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate if the + identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) + or from 0 (referred to as C-, Python-style index notation) respectively. + + + + + + diff --git a/contributed_definitions/NXopt.nxdl.xml b/contributed_definitions/NXopt.nxdl.xml new file mode 100644 index 0000000000..570d18555e --- /dev/null +++ b/contributed_definitions/NXopt.nxdl.xml @@ -0,0 +1,868 @@ + + + + + + + + + Variables used throughout the document, e.g. dimensions or parameters. + + + + Length of the spectrum array (e.g. wavelength or energy) of the measured + data. + + + + + Number of sensors used to measure parameters that influence the sample, + such as temperature or pressure. + + + + + Number of measurements (1st dimension of measured_data array). This is + equal to the number of parameters scanned. For example, if the experiment + was performed at three different temperatures and two different pressures + N_measurements = 2*3 = 6. + + + + + Number of detection angles of the beam reflected or scattered off the + sample. + + + + + Number of angles of incidence of the incident beam. + + + + + Number of observables that are saved in a measurement. e.g. one for + intensity, reflectivity or transmittance, two for Psi and Delta etc. This + is equal to the second dimension of the data array 'measured_data' and the + number of column names. + + + + + An application definition for optical spectroscopy experiments. + + + + An application definition template for optical spectroscopy experiments. + + A general optical experiment consists of a light or excitation source, a + beam path, a sample + its stage + its environment, and a detection unit. + Examples are reflection or transmission measurements, photoluminescence, + Raman spectroscopy, ellipsometry etc. + + + + An application definition describing a general optical experiment. + + + + Version number to identify which definition of this application + definition was used for this entry/data. + + + + + URL where to find further material (documentation, examples) relevant + to the application definition. + + + + + + + + + A (globally persistent) unique identifier of the experiment. + (i) The identifier is usually defined by the facility or principle + investigator. + (ii) The identifier enables to link experiments to e.g. proposals. + + + + + An optional free-text description of the experiment. + + However, details of the experiment should be defined in the specific + fields of this application definition rather than in this experiment + description. + + + + + Specify the type of the optical experiment. + + + + + Start time of the experiment. UTC offset should be specified. + + + + + Contact information of at least the user of the instrument or the + investigator who performed this experiment. + Adding multiple users, if relevant, is recommended. + + + + Name of the user. + + + + + Name of the affiliation of the user at the point in time when the + experiment was performed. + + + + + Street address of the user's affiliation. + + + + + Email address of the user. + + + + + Author ID defined by https://orcid.org/. + + + + + Telephone number of the user. + + + + + + Properties of the experimental setup. This includes general information + about the instrument (such as model, company etc.), information about + the calibration of the instrument, elements of the beam path including + the excitation or light source and the detector unit, the sample stage + (plus the sample environment, which also includes sensors used to + monitor external conditions) and elements of the beam path. + + Meta data describing the sample should be specified in ENTRY/SAMPLE + outside of ENTRY/INSTRUMENT. + + + + The name of the instrument. + + + + The used version of the hardware if available. If not a commercial + instrument use date of completion of the hardware. + + + + + + Name of the company which build the instrument. + + + + + ISO8601 date when the instrument was constructed. + UTC offset should be specified. + + + + + + Commercial or otherwise defined given name of the program that was + used to measure the data, i.e. the software used to start and + record the measured data and/or metadata. + If home written, one can provide the actual steps in the NOTE + subfield here. + + + + + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + + + + + Website of the software. + + + + + + Commercial or otherwise defined name of the firmware that was used + for the measurement - if available. + + + + Version and build number or commit hash of the software source code. + + + + + Website of the software. + + + + + + Was a calibration performed? If yes, when was it done? If the + calibration time is provided, it should be specified in + ENTRY/INSTRUMENT/calibration/calibration_time. + + + + + + + + + + + + The calibration data and metadata should be described in a separate NeXus file + with the link provided in 'calibration_link'. + + + + If calibtration status is 'calibration time provided', specify the + ISO8601 date when calibration was last performed before this + measurement. UTC offset should be specified. + + + + + Link to the NeXus file containing the calibration data and metadata. + + + + + + Describes an arrangement of optical or other elements, e.g. the beam + path between the light source and the sample, or between the sample + and the detector unit (including the sources and detectors + themselves). + + If a beam splitter (i.e. a device that splits the incoming beam into + two or more beams) is part of the beam path, two or more NXbeam_path + fields may be needed to fully describe the beam paths and the correct + sequence of the beam path elements. + Use as many beam paths as needed to describe the setup. + + + + + Angle(s) of the incident beam vs. the normal of the bottom reflective + (substrate) surface in the sample. + + + + + + + + + Detection angle(s) of the beam reflected or scattered off the sample + vs. the normal of the bottom reflective (substrate) surface in the + sample if not equal to the angle(s) of incidence. + + + + + + + + Sample stage, holding the sample at a specific position in X,Y,Z + (Cartesian) coordinate system and at an orientation defined + by three Euler angles (alpha, beta, gamma). + + + + Specify the type of the sample stage. + + + + + + + + + + + + If there is no motorized stage, we should at least qualify where + the beam hits the sample and in what direction the sample stands + in a free-text description, e.g. 'center of sample, long edge + parallel to the plane of incidence'. + + + + + Specify external parameters that have influenced the sample, such + as the surrounding medium, and varied parameters e.g. temperature, + pressure, pH value, optical excitation etc. + + + + Describe what was the medium above or around the sample. The + common model is built up from the substrate to the medium on the + other side. Both boundaries are assumed infinite in the model. + Here, define the name of the medium (e.g. water, air, UHV, etc.). + + + + + Array of pairs of complex refractive indices n + ik of the medium + for every measured spectral point/wavelength/energy. + Only necessary if the measurement was performed not in air, or + something very well known, e.g. high purity water. + + + + + + + + + A sensor used to monitor an external condition influencing the + sample, such as temperature or pressure. It is suggested to + replace 'PARAMETER' by the type of the varied parameter defined + in 'parameter_type'. + The measured parameter values should be provided in 'values'. + For each parameter, a 'PARAMETER(NXsensor)' field needs to exist. + In other words, there are N_sensors 'PARAMETER(NXsensor)' fields. + + + + Indicates which parameter was changed. Its definition must exist + below. The specified variable has to be N_measurements long, + providing the parameters for each data set. If you vary more than + one parameter simultaneously. + If the measured parameter is not contained in the list `other` + should be specified and the `parameter_type_name` should be provided. + + + + + + + + + + + + + + + + + + + + + + + + + If the parameter_type is `other` a name should be specified here. + + + + + Number of different parameter values at which the measurement + was performed. For example, if the measurement was performed at + temperatures of 4, 77 and 300 K, then number_of_parameters = 3. + + + + + Vector containing the values of the varied parameter. Its + length is equal to N_measurements. The order of the values + should be as follows: + + * Order the sensors according to number_of_parameters starting + with the lowest number. If number_of_parameters is equal for + two sensors order them alphabetically (sensor/parameter name). + * The first sensor's j parameters should be ordered in the + following way. The first N_measurements/number_of_parameters + entries of the vector contain the first parameter (a1), the + second N_measurements/number_of_parameters contain the second + parameter (a2) etc., so the vector looks like: + [ + a1,a1,...,a1, + a2,a2,...,a2, + ... + aj,aj,...aj + ] + * The kth sensor's m parameters should be ordered in the + following way: + [ + p1,...p1,p2,...,p2,...pm,...,pm, + p1,...p1,p2,...,p2,...pm,...,pm, + ... + p1,...p1,p2,...,p2,...pm,...,pm + ] + * The last sensor's n parameters should be ordered in the + following way: + [ + z1,z2,...,zn, + z1,z2,...,zn, + ... + z1,z2,...,zn] + + For example, if the experiment was performed at three different + temperatures (T1, T2, T3), two different pressures (p1, p2) and + two different angles of incidence (a1, a2), then + N_measurements = 12 and the order of the values for the various + parameter vectors is: + + * angle_of_incidence: [a1,a1,a1,a1,a1,a1,a2,a2,a2,a2,a2,a2] + * pressure: [p1,p1,p1,p2,p2,p2,p1,p1,p1,p2,p2,p2] + * temperature: [T1,T2,T3,T1,T2,T3,T1,T2,T3,T1,T2,T3] + + + + + + + + + + For environmental measurements, the environment (liquid, vapor + etc.) is enclosed in a cell, which has windows both in the + direction of the source (entry window) and the detector (exit + window) (looking from the sample). In case that the entry and exit + windows are not the same type and do not have the same properties, + use a second 'WINDOW(MXaperture)' field. + + The windows also add a phase shift to the light altering the + measured signal. This shift has to be corrected based on measuring + a known sample (reference sample) or the actual sample of interest + in the environmental cell. State if a window correction has been + performed in 'window_effects_corrected'. Reference data should be + considered as a separate experiment, and a link to the NeXus file + should be added in reference_data_link in measured_data. + + The window is considered to be a part of the sample stage but also + beam path. Hence, its position within the beam path should be + defined by the 'depends_on' field. + + + + Specify the position of the window in the beam path by pointing + to the preceding element in the sequence of beam path elements. + + + + + Was a window correction performed? If 'True' describe the window + correction procedure in 'window_correction/procedure'. + + + + + Was a window correction performed? If 'True' describe the + window correction procedure in '' + + + + Describe when (before or after the main measurement + time + stamp in 'date') and how the window effects have been + corrected, i.e. either mathematically or by performing a + reference measurement. In the latter case, provide the link to + to the reference data in 'reference_data_link'. + + + + + Link to the NeXus file which describes the reference data if a + reference measurement for window correction was performed. + Ideally, the reference measurement was performed on a reference + sample and on the same sample, and using the same conditions as + for the actual measurement with and without windows. It should + have been conducted as close in time to the actual measurement + as possible. + + + + + + The material of the window. + + + + + + + + + + + + + + + If you specified 'other' as material, decsribe here what it is. + + + + + Thickness of the window. + + + + + Angle of the window normal (outer) vs. the substrate normal + (similar to the angle of incidence). + + + + + + + + Properties of the sample, such as sample type, layer structure, + chemical formula, atom types, its history etc. + Information about the sample stage and sample environment should be + described in ENTRY/INSTRUMENT/sample_stage. + + + + Descriptive name of the sample + + + + + Specify the type of sample, e.g. thin film, single crystal etc. + + + + + + + + + + + + Qualitative description of the layer structure for the sample, + starting with the top layer (i.e. the one on the front surface, on + which the light incident), e.g. native oxide/bulk substrate, or + Si/native oxide/thermal oxide/polymer/peptide. + + + + + Chemical formula of the sample. Use the Hill system (explained here: + https://en.wikipedia.org/wiki/Chemical_formula#Hill_system) to write + the chemical formula. In case the sample consists of several layers, + this should be a list of the chemical formulas of the individual + layers, where the first entry is the chemical formula of the top + layer (the one on the front surface, on which the light incident). + The order must be consistent with layer_structure + + + + + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + 'atom_types'. + + + + + Ideally, a reference to the location or a unique (globally + persistent) identifier (e.g.) of e.g. another file which gives + as many as possible details of the material, its microstructure, + and its thermo-chemo-mechanical processing/preparation history. + In the case that such a detailed history of the sample is not + available, use this field as a free-text description to specify + details of the sample and its preparation. + + + + + ISO8601 date with time zone (UTC offset) specified. + + + + + Description of the substrate. + + + + + Specify the sample orientation. + + + + + + Measured data, data errors, and varied parameters. If reference data + were measured they should be considered a separate experiment and a + link to its NeXus file should be added in reference_data_link. + + + + An identifier to correlate data to the experimental conditions, + if several were used in this measurement; typically an index of 0-N. + + + + + Select which type of data was recorded, for example intensity, + reflectivity, transmittance, Psi and Delta etc. + It is possible to have multiple selections. The enumeration list + depends on the type of experiment and may differ for different + application definitions. + + + + + + + + + + + + + + + + + Spectral values (e.g. wavelength or energy) used for the measurement. + An array of 1 or more elements. Length defines N_spectrum. Replace + 'SPECTRUM' by the physical quantity that is used, e.g. wavelength. + + + + + + + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + + + + + + Resulting data from the measurement, described by 'data_type'. + + The first dimension is defined by the number of measurements taken, + (N_measurements). The instructions on how to order the values + contained in the parameter vectors given in the doc string of + INSTRUMENT/sample_stage/environment_conditions/PARAMETER/values, + define the N_measurements parameter sets. For example, if the + experiment was performed at three different temperatures + (T1, T2, T3), two different pressures (p1, p2) and two different + angles of incidence (a1, a2), the first measurement was taken at the + parameters {a1,p1,T1}, the second measurement at {a1,p1,T2} etc. + + + + + + + + + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + + + + + + Specified uncertainties (errors) of the data described by 'data_type' + and provided in 'measured_data'. + + + + + + + + + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + + + + + + List of links to the values of the sensors. Add a link for each + varied parameter (i.e. for each sensor). + + + + + + + + Link to the NeXus file which describes the reference data if a + reference measurement was performed. Ideally, the reference + measurement was performed using the same conditions as the actual + measurement and should be as close in time to the actual measurement + as possible. + + + + + + Commercial or otherwise defined given name of the program that was + used to generate the result file(s) with measured data and/or + metadata (in most cases, this is the same as INSTRUMENT/software). + If home written, one can provide the actual steps in the NOTE + subfield here. + + + + + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + + + + + Website of the software. + + + + + + A plot of the multi-dimensional data array provided in + ENTRY/data/measured_data. + + + + Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) + + + + + + + Parameters that are derived from the measured data. + + + + Light loss due to depolarization as a value in [0-1]. + + + + + + + + + + Jones quality factor. + + + + + + + + + + Reflectivity. + + + + + + + + + + Transmittance. + + + + + + + + + + + Commercial or otherwise defined given name of the program that was + used to generate or calculate the derived parameters. + If home written, one can provide the actual steps in the NOTE + subfield here. + + + + + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + + + + + + + A default view of the data provided in ENTRY/data_collection/measured_data. This + should be the part of the data set which provides the most suitable + representation of the data. + + + + Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) + + + + + diff --git a/contributed_definitions/NXoptical_system_em.nxdl.xml b/contributed_definitions/NXoptical_system_em.nxdl.xml index 22db765166..0611984a77 100644 --- a/contributed_definitions/NXoptical_system_em.nxdl.xml +++ b/contributed_definitions/NXoptical_system_em.nxdl.xml @@ -1,13 +1,92 @@ - + - + + A container for qualifying an electron optical system. - - - - - - + + + + Citing the JEOL TEM glossary this is *an effective distance from a specimen + to a plane where an observed diffraction pattern is formed*. + + + + + The factor of enlargement of the apparent size, + not the physical size, of an object. + + + + + The defocus aberration constant (oftentimes referred to as C_1_0). + See respective details in :ref:`NXaberration` class instances. + + + + + Citing the JEOL TEM glosssary this is the value *when a cone shaped, + convergent electron beam illuminates a specimen, the semi-angle of the cone + is termed convergence angle.* + + + + + The extent of the observable parts of the specimen given the current + magnification and other settings of the instrument. + + + + + Citing `Globalsino <https://www.globalsino.com/EM/page4586.html>`_ this is + *a distance between the specimen and the lower pole piece in SEM system*. + + + + + + Beam current as measured relevant for the illumination of the specimen. + Users should specify further details like how the beam current + was measured using the beam_current_description field. + + + + + + Specify further details how the beam current was measured or estimated. + + + diff --git a/contributed_definitions/NXpeak.nxdl.xml b/contributed_definitions/NXpeak.nxdl.xml index 4eaffed5de..f39d938c2c 100644 --- a/contributed_definitions/NXpeak.nxdl.xml +++ b/contributed_definitions/NXpeak.nxdl.xml @@ -1,6 +1,27 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays. @@ -14,13 +35,13 @@ Description of peaks, their functional form or measured support. - + Human-readable identifier to specify which concept/entity the peak represents/identifies. - + Is the peak described analytically via a functional form or is it empirically defined via measured/reported diff --git a/contributed_definitions/NXphysical_process.nxdl.xml b/contributed_definitions/NXphysical_process.nxdl.xml new file mode 100644 index 0000000000..d422e516c6 --- /dev/null +++ b/contributed_definitions/NXphysical_process.nxdl.xml @@ -0,0 +1,61 @@ + + + + + + A planned or unplanned process which results in physical changes in a specified material. + + A physical change involve changes only in intermolecular forces, not in the chemical bonds. + Examples include sample preparation, material transformation, or (partially) destructive measurements. + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process started. + + + + + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process ended. + + + + + Short description of the activity. + + + + + Method by which this process was performed. + + + + + This can be any data or other descriptor acquired during the physical process + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + + + diff --git a/contributed_definitions/NXpid.nxdl.xml b/contributed_definitions/NXpid.nxdl.xml new file mode 100644 index 0000000000..c93ce7597e --- /dev/null +++ b/contributed_definitions/NXpid.nxdl.xml @@ -0,0 +1,98 @@ + + + + + + Contains the settings of a PID controller. + + + + Description of how the Process Value for the PID controller is produced by sensor(s) in the setup. + + For example, a set of sensors could be averaged over before feeding it back into the loop. + + + + + The sensor representing the Process Value used in the feedback loop for the PID. + + In case multiple sensors were used, this NXsensor should contain the proper calculated/aggregated value. + + + + + The actual timeseries data fed back to the PID loop. + + + + + + + The Setpoint(s) used as an input for the PID controller. + + It can also be a link to an NXsensor.value field. + + + + + Time log of the setpoint(s) used as an input for the PID controller. + + + + + Proportional term. The proportional term produces an output value + that is proportional to the current error value. + The proportional response can be adjusted by multiplying the error + by a constant Kp, called the proportional gain constant. + The Type switches controller parameters between P/I (proportional gain/integral gain) and P/T (proportional gain/time constant). The formula for the controller in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and time constant are related as follows I = P/T. + + + + + The contribution from the integral term is proportional to both + the magnitude of the error and the duration of the error. + The integral in a PID controller is the sum of the instantaneous + error over time and gives the accumulated offset that should have + been corrected previously. The accumulated error is then + multiplied by the integral gain (Ki) and added to the + controller output. + + + + + The derivative of the process error is calculated by determining + the slope of the error over time and multiplying this rate of + change by the derivative gain K_d. The magnitude of the + contribution of the derivative term to the overall control + action is termed the derivative gain, K_d + + + + + The Type switches controller parameters between P/I (proportional gain/integral + gain) and P/T (proportional gain/time constant). The formula for the controller + in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and + time constant are related as follows I = P/T. + + + diff --git a/contributed_definitions/NXpolarizer_opt.nxdl.xml b/contributed_definitions/NXpolarizer_opt.nxdl.xml new file mode 100644 index 0000000000..8edba8ecd3 --- /dev/null +++ b/contributed_definitions/NXpolarizer_opt.nxdl.xml @@ -0,0 +1,244 @@ + + + + + + + + + Size of the wavelength array for which the refractive index of the material + and/or coating is given. + + + + + Size of the wavelength array for which the reflectance or transmission of + the polarizer is given. + + + + + An optical polarizer. + + Information on the properties of polarizer is provided e.g. + [here](https://www.rp-photonics.com/polarizers.html). + + + + Type of the polarizer (e.g. dichroic, linear, circular etc.) + + + + + + + + + + + + + + + + + + + + + If you selected 'other' in type specify what it is. + + + + + Angle of the polarizer. + + + + + Acceptance angle of the polarizer (range). + + + + + + + + Describe the geometry (shape, dimension etc.) of the device. + Specify the dimensions in 'SHAPE/size'. A sketch of the device should be + provided in the 'sketch(NXdata)' field to clarify (i) the shape and + dimensions of the device, and (ii) the input and outputs (i.e. the + direction of the incoming and outcoming (split) beams). + + + + + Describe the shape (plate, cube, wedged, prism etc.). + + + + + + + + + + + + + If you chose 'other' in 'shape' describe what it is. + + + + + Sketch of thedevice showing its geometry. The paths of the + incoming and outgoing beam should be illustrated and labelled (0 for + the incoming beam, and 1, 2,..., N_outputs for the outputs). + + + + + Physical extent of the device. The device might be made up of one or + more objects (NX_objects). The meaning and location of the axes used + will vary according to the value of the 'shape' variable. 'N_shapepar' + defines how many parameters: + + * For 'cube' the parameters are (width, length). + * For 'cylinder' the parameters are (diameter, length). + * For 'plate' the parameters are (width, height, length). + * For 'prism' the parameters are (width, height, length). + * For 'wedged' the parameters are (width, height, shortest length). + The wedge angle should be provided in 'SHAPE/wedge_angle'. + * For 'other' the parameters may be (A, B, C, ...) with the labels + defined in the sketch plotted in 'SHAPE/sketch'. + + + + + + + + + Wedge angle if 'shape' is 'wedged'. + + + + + + Wavelength range for which the polarizer is designed. Enter the minimum + and maximum wavelength (lower and upper limit) of the range. + + + + + + + + Properties of the substrate material of the polarizer. If the device has + a coating specify the coating material and its properties in 'coating'. + + + + Specify the substrate material of the polarizer. + + + + + Thickness of the polarizer substrate. + + + + + Complex index of refraction of the polarizer material. Specify at given + spectral values (wavelength, energy, wavenumber etc.). + + + + + + + + + + + If the device has a coating describe the material and its properties. + Some basic information can be found e.g. [here] + (https://www.opto-e.com/basics/reflection-transmission-and-coatings). + If the back and front side of the polarizer are coated with different + materials, you may define two coatings (e.g. COATING1 and COATING2). + + + + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + + + + + Describe the coating material (e.g. MgF2). + + + + + Thickness of the coating. + + + + + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + + + + + + + + + + Extinction ratio (maximum to minimum transmission). + + + + + + + + Reflection of the polarizer at given wavelength values. + + + + + + + + Transmission of the polarizer at given wavelength values. + + + + + + + diff --git a/contributed_definitions/NXpositioner_sts.nxdl.xml b/contributed_definitions/NXpositioner_sts.nxdl.xml new file mode 100644 index 0000000000..7d13592b97 --- /dev/null +++ b/contributed_definitions/NXpositioner_sts.nxdl.xml @@ -0,0 +1,310 @@ + + + + + + A generic positioner such as a motor or piezo-electric transducer. + + + + symbolic or mnemonic name (one word) + + + + + description of positioner + + + + + best known value of positioner - need [n] as may be scanned + + + + + + + + raw value of positioner - need [n] as may be scanned + + + + + + + + targeted (commanded) value of positioner - need [n] as may be scanned + + + + + + + + maximum allowable difference between target_value and value + + + + + + + + minimum allowed limit to set value + + + + + maximum allowed limit to set value + + + + + velocity of the positioner (distance moved per unit time) + + + + + time to ramp the velocity up to full speed + + + + + Hardware device record, e.g. EPICS process variable, taco/tango ... + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a positioner. + + + + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + + + + To clarify the frame laboratory frame. The scanning area in x, y, and z position in the + frame. + + + + + This controllers task is to continuously adjust the Z position of the stm tip in order + to keep the selected control signal as close as possible to the Set Point. Different control + signals lead to different contronller beahvior. + + + + + Offset added to the initial averaged position Zaver before starting to swepp. + + + + + Indicate the tip position Z between tip and sample. The tip position can also be varied when + the controller is not running. + + + + + Controller name. This name which will be displayed at places where you can select a + controller. + + + + + Set Point is the desired value of the control signal. It can be set by editing the number + or using the slider bar. Click the "Set" button above the input field to use the actual + value as Set Point. The slider shows the Set Point as well as the current value. + + + + + Lifts the tip by the specified amount when then controller is switched off. This can be + a positive or a negative number, i.e. the tip can also be moved towards the sample. Be + careful with sign and value when using this feature. + + + + + Use this parameter for a reproducible position when switching off the Z-controller. + When >0 and the Z-controller is switched off, it doesn't switch off immediately but continues + to run for the specified time and averages the Z position. + + + + + (In bias spectroscopy) Select whether to set the Z-Controller on hold (i.e. disabled) during + the sweep. It is selected by default. When deselected, Z-offset and Z control time parameters + are disabled. + + + + + The final z-position during the bias spectroscopy scan. The availability of values is + related to the mode of scanning. + + + + + + Configure the scan frame like x position; y position; width; height. + + + + + Scan resolution by setting the Lines equal to Pixels. + + + + + Define the image resolution. + + + + + Define the scan forward speed in the forward direction. + + + + + Define the scan backward speed in the forward direction. + + + + + Piezo calibration module is used to define the X Y Z piezos calibration. + + + + + The name of caliberation type. + + + + + + + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and :math:`P/T` + (proportional gain/time constant). The formula for the controller in the frequency domain is: + :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. + The integral gain and time constant are related as follows: :math:`I = P/T`. + + + + + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and + P/T (proportional gain/time constant). The formula for the controller in the frequency + domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related + as follows: `:math:I = P/T`. + + + + + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and + :math:`P/T` (proportional gain/time constant). The formula for the controller in the frequency + domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related + as follows: :math:`I = P/T`. + + + + + + There are 2 parameters in X and Y directions. If you know them, you can enter the 2nd order + piezo characteristics to compensate for it. The following equation shows the interpretation + of the 2nd order correction parameter: For the X-piezo: + :math:`Ux = 1/cx · X + cxx · X2`; with units: :math:`[V] = [V/m] · [m] + [V/m2] · [m2]` + where cx is the calibration of the piezo X and cxx is the 2nd order correction. :math:`(V/m^2)` + + + + + There are 2 parameters in X and Y directions. Define the drift speed for all three axes. + When the compensation is on, the piezos will start to move at that speed. + + + + + Use the button to turn on/off the drift compensation. + + + diff --git a/contributed_definitions/NXprocess_mpes.nxdl.xml b/contributed_definitions/NXprocess_mpes.nxdl.xml new file mode 100644 index 0000000000..585bc972f9 --- /dev/null +++ b/contributed_definitions/NXprocess_mpes.nxdl.xml @@ -0,0 +1,159 @@ + + + + + + :ref:`NXprocess_mpes` describes events of data processing, reconstruction, + or analysis for MPES-related data. + + It extends the NXprocess class and provides a glossary of explicitly named processes + and their metadata which are typical for MPES data. + + + + Calibration event on the energy axis. + + For XPS, the calibration should ideally be performed according to + `ISO 15472:2010`_ specification. + + .. _ISO 15472:2010: https://www.iso.org/standard/74811.html + + + + This is the calibrated energy axis to be used for data plotting. + + + + + + + This is the calibrated angular axis to be used for data plotting. + + + + + + + This is the calibrated spatial axis to be used for data plotting. + + + + + + + This is the momentum axis to be used for data plotting. + + + + + + For energy referencing, the measured energies are corrected for the charging potential + (i.e., the electrical potential of the surface region of an insulating sample, caused by + irradiation) such that those energies correspond to a sample with no surface charge. + Usually, the energy axis is adjusted by shifting all energies uniformally until one + well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. + + This concept is related to term `12.74 ff.`_ of the ISO 18115-1:2023 standard. + + .. _12.74 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 + + + + Electronic core or valence level that was used for the calibration. + + + + + Reference peak that was used for the calibration. + + For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level + + + + + The binding energy (in units of eV) that the specified emission line appeared at, + after adjusting the binding energy scale. + + This concept is related to term `12.16_ ff.`_ of the ISO 18115-1:2023 standard. + + .. _12.16_ ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + + + + + Offset between measured binding energy and calibrated binding energy of the + emission line. + + + + + This is the calibrated energy axis to be used for data plotting. + + This should link to /entry/data/energy. + + + + + + In the transmission correction, each intensity measurement for electrons of a given + kinetic energy is multiplied by the corresponding value in the relative_intensity + field of the transmission_function. This calibration procedure is used to account for + the different tranmsission efficiencies when using different lens modes. + + + + Transmission function of the electron analyser. + + The transmission function (TF) specifies the detection efficiency for electrons of + different kinetic energy passing through the electron analyser. + This can be a link to /entry/instrument/electronanalyser/transmission_function. + + + + + + + + + + + + + + Kinetic energy values + + + + + + + + Relative transmission efficiency for the given kinetic energies + + + + + + + + diff --git a/contributed_definitions/NXprogram.nxdl.xml b/contributed_definitions/NXprogram.nxdl.xml new file mode 100644 index 0000000000..2a2c10c03e --- /dev/null +++ b/contributed_definitions/NXprogram.nxdl.xml @@ -0,0 +1,52 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Base class to describe a software tool or library. + + + + Given name of the program. Program can be a commercial one a script, + or a library or a library component. + + + + Program version plus build number, or commit hash. + + + + + Description of an ideally ever persistent resource where the source code + of the program or this specific compiled version of the program can be + found so that the program yields repeatably exactly the same numerical + and categorical results. + + + + diff --git a/contributed_definitions/NXpulser_apm.nxdl.xml b/contributed_definitions/NXpulser_apm.nxdl.xml index cacd80e283..b45230e1ec 100644 --- a/contributed_definitions/NXpulser_apm.nxdl.xml +++ b/contributed_definitions/NXpulser_apm.nxdl.xml @@ -1,6 +1,27 @@ - + - + + The symbols used in the schema to specify e.g. dimensions of arrays. @@ -12,57 +33,81 @@ - Metadata for laser-, voltage-, or combined pulsing triggering field evaporation. + Metadata for laser- and/or voltage-pulsing in atom probe microscopy. - + + How is field evaporation physically triggered. - - + + - + Frequency with which the high voltage or laser pulser fires. + + + + - + Fraction of the pulse_voltage that is applied in addition to the standing_voltage at peak voltage of a pulse. + + If a standing voltage is applied, this gives nominal pulse fraction + (as a function of standing voltage). Otherwise this field should not be + present. + + + + + In laser pulsing mode the values will be zero so the this field is recommended. + However, for voltage pulsing mode it is highly recommended that users report the pulsed_voltage. + + + + + + + + Absolute number of pulses starting from the beginning of the experiment. + - Direct current voltage between the specimen and the - (local electrode) in the case of local electrode atom - probe (LEAP) instrument. + Direct current voltage between the specimen and the (local electrode) in + the case of local electrode atom probe (LEAP) instrument. + The standing voltage applied to the sample, relative to system ground. - + Atom probe microscopes use controlled laser, voltage, or a combination of pulsing strategies to trigger the excitation and eventual field evaporation/emission of - an ion during an atom probe microscopy experiment. + an ion during an experiment. - + Given name/alias. - + Nominal wavelength of the laser radiation. @@ -70,14 +115,42 @@ - Average power of the laser source while illuminating the specimen. + Nominal power of the laser source while illuminating the specimen. + Average energy of the laser at peak of each pulse. + + + Details about specific positions along the focused laser beam + which illuminates the (atom probe) specimen. + + + + Track time-dependent settings over the course of the + measurement how the laser beam in tip space/reconstruction space + laser impinges on the sample, i.e. the mean vector is parallel to + the laser propagation direction. + + + + + Track time-dependent settings over the course of the + measurement where the laser beam exits the + focusing optics. + + + + + Track time-dependent settings over the course of the + measurement where the laser hits the specimen. + + + Affine transformations which describe the geometry how the @@ -90,23 +163,4 @@ - - - Details about specific positions along the focused laser beam - which illuminates the (atom probe) specimen. - - - - Track time-dependent settings over the course of the - measurement where the laser beam exits the - focusing optics. - - - - - Track time-dependent settings over the course of the - measurement where the laser hits the specimen. - - - diff --git a/contributed_definitions/NXpump.nxdl.xml b/contributed_definitions/NXpump.nxdl.xml index 3982438b55..45a86edada 100644 --- a/contributed_definitions/NXpump.nxdl.xml +++ b/contributed_definitions/NXpump.nxdl.xml @@ -1,9 +1,31 @@ - + - + + - Device to reduce an atmosphere to a controlled remaining pressure level. + Device to reduce an atmosphere (real or simulated) to a controlled pressure. + Principle type of the pump. @@ -15,4 +37,7 @@ + diff --git a/contributed_definitions/NXreflectron.nxdl.xml b/contributed_definitions/NXreflectron.nxdl.xml index 40723fa055..20d083590e 100644 --- a/contributed_definitions/NXreflectron.nxdl.xml +++ b/contributed_definitions/NXreflectron.nxdl.xml @@ -1,21 +1,46 @@ - + - + + Device for reducing flight time differences of ions in ToF experiments. + For atom probe the reflectron can be considered an energy_compensation + device, which can e.g. be realized technically as via a Poschenrieder lens + (see US patent 3863068 or US patents for the reflectron 6740872, or the curved reflectron 8134119 design). - + Given name/alias. - - + + Free-text field to specify further details about the reflectron. The field can be used to inform e. g. if the reflectron is flat or curved. + Affine transformation(s) which detail where the reflectron diff --git a/contributed_definitions/NXregistration.nxdl.xml b/contributed_definitions/NXregistration.nxdl.xml index 8ddd155260..0b328b1edc 100644 --- a/contributed_definitions/NXregistration.nxdl.xml +++ b/contributed_definitions/NXregistration.nxdl.xml @@ -1,6 +1,27 @@ - + - + + Describes image registration procedures. diff --git a/contributed_definitions/NXresolution.nxdl.xml b/contributed_definitions/NXresolution.nxdl.xml new file mode 100644 index 0000000000..6abb5f4308 --- /dev/null +++ b/contributed_definitions/NXresolution.nxdl.xml @@ -0,0 +1,102 @@ + + + + + + Describes the resolution of a physical quantity. + + + + The physical quantity of the resolution, e.g., + energy, momentum, time, etc. + + + + + The process by which the resolution was determined. + + + + + + + + + + + Additional details of the estimate or description of the calibration procedure + + + + + The resolution of the physical quantity. + + + + + Standard deviation of the resolution of the physical quantity. + + + + + The response of the instrument or part to a infinitesimally sharp input signal + along the physical quantity of this group. + This is also sometimes called instrument response function for time resolution or + point spread function for spatial response. + The resolution is typically determined by taking the full width at half maximum (FWHM) + of the response function. + + + + The input axis or grid of the response function. + The unit should match the one of the resolution field. + + + + + The magnitude of the response function corresponding to the points + in the input axis or grid. + This field should have the same dimensions as `input`. + + + + + + A symbol linking to another path in this appdef to be referred to from the + `resolution_formula` field. This should be a valid path inside this application + definition, i.e., of the form /entry/instrument/my_part/my_field. + + + + + A resolution formula to determine the resolution from a set of symbols as + entered by the `formula_...` fields. + The output unit should match the provided unit of this field. + + + + + For storing details and data of a calibration to derive a resolution from data. + + + diff --git a/contributed_definitions/NXroi.nxdl.xml b/contributed_definitions/NXroi.nxdl.xml new file mode 100644 index 0000000000..94857e74cb --- /dev/null +++ b/contributed_definitions/NXroi.nxdl.xml @@ -0,0 +1,34 @@ + + + + + + Base class to describe a region-of-interest analyzed. + + + + Details about processing steps. + + + + diff --git a/contributed_definitions/NXrotation_set.nxdl.xml b/contributed_definitions/NXrotation_set.nxdl.xml new file mode 100644 index 0000000000..dd55e97e76 --- /dev/null +++ b/contributed_definitions/NXrotation_set.nxdl.xml @@ -0,0 +1,256 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The cardinality of the set, i.e. the number of value tuples. + + + + + How many phases with usually different crystal and symmetry are distinguished. + + + + + Base class to detail a set of rotations, orientations, and disorientations. + + For getting a more detailed insight into the discussion of the + parameterized description of orientations in materials science see: + + * `H.-J. Bunge <https://doi.org/10.1016/C2013-0-11769-2>`_ + * `T. B. Britton et al. <https://doi.org/10.1016/j.matchar.2016.04.008>`_ + * `D. Rowenhorst et al. <https://doi.org/10.1088/0965-0393/23/8/083501>`_ + * `A. Morawiec <https://doi.org/10.1007/978-3-662-09156-2>`_ + + Once orientations are defined, one can continue to characterize the + misorientation and specifically the disorientation. The misorientation describes + the rotation that is required to register the lattices of two oriented objects + (like crystal lattice) into a crystallographic equivalent orientation: + + * `R. Bonnet <https://doi.org/10.1107/S0567739480000186>`_ + + + + Reference to an instance of :ref:`NXem_conventions` which contextualizes + how the here reported parameterized quantities can be interpreted. + + + + + + Point group which defines the symmetry of the crystal. + + This has to be at least a single string. If crystal_symmetry is not + provided point group 1 is assumed. + + In the case that misorientation or disorientation fields are used + and the two crystal sets resolve for phases with a different + crystal symmetry, this field has to encode two string. + In this case the first string is for phase A the second one for phase B. + An example of this most complex case is the description of the + disorientation between crystals adjoining a hetero-phase boundary. + + + + + + + + Point group which defines an assumed symmetry imprinted upon processing + the material/sample which could give rise to or may justify to use a + simplified description of rotations, orientations, misorientations, + and disorientations via numerical procedures that are known as + symmetrization. + + If sample_symmetry is not provided point group 1 is assumed. + + The traditionally used symmetrization operations within the texture + community in Materials Science, though, are thanks to methodology and + software improvements no longer strictly needed. Therefore, users are + encouraged to set the sample_symmetry to 1 (triclinic) and thus assume + there is no justification to assume the imprinting of additional + symmetry because of the processing. + + In practice one often faces situations where indeed these assumed + symmetries are anyway not fully observed, and thus an accepting of + eventual inaccuracies just for the sake of reporting a simplified + symmetrized description should be avoided. + + + + + + + + The set of rotations expressed in quaternion parameterization considering + crystal_symmetry and sample_symmetry. Rotations which should be + interpreted as antipodal are not marked as such. + + + + + + + + + The set of rotations expressed in Euler angle parameterization considering + the same applied symmetries as detailed for the field rotation_quaternion. + To interpret Euler angles correctly, it is necessary to inspect the + conventions behind depends_on to resolve which of the many Euler-angle + conventions possible (Bunge ZXZ, XYZ, Kocks, Tait, etc.) were used. + + + + + + + + + + + True for all those value tuples which have assumed antipodal symmetry. + False for all others. + + + + + + + + The set of orientations expressed in quaternion parameterization and + obeying symmetry for equivalent cases as detailed in crystal_symmetry + and sample_symmetry. The supplementary field is_antipodal can be used + to mark orientations with the antipodal property. + + + + + + + + + The set of orientations expressed in Euler angle parameterization following + the same assumptions like for orientation_quaternion. + To interpret Euler angles correctly, it is necessary to inspect the + conventions behind depends_on to resolve which of the many Euler-angle + conventions possible (Bunge ZXZ, XYZ, Kocks, Tait, etc.) were used. + + + + + + + + + + + The set of misorientations expressed in quaternion parameterization + obeying symmetry operations for equivalent misorientations + as defined by crystal_symmetry and sample_symmetry. + + + + + + + + + Misorientation angular argument (eventually signed) following the same + symmetry assumptions as expressed for the field misorientation_quaternion. + + + + + + + + Misorientation axis (normalized) and signed following the same + symmetry assumptions as expressed for the field misorientation_angle. + + + + + + + + + + The set of disorientation expressed in quaternion parameterization + obeying symmetry operations for equivalent misorientations + as defined by crystal_symmetry and sample_symmetry. + + + + + + + + + Disorientation angular argument (should not be signed, see + `D. Rowenhorst et al. <https://doi.org/10.1088/0965-0393/23/8/083501>`_) + following the same symmetry assumptions as expressed for the field + disorientation_quaternion. + + + + + + + + Disorientation axis (normalized) following the same symmetry assumptions + as expressed for the field disorientation_angle. + + + + + + + + diff --git a/contributed_definitions/NXsample_component_set.nxdl.xml b/contributed_definitions/NXsample_component_set.nxdl.xml new file mode 100644 index 0000000000..aa3a0e794f --- /dev/null +++ b/contributed_definitions/NXsample_component_set.nxdl.xml @@ -0,0 +1,78 @@ + + + + + + + + number of components + + + + + Set of sample components and their configuration. + + The idea here is to have a united place for all materials descriptors that are not + part of the individual sample components, but rather their configuration. + + + + Array of strings referring to the names of the NXsample_components. + The order of these components serves as an index (starting at 1). + + + + + Concentration of each component + + + + + + + + Volume fraction of each component + + + + + + + + Scattering length density of each component + + + + + + + + Each component set can contain multiple components. + + + + + For description of a sub-component set. Can contain multiple components itself. + + + diff --git a/contributed_definitions/NXsample_history.nxdl.xml b/contributed_definitions/NXsample_history.nxdl.xml new file mode 100644 index 0000000000..207fc41d5d --- /dev/null +++ b/contributed_definitions/NXsample_history.nxdl.xml @@ -0,0 +1,67 @@ + + + + + + A set of activities that occurred to the sample prior/during experiment. + + Ideally, a full report of the previous operations (or links to a chain of operations). + Alternatively, notes allow for additional descriptors in any format. + + + + Any activity that was performed on the sample prior or during the experiment. In + the future, if there is base class inheritance, this can describe any activity, + including processes and measurements. + + + + + + Any physical process that was performed on the sample prior or during the + experiment. + + + + + Any chemical process that was performed on the sample prior or during the + experiment. + + + + + + A descriptor to keep track of the treatment of the sample before or during the + experiment (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + This should only be used in case that there is no rigorous description + using the base classes above. This field can also be used to pull in any activities + that are not well described by an existing base class definition. + + + diff --git a/contributed_definitions/NXscanbox_em.nxdl.xml b/contributed_definitions/NXscanbox_em.nxdl.xml index 0af3ac4f8f..875218fa48 100644 --- a/contributed_definitions/NXscanbox_em.nxdl.xml +++ b/contributed_definitions/NXscanbox_em.nxdl.xml @@ -1,19 +1,82 @@ - + - + + - Scan box and coils which deflect an electron beam in a controlled manner. + Scan box and coils which deflect a beam of charged particles in a controlled manner. - In electron microscopy, the scan box is instructed by the microscope - control software. This component directs the probe to controlled - locations according to a scan scheme and plan. + The scan box is instructed by an instance of :ref:`NXprogram`, some control software, + which is not necessarily the same program as for all components of a microscope. + + The scanbox directs the probe of charged particles (electrons, ions) + to controlled locations according to a scan scheme and plan. + + To achieve this task, the scanbox typically contains deflection coils, + which should be modelled as instances of :ref:`NXdeflector`. - - - - - - - - + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + + TODO discuss with the electron microscopists. + + + + diff --git a/contributed_definitions/NXsensor_scan.nxdl.xml b/contributed_definitions/NXsensor_scan.nxdl.xml new file mode 100644 index 0000000000..00ef3e3300 --- /dev/null +++ b/contributed_definitions/NXsensor_scan.nxdl.xml @@ -0,0 +1,198 @@ + + + + + + + Variables used to set a common size for collected sensor data. + + + + The number of scan points measured in this scan. + + + + + Application definition for a generic scan using sensors. + + In this application definition, times should be specified always together + with an UTC offset. + + + + + + + + + + + + + + + Define the program that was used to generate the results file(s) + with measured data and metadata. + + + + Commercial or otherwise defined given name of the program + (or a link to the instrument software). + + + + Either version with build number, commit hash, or description of an + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + + + + + Website of the software. + + + + + + + Contact information of at least the user of the instrument or the + investigator who performed this experiment. Adding multiple users if + relevant is recommended. + + + + Name of the user. + + + + + Name of the affiliation of the user at the point in time when + the experiment was performed. + + + + + Full address (street, street number, ZIP, city, country) + of the user's affiliation. + + + + + Email address of the user. + + + + + Author ID defined by https://orcid.org/. + + + + + Official telephone number of the user. + + + + + + + Describes an environment setup for the experiment. + + All the setting values of the independently scanned controllers are listed under corresponding + NXsensor groups. Similarly, seperate NXsensor groups are used to store the readings from each + measurement sensor. + + For example, in a temperature-dependent IV measurement, the temperature and voltage must be + present as independently scanned controllers and the current sensor must also be present with + its readings. + + + + + Plot of measured signal as a function of the timestamp of when they have been + acquired is also possible. + + + + + For each point in the scan space, either the nominal setpoint of an independently scanned controller + or a representative average value of a measurement sensor is registered. + + The length of each sensor's data value array stored in this group should be equal to the number of scan points + probed in this scan. For every scan point [N], the corresponding sensor value can be picked from index [N]. + This allows the scan to be made in any order as the user describes above in the experiment. We get matching + values simply using the index of the scan point. + + + + + + + + Timestamp for when the values provided in the value field were registered. + + Individual readings can be stored with their timestamps under value_log. This is to timestamp + the nominal setpoint or average reading values listed above in the value field. + + + + + + Free-text describing the data acquisition control: an internal + sweep using the built-in functionality of the controller device, + or a set/wait/read/repeat mechanism. + + + + + + ISO8601 datum when calibration was last performed + before this measurement. UTC offset should be specified. + + + + + + + A list of names of NXsensor groups used as independently scanned controllers. + + + + + A list of names of NXsensor groups used as measurement sensors. + + + + + + + + + + A scan specific representation of the measured signals as a function of the independently controlled environment settings. + Plot of every measured signal as a function of the timestamp of when they have been acquired is also possible. + + + + diff --git a/contributed_definitions/NXsensor_sts.nxdl.xml b/contributed_definitions/NXsensor_sts.nxdl.xml new file mode 100644 index 0000000000..31094bd4e1 --- /dev/null +++ b/contributed_definitions/NXsensor_sts.nxdl.xml @@ -0,0 +1,233 @@ + + + + + + A sensor used to monitor an external condition + + The condition itself is described in :ref:`NXenvironment`. + + + + Sensor identification code/model number + + + + + Name for the sensor + + + + + Short name of sensor used e.g. on monitor display program + + + + + where sensor is attached to ("sample" | "can") + + + + + Defines the axes for logged vector quantities if they are not the global + instrument axes. + + + + + name for measured signal + + + + + + + + + + + + + + + + + + + + + The type of hardware used for the measurement. + Examples (suggestions but not restrictions): + + :Temperature: + J | K | T | E | R | S | Pt100 | Pt1000 | Rh/Fe + :pH: + Hg/Hg2Cl2 | Ag/AgCl | ISFET + :Ion selective electrode: + specify species; e.g. Ca2+ + :Magnetic field: + Hall + :Surface pressure: + wilhelmy plate + + + + + + link to second amplifer circuit with 1MOhm + + + + + Is data collection controlled or synchronised to this quantity: + 1=no, 0=to "value", 1=to "value_deriv1", etc. + + + + + Upper control bound of sensor reading if using run_control + + + + + Lower control bound of sensor reading if using run_control + + + + + nominal setpoint or average value + - need [n] as may be a vector + + + + + + + + Nominal/average first derivative of value + e.g. strain rate + - same dimensions as "value" (may be a vector) + + + + + + + + Nominal/average second derivative of value + - same dimensions as "value" (may be a vector) + + + + + + + + Time history of sensor readings + + + + + Time history of first derivative of sensor readings + + + + + Time history of second derivative of sensor readings + + + + + + + + + + + + + + + For complex external fields not satisfied by External_field_brief + + + + + This group describes the shape of the sensor when necessary. + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a sensor. + + + + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + + + + External sensors connected to the device. For example, T1, temperature of STM + head. T2, temperature of bottom of LHe helium cryostat. T3, temperature of LN2 + nitrogen shield. + + + + + External sensors connected to the device. Pressure of each chamber or ion pump, + such as prepare chamber and analysis chamber + + + + + The power present in the signal as a function of frequency. Used to characterise + the vibration and noise of scanning probes to detect and reduce the impact on + resolution during STM imaging + + + diff --git a/contributed_definitions/NXserialized.nxdl.xml b/contributed_definitions/NXserialized.nxdl.xml new file mode 100644 index 0000000000..2595d99683 --- /dev/null +++ b/contributed_definitions/NXserialized.nxdl.xml @@ -0,0 +1,76 @@ + + + + + + Metadata to a set of pieces of information of a resource that has been serialized. + + A typical use case is the documentation of the source (file) or database (entry) + from which pieces of information have been extracted for consumption in e.g. a + research data management system (RDMS). This may be for reasons of enabling + services such as providing access to normalized information for which reading + again from the resource may not be desired, possibe, or feasible. + + Possible reasons could be the extraction of specific information for caching, + performance reasons, or re-evaluate given pieces of information based on other + views and interaction patterns with the data where information has been formatted + differently by tools than how these pieces of information were originally + serialized. + + + + Answers into what resource the information was serialized. + + + + + + + + + Path to the resource. + + E.g. the name of a file or its absolute or relative path, or the + identifier to a resource in another database. + + + + + Value of the checksum obtain when running algorithm on the resource. + + + + + Name of the algorithm whereby the checksum was computed. + + + + + + + + + Extracted file containing the serialized information. + + + diff --git a/contributed_definitions/NXsimilarity_grouping.nxdl.xml b/contributed_definitions/NXsimilarity_grouping.nxdl.xml new file mode 100644 index 0000000000..74cd0a1771 --- /dev/null +++ b/contributed_definitions/NXsimilarity_grouping.nxdl.xml @@ -0,0 +1,169 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Cardinality of the set. + + + + + Number of numerical labels per object. + + + + + Number of categorical labels per object. + + + + + Total number of similarity groups aka features, objects, clusters. + + + + + Metadata to the results of a similarity grouping analysis. + + Similarity grouping analyses can be supervised segmentation or machine learning + clustering algorithms. These are routine methods which partition the member of + a set of objects/geometric primitives into (sub-)groups, features of + different type. A plethora of algorithms have been proposed which can be applied + also on geometric primitives like points, triangles, or (abstract) features aka + objects (including categorical sub-groups). + + This base class considers metadata and results of one similarity grouping + analysis applied to a set in which objects are either categorized as noise + or belonging to a cluster. + As the results of the analysis each similarity group, here called feature + aka object can get a number of numerical and/or categorical labels. + + + + Number of members in the set which is partitioned into features. + + + + + How many numerical labels does each feature have. + + + + + How many categorical labels does each feature have. + + + + + + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + Numerical identifier have to be strictly increasing. + + + + + + + + Matrix of numerical label for each member in the set. + For classical clustering algorithms this can for instance + encode the cluster_identifier. + + + + + + + + + Matrix of categorical attribute data for each member in the set. + + + + + + + + + + In addition to the detailed storage which members was grouped to which + feature/group summary statistics are stored under this group. + + + + + Total number of members in the set which are categorized as unassigned. + + + + + + + + Total number of members in the set which are categorized as noise. + + + + + + + + + Total number of clusters (excluding noise and unassigned). + + + + + Array of numerical identifier of each feature (cluster). + + + + + + + + + Array of number of members for each feature. + + + + + + + + diff --git a/contributed_definitions/NXsingle_crystal.nxdl.xml b/contributed_definitions/NXsingle_crystal.nxdl.xml new file mode 100644 index 0000000000..44f6e92c30 --- /dev/null +++ b/contributed_definitions/NXsingle_crystal.nxdl.xml @@ -0,0 +1,72 @@ + + + + + + Description of a single crystal material or a single crystalline phase in a material. + + There is the option of using Busing-Levy convention (as orginally designed in NXsample) + or using a more detailed description with NXrotation_set. + + + + This will follow the Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + + + + + + + + Orientation matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + + + + + + + + + UB matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is + the multiplication of the orientation_matrix, given above, + with the :math:`B` matrix which can be derived from the lattice constants. + + + + + + + + + Detailed description of single crystal orientation and misorientation. + + + + + Unit cell of the single crystal. + + + diff --git a/contributed_definitions/NXslip_system_set.nxdl.xml b/contributed_definitions/NXslip_system_set.nxdl.xml new file mode 100644 index 0000000000..4e7d65b5c0 --- /dev/null +++ b/contributed_definitions/NXslip_system_set.nxdl.xml @@ -0,0 +1,85 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of slip systems. + + + + + Base class for describing a set of crystallographic slip systems. + + + + + + + + + + + + + + + + + + Array of Miller indices which describe the crystallographic plane. + + + + + + + + + + Array of Miller indices which describe the crystallographic direction. + + + + + + + + + For each slip system a marker whether the specified Miller indices + refer to the specific slip system or the set of crystallographic equivalent + slip systems of the respective family of slip systems. + + + + + + diff --git a/contributed_definitions/NXspatial_filter.nxdl.xml b/contributed_definitions/NXspatial_filter.nxdl.xml new file mode 100644 index 0000000000..7a0680911d --- /dev/null +++ b/contributed_definitions/NXspatial_filter.nxdl.xml @@ -0,0 +1,85 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of ellipsoids. + + + + + Number of hexahedra. + + + + + Number of cylinders. + + + + + Spatial filter to filter entries within a region-of-interest based on their + position. + + + + Qualitative statement which specifies which spatial filtering with respective + geometric primitives or bitmask is used. These settings are possible: + + * entire_dataset, no filter is applied, the entire dataset is used. + * union_of_primitives, a filter with (rotated) geometric primitives. + All ions in or on the surface of the primitives are considered + while all other ions are ignored. + * bitmasked_points, a boolean array whose bits encode with 1 + which ions should be included. Those ions whose bit is set to 0 + will be excluded. Users of python can use the bitfield operations + of the numpy package to define such bitfields. + + Conditions: + In the case that windowing_method is entire_dataset all entries are processed. + In the case that windowing_method is union_of_primitives, + it is possible to specify none or all types of primitives + (ellipsoids, cylinder, hexahedra). If no primitives are specified + the filter falls back to entire_dataset. + In the case that windowing_method is bitmask, the bitmask has to be defined; + otherwise the filter falls back to entire dataset. + + + + + + + + + + + + diff --git a/contributed_definitions/NXspectrum_set.nxdl.xml b/contributed_definitions/NXspectrum_set.nxdl.xml new file mode 100644 index 0000000000..a30144b851 --- /dev/null +++ b/contributed_definitions/NXspectrum_set.nxdl.xml @@ -0,0 +1,240 @@ + + + + + + + + Number of scan points. + + + + + Number of pixel in the slow direction. + + + + + Number of pixel in the fast direction. + + + + + Number of energy bins. + + + + + Base class container for reporting a set of spectra. + + + + + Details how spectra were processed from the detector readings. + + + + Resolvable data artifact (e.g. filename) from which the all values in + the :ref:`NXdata` instances in this :ref:`NXspectrum_set` were + loaded during parsing. + + + + + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXspectrum_set` instance. + + + + + Link or name of an :ref:`NXdetector` instance with which the data were + collected. + + + + + + + + Collected spectra for all pixels of a rectangular region-of-interest. + + This representation supports rectangular scan pattern with equidistant + energy bins. For randomly or dissimilarly spaced scan points + use collection instead. + + + + Counts + + + + + + + + + Counts + + + + + + + Coordinate along y direction. + + + + + + + Pixel coordinate along y direction + + + + + + Coordinate along x direction. + + + + + + + Pixel coordinate along x direction + + + + + + Energy axis + + + + + + + Energy + + + + + + + + Accumulated counts over all pixels of the region-of-interest. + This representation supports a rectangular scan pattern with + equidistant energy bins. + + + + Accumulated counts + + + + + + + Counts + + + + + + + Energy axis + + + + + + + Energy + + + + + + + Collected spectra for each scan point. + + This representation supports equidistant energy bins. + For rectangular sampling use stack and summary instead. + + + + Counts + + + + + + + + Counts + + + + + + + Scan point identifier + + + + + + + Scan point identifier + + + + + + Energy axis + + + + + + + Energy + + + + + diff --git a/contributed_definitions/NXspectrum_set_em_auger.nxdl.xml b/contributed_definitions/NXspectrum_set_em_auger.nxdl.xml deleted file mode 100644 index e41ce1a860..0000000000 --- a/contributed_definitions/NXspectrum_set_em_auger.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of auger electron energy spectra. - - - - diff --git a/contributed_definitions/NXspectrum_set_em_cathodolum.nxdl.xml b/contributed_definitions/NXspectrum_set_em_cathodolum.nxdl.xml deleted file mode 100644 index 20ce7bf72d..0000000000 --- a/contributed_definitions/NXspectrum_set_em_cathodolum.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of cathodoluminescence spectra. - - - - diff --git a/contributed_definitions/NXspectrum_set_em_eels.nxdl.xml b/contributed_definitions/NXspectrum_set_em_eels.nxdl.xml deleted file mode 100644 index 7e44d1f118..0000000000 --- a/contributed_definitions/NXspectrum_set_em_eels.nxdl.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - Container for reporting a set of electron energy loss spectra. - - - - diff --git a/contributed_definitions/NXspectrum_set_em_xray.nxdl.xml b/contributed_definitions/NXspectrum_set_em_xray.nxdl.xml deleted file mode 100644 index 916f1376a3..0000000000 --- a/contributed_definitions/NXspectrum_set_em_xray.nxdl.xml +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - - Number of scan points - - - - - Number of pixel per Kikuchi pattern in the slow direction - - - - - Number of pixel per Kikuchi pattern in the fast direction - - - - - Number of X-ray photon energy (bins) - - - - - Number of identified elements - - - - - Number of peaks - - - - - Container for reporting a set of energy-dispersive X-ray spectra. - - Virtually the most important case is that spectra are collected in - a scanning microscope (SEM or STEM) for a collection of points. - The majority of cases use simple d-dimensional regular scan pattern, - such as single point, line profiles, or (rectangular) surface mappings. - The latter pattern is the most frequently used. - - For now the base class provides for scans where the settings, - binning, and energy resolution is the same for each scan point. - - `IUPAC instead of Siegbahn notation <https://doi.org/10.1002/xrs.1300200308>`_ should be used. - - - - Collected X-ray counts chunked based on rectangular images. - - This representation supports only rectangular scan pattern. - - - - - - - - - - - X-ray photon counts - - - - - - - - - Label for the y axis - - - - - - - - - - Label for the x axis - - - - - - - - - - X-ray energy - - - - - - - Details about computational steps how peaks were indexed as elements. - - - - Given name of the program that was used to perform this computation. - - - - Program version plus build number, commit hash, or description of an ever persistent resource - where the source code of the program and build instructions can be found so that the program - can be configured in such a manner that the result file is ideally recreatable yielding the - same results. - - - - - - Name and location of each X-ray line which was indexed as a known ion. - For each ion an NXion instance should be created which specifies - the origin of the signal. For each ion also the relevant IUPAC notation - X-ray lines should be specified. - - - - - IUPAC notation identifier of the line which the peak represents. - - This can be a list of IUPAC notations for (the seldom) case that - multiple lines are group with the same peak. - - - - - - - List of the names of identified elements. - - - - - - - - Individual element-specific EDX/EDS/EDXS/SXES mapping - - A composition map is an image whose intensities for each pixel are the - accumulated X-ray quanta *under the curve(s)* of a set of peaks. - - - - Given name of the program that was used to perform this computation. - - - - Program version plus build number, commit hash, or description of an ever persistent resource - where the source code of the program and build instructions can be found so that the program - can be configured in such a manner that the result file is ideally recreatable yielding the - same results. - - - - - - A list of strings of named instances of NXpeak from indexing - whose X-ray quanta where accumulated for each pixel. - - - - - - - - Human-readable, given name to the image. - - - - - Individual element-specific maps. Individual maps should - each be a group and be named according to element_names. - - - - - - - - - - Accumulated X-ray photon counts - - - - - - - - - Label for the y axis - - - - - - - - - - Label for the x axis - - - - - - - diff --git a/contributed_definitions/NXspindispersion.nxdl.xml b/contributed_definitions/NXspindispersion.nxdl.xml index 71668a6480..2153672719 100644 --- a/contributed_definitions/NXspindispersion.nxdl.xml +++ b/contributed_definitions/NXspindispersion.nxdl.xml @@ -1,13 +1,34 @@ - + - + + Subclass of NXelectronanalyser to describe the spin filters in photoemission experiments. - Type of spin detector, VLEED, SPLEED, Mott, etc. + Type of spin detector, VLEED, SPLEED, Mott, etc. @@ -22,7 +43,7 @@ - Energy of the spin-selective scattering + Energy of the spin-selective scattering diff --git a/contributed_definitions/NXstage_lab.nxdl.xml b/contributed_definitions/NXstage_lab.nxdl.xml index 5aa4c431a2..782a72893c 100644 --- a/contributed_definitions/NXstage_lab.nxdl.xml +++ b/contributed_definitions/NXstage_lab.nxdl.xml @@ -1,79 +1,106 @@ - + - + + - A stage lab can be used to hold, align, orient, and prepare a specimen. + Base class for a stage (lab) used to hold, orient, and prepare a specimen. - Modern stages are multi-functional devices. Many of which offer a controlled - environment around (a part) of the specimen. Stages enable experimentalists - to apply stimuli. A stage_lab is a multi-purpose/-functional tools which - can have multiple actuators, sensors, and other components. + Modern stages are multi-functional devices. Stages provide a controlled + environment around the specimen. Stages enable experimentalists to apply + controlled external stimuli on the specimen. A stage_lab is a multi-purpose + /-functional tool that is constructed from multiple actuators, sensors, + and other components. - With such stages comes the need for storing various (meta)data - that are generated while manipulating the sample. + With such stages comes the need for storing various (meta)data + that are generated while working and modifying the sample. - Modern stages realize a hierarchy of components: For example the specimen - might be mounted on a multi-axial tilt rotation holder. This holder is - fixed in the support unit which connects the holder to the rest of the - microscope. + Modern stages realize a hierarchy of components. Two examples are given to help + clarify how :ref:`NXstage_lab` instances should be used: Take a specimen that is + mounted on a multi-axial tilt rotation holder. This holder is fixed in the + support unit which connects the holder to the rest of the instrument. + Evidently different components are all considerable as to represent instances + of stages. - In other examples, taken from atom probe microscopy, researchers may work - with wire samples which are clipped into a larger fixing unit for - convenience and enable for a more careful specimen handling. - This fixture unit is known in atom probe jargon as a stub. - Stubs in turn are positioned onto pucks. - Pucks are then loaded onto carousels. - A carousel is a carrier unit with which eventually entire sets of specimens - can be moved in between parts of the microscope. + In another example, taken from atom probe microscopy, researchers may work + with wire samples which are clipped into a larger fixing unit to enable + careful specimen handling. Alternatively, a microtip is a silicon post + upon which e.g. an atom probe specimen is mounted. + Multiple microtips are grouped into a microtip array to conveniently enable + loading of multiple specimens into the instrument with fewer operations. + That microtip array is fixed on a holder. Fixture units in atom probe are known + as stubs. Stubs in turn are positioned onto pucks. Pucks are then loaded onto + carousels. A carousel is a carrier unit with which eventually entire sets of + specimens can be moved in between parts of the microscope. All of these units + can be considered stage_lab instances. - An NXstage_lab instance reflects this hierarchical design. The stage is the - root of the hierarchy. A stage carries the holder. - In the case that it is not practical to distinguish these two layers, - the holder should be given preference. + The :ref:`NXstage_lab` base class reflects this hierarchy. To cover for an as flexible + design of complex stages as possible, users should nest multiple instances of + :ref:`NXstage_lab` according to their needs to reflect the differences between what + they consider as the holder and what they consider is the stage. + The alias field can be used to specify the community jargon if necessary. - Some examples for stage_labs in applications: - - * A nanoparticle on a copper grid. The copper grid is the holder. - The grid itself is fixed to the stage. - * An atom probe specimen fixed in a stub. In this case the stub can be - considered the holder, while the cryostat temperature control unit is - a component of the stage. - * Samples with arrays of specimens, like a microtip on a microtip array - is an example of a three-layer hierarchy commonly employed for - efficient sequential processing of atom probe experiments. - * With one entry of an application definition only one microtip should be - described. Therefore, the microtip is the specimen, - the array is the holder and the remaining mounting unit - that is attached to the cryo-controller is the stage. - * For in-situ experiments with e.g. chips with read-out electronics - as actuators, the chips are again placed in a larger unit. - * Other examples are (quasi) in-situ experiments where experimentalists - anneal or deform the specimen via e.g. in-situ tensile testing machines - which are mounted on the specimen holder. + However, a much clearer approach to reflect the hierarchy of all :ref:`NXstage_lab` + instances is postfix each instance named stage_lab with integers starting + from 1 as the top level unit. + In the microtip example one could thus use stage_lab1 for the microtip, + stage_lab2 for the microtip array, stage_lab3 holder, etc. + The depends_on keyword should be used to additional clarify the hierarchy + especially when users decide to not follow the above-mentioned postfixing + notation or when is not obvious from the postfixes which stage_lab is at + which level of the stage_lab hierarchy. - To cover for an as flexible design of complex stages, users should nest - multiple instances of NXstage_lab objects according to their needs to reflect - the differences between what they consider as the holder and what - they consider is the stage. + Some examples for stage_labs in applications: - Instances should be named with integers starting from 1 as the top level unit. - In the microtip example stage_lab_1 for the stage, stage_lab_2 for the holder - (microtip array), stage_lab_3 for the microtip specimen, respectively. - The depends_on keyword should be used with relative or absolute naming inside - the file to specify how different stage_lab instances build a hierarchy - if this is not obvious from numbered identifiers like the stage_lab_1 to - stage_lab 3 example. The lower it is the number the higher it is the - rank in the hierarchy. + * A nanoparticle on a copper grid. The copper grid is the holder. + The grid itself is fixed to a stage. + * An atom probe specimen fixed in a stub. In this case the stub can be + considered the holder, while the cryostat temperature control unit is + a component of the stage. + * Samples with arrays of specimens, like a microtip on a microtip array + is an example of an at least three-layer hierarchy commonly employed for + efficient sequential processing of atom probe experiments. + * With one entry of an application definition only one microtip should be + described. Therefore, the microtip is the specimen, + the array is the holder and the remaining mounting unit + that is attached to the cryo-controller is the stage. + * For in-situ experiments with e.g. chips with read-out electronics + as actuators, the chips are again placed in a larger unit. A typical + example are in-situ experiments using e.g. the tools of `Protochips <https://www.protochips.com>`_. + * Other examples are (quasi) in-situ experiments where experimentalists + anneal or deform the specimen via e.g. in-situ tensile testing machines + which are mounted on the specimen holder. For specific details and inspiration about stages in electron microscopes: - * `Holders with multiple axes <https://www.nanotechnik.com/e5as.html>`_ - * `Chip-based designs <https://www.protochips.com/products/fusion/fusion-select-components/>`_ + * `Holders with multiple axes <https://www.nanotechnik.com/e5as.html>`_ + * `Chip-based designs <https://www.protochips.com/products/fusion/fusion-select-components/>`_ * `Further chip-based designs <https://www.nanoprobetech.com/about>`_ - * `Stages in transmission electron microscopy <https://doi.org/10.1007/978-3-662-14824-2>`_ (page 103, table 4.2) + * `Stages in transmission electron microscopy <https://doi.org/10.1007/978-3-662-14824-2>`_ (page 103, table 4.2) * `Further stages in transmission electron microscopy <https://doi.org/10.1007/978-1-4757-2519-3>`_ (page 124ff) * `Specimens in atom probe <https://doi.org/10.1007/978-1-4614-8721-0>`_ (page 47ff) * `Exemplar micro-manipulators <https://nano.oxinst.com/products/omniprobe/omniprobe-200>`_ + + We are looking forward to suggestions from the scientists. @@ -86,52 +113,59 @@ electrical_biasing_chip, liquid_cell_chip - + - Given name/alias for the components making the stage. + Free-text field to give a term how that a stage_lab at this level of the + stage_lab hierarchy is commonly referred to. Examples could be stub, + puck, carousel, microtip, clip, holder, etc. - - + - Ideally, a (globally) unique persistent identifier, link, - or text to a resource which gives further details. + The interpretation of this tilt should be specialized + and thus detailed via the application definition. - + - Should be defined by the application definition. + The interpretation of this tilt should be specialized + and thus detailed via the application definition. - + - Should be defined by the application definition. + The interpretation of this tilt should be specialized + and thus detailed via the application definition. - + - Should be defined by the application definition. - - - - - Should be defined by the application definition. + The interpretation of this tilt should be specialized + and thus detailed via the application definition. - + Voltage applied to the stage to decelerate electrons. - - - The rotation, tilt and position of stage components can be specified - either via NXtransformations or via the tilt_1, tilt_2, rotation, - and position fields. - - + + diff --git a/contributed_definitions/NXsts.nxdl.xml b/contributed_definitions/NXsts.nxdl.xml new file mode 100644 index 0000000000..01f14143b6 --- /dev/null +++ b/contributed_definitions/NXsts.nxdl.xml @@ -0,0 +1,901 @@ + + + + + + + Application definition for temperature-dependent IV curve measurements + #2023.19.7 This Nexus file is currently only for STS data, it will be updated to handle the + STM image mode in the future with a focus on bias spectroscopy in Scanning Tunneling Microscopy. + + In this application definition, times should be specified always together with a UTC offset. + + This is the application definition describing temperature (T) dependent current voltage (IV) curve + measurements. For this, a temperature is set. After reaching the temperature, a voltage sweep + is performed. For each voltage, a current is measured. + Then, the next desired temperature is set and an IV measurement is performed. + The data can be visualized in a tensor with: + I (NXsensor_C, NXsoftware_Read_offset, NXcircuit) + parameters: + V has (NXsource+offset, NXsoftware_Scan_offset, NXsensor_V, NXcircuit) + T has (NXsource, NXsoftware_Scan_offset, NXsensor_T) + x has (NXsoftware_Scan_offset) + y has (NXsoftware_Scan_offset) + z has (NXsoftware_Scan_offset) + + + + + + + + + + Name of the experiment where the application is applicable. + + + + + + + + + The equipments and techniques as well as the parameter settings and reference signals + are used during the experiments used in Scanning Tunneling Microscopy (STM). + + + + + + + + + + + The name of the output file, with the number of scans at the end. (e.g. + 221122_Au_5K00014) + + + + + The name of the series output file, which represents only the public part of the + output file. (e.g. 221122_Au_5K) + + + + + Path to storage of output files. + (e.g. Path C:\Users\SPM-PEEM\Desktop\DATA_Nanonis\20220711_CreaTec_Service_Benchmarks_LHe\Nanonis-Session-PMD100-HVHU_CreaTec_Service_PalmaLabBerlin220711) + + + + + Descriptive comments for this experiment, added by the experimenter, coming from the + output file. (e.g. Comment01 SYNC & Filter LP 8order WITHDRAW 600 steps, locked Au(111), + 50pA, 100 mV set point, 1mV DCA, 973Hz,138 1st H, -84 2nd H) + + + + + + Hardware type used in SPM experiment, includes hardware manufacturers and type. + (e.g. Nanonis BP5e) + + + + + + Type of software used in SPM experiments, such as software version serial number, UI and + RT probe release method. (e.g. SW Version Generic 5e -- RT Release 10771) + + + + Version of the software. + + + + + + + The Amplifier description that improves or helps to determine tunnel current (current + between tip and bias). + + + + + + + Status of Lock-in device whether while performing the experiment + + + + + + This is the signal on which the modulation (sine) will be added. + + + + + + + The signal is modulated by adding the frequency of the sine modulation. The + modulation frequency spans can be from 10 mHz to 40 kHz, corresponding to the output filter + cut-off range. When dealing with harmonics, it's essential to ensure that the + harmonic frequencies remain below ~100 kHz, which aligns with the input filter cut-off. + Be mindful that hardware filters might impact the amplitude as the signal approaches + their cut-off frequencies." (e.g. 973E+0) + + + + + + The amplitude (in physical units of modulated signal) of the sine modulation. + + + + + + The input signal (STS signal) will be demodulated, in order to determine the amplitude + and phase at the frequency set in the Frequency field or harmonics, such as current, + bias, et.al. + + + + + + N denotes 1 or 2. The order of the harmonic oscillation to be detected in the demodulated + signal should be considered relative to the modulation frequency. When dealing with + higher harmonics, it's essential to ensure that their frequencies do not surpass + the analogue signal bandwidth (e.g. harmonic_order_1). + + + + + + Reference phase for the sine on the demodulated signal with respect to the + modulation signal. The determined phase is displayed with respect to the + reference phase. + + + + + + + + + Applied a voltage between tip and sample. + + + + + + + + + Temperature of STM head. Note: At least one field from stm_head_temperature, + cryo_bottom_temp and cryo_sheild_temp must be provided. + + + + + Temperature of liquid helium cryostat. Note: At least one field from + stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp must be provided. + + + + + Temperature of liquid nitrogen shield. Temperature 3 (K) (e.g 78.00000E+0). Note: At + least one field from stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp + must be provided. + + + + + + + Configuration for piezoelectric scanner used to move tip along X and Y direction. The + material of the Piezoelectric scanner composed of polycrystalline solids and sensitive to + applied voltage. + + + + The name of calibration type. (e.g. LHe) + + + + + N denotes X or Y or Z. There are three parameters in the X, Y, and Z directions, + along with three available controls: Calibration (m/V), Range (m), and HV gain. Only + two of these parameters are required to define the calibration. Consequently, when any + value is changed, one of the other values will be automatically updated. (e.g. calib_X = 3.8E-9) + + + + + N denotes X or Y or Z. In some systems, there is an HV gain readout feature. For + these systems, the HV gain should be automatically adjusted whenever the gain is + changed at the high voltage amplifier. (e.g. 14.5) + + + + + + N denotes X or Y. There are 2 parameters in X and Y directions, and tilt needs to be + adjusted according to the actual surface. (in degrees, first order correction). + + + + + + N denotes X or Y. There are 2 parameters in X and Y directions. (can be set + approximately to the length of the piezotube). + + + + + N denotes X or Y. There are 2 parameters in X and Y directions. If you know them, + you can enter the 2nd order piezo characteristics to compensate for it. The + following equation shows the interpretation of the 2nd order correction parameter: + For the X-piezo: "Ux = 1/cx · X + cxx · X2" with units: + [V] = [V/m] · [m] + [V/m2] · [m2] where cx is the calibration of the piezo X and cxx + is the 2nd order correction. (V/m^2). (e.g. 0E+0) + + + + + N denotes X, Y or Z. There are 3 parameters in X, Y and Z directions. Define the + drift speed for all three axes. When the compensation is on, the piezos will start to + move at that speed. (e.g. 0E+0) + + + + + Use the button to enable or disable the drift compensation. (e.g. FALSE) + + + + + + Describes an environment setup for a temperature-dependent IV measurement experiment. + The temperature and voltage must be present as independently scanned controllers and + the current sensor must also be present with its readings. + + + + + This is set-point of tip current (in the constant current mode should be equal to set-point, + in the constant height mode means the real tunnelling current between tip and sample). + + + + + Value of calibration that comes as A/V. + + + + + + + + + + Clarify the frame laboratory frame. + + + + The scanning area in x position in the frame. (e.g. -890.53E-12) + + + + + The scanning area in y position in the frame. (e.g. 29.6968E-9) + + + + + The scanning area in z position in the frame. (e.g. 130.5E-9) + + + + + + Indicate the relative tip position z between tip and sample. The tip position can also + be varied when the z_controller is not running. (e.g. 130.5E-9) + + + + + + + + + + Time during which the spectroscopy data are acquired and averaged. (e.g. 150E-6) + + + + + Number of sweeps to measure and average. (e.g. 100) + + + + + The start bias values of the sweep. (e.g. -300E-3) + + + + + The end bias values of the sweep. (e.g. 300E-3) + + + + + The sweep number of points is defined as the maximum spectrum resolution, which + is equal to the bias sweep window divided by the number of pixels. (e.g. 4096) + + + + + The Z position is recorded and averaged for a certain duration both before and + after the sweep. After the initial Z averaging time, if "Z-Controller to Hold" + is selected, the Z-Controller is set to hold mode, and the tip is positioned at + the previously averaged Z position (adjusted by the Z offset). (e.g. 100E-3) + + + + + + + The bandwidth of the Hardware and/or Software is instrument specific. + For example, Nanonis Generic 5 has 'RT Frequency' (e.g. 20E+3). + + + + + The Signals Period represents the rate at which signals are transferred to + the host computer, which operates the control software. This rate may + be 10 times lower than the sampling rate, as the real-time engine internally + oversamples the signal. If desired, you may have the option to reduce the oversampling + to 1, enabling higher frequency resolution in the Spectrum Analyzer. (e.g. 10) + + + + + The update rate is utilized in various processes, including the History Graph, + Auto-Approach, and multiple Programming Interface functions. It may be + configured to a 20 ms interval. Any additional timings must strictly be integer + multiples of this base value. While it is possible to set these additional + timings to different values, the actual timing value will automatically be + adjusted to become a multiple of the Acquisition Period. (e.g. 20E-3) + + + + + The update rate of animated graphical indicators, such as graphs and sliders, + can be adjusted. A normal value may be 40 ms, which corresponds to 25 updates + per second. Increasing this period can help reduce the processor load on the + graphical user interface, particularly on slower computers. It is important to + note that this update rate solely impacts the user interface and does not affect + measurements in any manner. (e.g. 20E-3) + + + + + The update rate of digital indicators, such as the numbers displayed, can be set + to 3 updates per second, equivalent to 300 ms. This interval is sufficient for + the user interface and does not impact measurements in any manner. (e.g. 300E-3) + + + + + The Measurements period determines the integration time required for precise + measurements, primarily utilized in sweep modules. It is particularly useful for + tasks such as recording force-distance curves or cantilever resonances. For + swift measurements with small steps, a value of 40 ms is often adequate. For + regular use, a range of 300-500 ms may be recommended, but when capturing the + resonance of a high-Q cantilever, longer values in the range of several seconds + might be necessary. Usually, this parameter does not require manual adjustment + within this module, as the sweep modules automatically set this value according + to the sweep timings. (e.g. 500E-3) + + + + + + + + + + Also clarify the frame for the ROI of the scan in lab frame, the middle of the lab + frame is (0, 0), and positive in x means right and in y means up. + + + + + + + The scan channels are selected by users. (e.g. (A);Bias (V);Z (m);LI Demod 2 X + (A);LI Demod 2 Y (A);LI Demod 1 X (A);LI Demod 1 Y (A)) + + + + + + + Configure the scan frame like x position; y position; width; height. (e.g. + 3.11737E-9;29.1583E-9;15E-9;15E-9;0E+0) + + + + + Scan resolution by setting the Lines equal to Pixels. (e.g. 512) + + + + + Define the image resolution. (e.g. 512) + + + + + Define the scan forward speed in the forward direction. (m/s) (e.g. 11.7187E-9) + + + + + Define the scan backward speed in the forward direction. (m/s) (e.g. 11.7187E-9) + + + + + + + + + + + + Link to target:/NXentry/NXinstrument/stm_head_temp + + + + + + Link to target:/NXentry/NXinstrument/cryo_bottom_temp + + + + + + Link to target:/NXentry/NXinstrument/temp_cryo_shield + + + + + + Link to target:/NXentry/NXinstrument/NXlock_in/modulation_signal + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/NXintegration_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/number_of_sweeps + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_start + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_end + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/num_pixel + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_avg_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/rt_frequency + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/signals_oversampling + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/acquisition_period + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/animations_period + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/indicators_period + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/measurements_period + + + + + + + + + Link to target:/NXentry/NXinstrument/NXsample_bias/bias + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current + + + + + + Link to target:/NXentry/NXnstrument/NXsample_bias/bias_calibration + + + + + Link to target:/NXentry/NXinstrument/NXsample_bias/bias_offset + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_calibration + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_offset + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_gain + + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_offset + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/settling_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_ccontroller_hold + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/record_final_z + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/first_settling_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/end_settling_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_control_time + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/max_slew_rate + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/backward_sweep + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_name + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_status + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/set_point + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/p_gain + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/i_gain + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/time_const + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/tip_lift + + + + + + + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/switchoff_delay + + + + + + To describe sample and other constaints that applied on sample before scanning. + + + + At this moment no base class available that can track entire sample preparation. + + + + + + + This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. + There should also be two more fields called temperature and voltage containing the setpoint values. + There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension + equal to the number of voltage setpoints. + axes: bias_calc + signals: + li_demod_[1;2]_[X/Y]_[-;bwd;filt;bwd_filt] + current_[-;bwd;filt;bwd_filt] + temperature + x + y + z + + + + + + + + + + + + diff --git a/contributed_definitions/NXsubsampling_filter.nxdl.xml b/contributed_definitions/NXsubsampling_filter.nxdl.xml new file mode 100644 index 0000000000..2253cbf9a4 --- /dev/null +++ b/contributed_definitions/NXsubsampling_filter.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Settings of a filter to sample entries based on their value. + + + + Triplet of the minimum, increment, and maximum value which will + be included in the analysis. The increment controls which n-th entry to take. + + Take as an example a dataset with 100 entries (their indices start at zero) + and the filter set to 0, 1, 99. This will process each entry. + 0, 2, 99 will take each second entry. 90, 3, 99 will take only each third + entry beginning from entry 90 up to 99. + + + + + + diff --git a/contributed_definitions/NXsubstance.nxdl.xml b/contributed_definitions/NXsubstance.nxdl.xml new file mode 100644 index 0000000000..6d246ca224 --- /dev/null +++ b/contributed_definitions/NXsubstance.nxdl.xml @@ -0,0 +1,119 @@ + + + + + + A form of matter with a constant, definite chemical composition. + + Examples can be single chemical elements, chemical compunds, or alloys. + For further information, see https://en.wikipedia.org/wiki/Chemical_substance. + + + + User-defined chemical name of the substance + + + + + Molecular mass of the substance + + + + + Unique numeric CAS REGISTRY number of the sample chemical content + For further information, see https://www.cas.org/. + + + + + CAS REGISTRY name of the sample chemical content + + + + + CAS REGISTRY URI + + + + + CAS REGISTRY image + + + + + Synonyms in the CAS system. + + + + + String InChi identifier. + The InChI identifier expresses chemical structures in terms of atomic connectivity, + tautomeric state, isotopes, stereochemistry and electronic charge in order to + produce a string of machine-readable characters unique to the respective molecule. + For further information, see https://iupac.org/who-we-are/divisions/division-details/inchi/. + + + + + Condensed, 27 character InChI key. + Hashed version of the full InChI (using the SHA-256 algorithm). + + + + + Name according to the IUPAC system (standard). + For further information, see https://iupac.org/. + + + + + Identifier in the SMILES (Simplified Molecular Input Line Entry System) system + For further information, see https://www.daylight.com/smiles/. + + + + + Canonical version of the smiles identifier + + + + + The chemical formula specified using CIF conventions. + Abbreviated version of CIF standard:107 + This is the *Hill* system used by Chemical Abstracts. + + * 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. + + + diff --git a/contributed_definitions/NXtransmission.nxdl.xml b/contributed_definitions/NXtransmission.nxdl.xml new file mode 100644 index 0000000000..c56878d6da --- /dev/null +++ b/contributed_definitions/NXtransmission.nxdl.xml @@ -0,0 +1,356 @@ + + + + + + + + Variables used throughout the experiment + + + + Number of wavelength points + + + + + Number of scans + + + + + Application definition for transmission experiments + + + + This application definition + + + + An application definition for transmission. + + + + Version number to identify which definition of this application definition was + used for this entry/data. + + + + + URL where to find further material (documentation, examples) relevant to the + application definition. + + + + + + + + + Start time of the experiment. + + + + + Unique identifier of the experiment, such as a (globally persistent) + unique identifier. + + * The identifier is usually defined by the facility or principle + investigator. + * The identifier enables to link experiments to e.g. proposals. + + + + + An optional free-text description of the experiment. However, details of the + experiment should be defined in the specific fields of this application + definition rather than in this experiment description. + + + + + + + Commercial or otherwise defined given name to the program that was + used to generate the result file(s) with measured data and metadata. + + + + + Version number of the program that was used to generate the result + file(s) with measured data and metadata. + + + + + Website of the software + + + + + + Contact information of at least the user of the instrument or the investigator + who performed this experiment. Adding multiple users if relevant is recommended. + + + + Name of the user. + + + + + Name of the affiliation of the user at the point in time when the experiment was + performed. + + + + + Street address of the user's affiliation. + + + + + Email address of the user. + + + + + Author ID defined by reasearch id services, e.g. orcid (https://orcid.org/). + + + + + Telephone number of the user. + + + + + + + Manufacturer of the instrument. + + + + + Common beam mask to shape the incident beam + + + + The height of the common beam in percentage of the beam + + + + + + If true, the incident beam is depolarized. + + + + + Polarizer value inside the beam path + + + + + Attenuator in the reference beam + + + + + + Attenuator in the sample beam + + + + + + + Wavelength value(s) used for the measurement. + An array of 1 or more elements. Length defines N_wavelenghts + + + + + + + + Overall spectral resolution of this spectrometer. + If several gratings are employed the spectral resoultion + should rather be specified for each grating inside the + NXgrating group of this spectrometer. + + + + + Diffraction grating, as could be used in a monochromator. + If two or more gratings were used, define the angular + dispersion and the wavelength range (min/max wavelength) + for each grating and make sure that the wavelength ranges + do not overlap. The dispersion should be defined for the + entire wavelength range of the experiment. + + + + Dispersion of the grating in nm/mm used. + + + + + The blaze wavelength of the grating used. + + + + + Overall spectral resolution of the instrument + when this grating is used. + + + + + Wavelength range in which this grating was used + + + + + + + + + + + Wavelength range in which this detector was used + + + + + + + + Detector type + + + + + + + + + + Response time of the detector + + + + + Detector gain + + + + + Slit setting used for measurement with this detector + + + + + + + + + + + + An array of relative scan start time points. + + + + + + + + Resulting data from the measurement. + The length of the 2nd dimension is + the number of time points. + If it has length one the time_points + may be empty. + + + + + + + + + The lamp used for illumination + + + + The type of lamp, e.g. halogen, D2 etc. + + + + + + + + + The spectrum of the lamp used + + + + + + + + Wavelength range in which the lamp was used + + + + + + + + + + + Properties of the sample measured + + + + + + A default view of the data emitted intensity vs. wavelength. + From measured_data plot intensity and wavelength. + + + + We recommend to use wavelength as a default attribute, but it can be + replaced by any suitable parameter along the X-axis. + + + + + diff --git a/contributed_definitions/NXunit_cell.nxdl.xml b/contributed_definitions/NXunit_cell.nxdl.xml new file mode 100644 index 0000000000..7222cfc620 --- /dev/null +++ b/contributed_definitions/NXunit_cell.nxdl.xml @@ -0,0 +1,225 @@ + + + + + + + + Number of atom positions. + + + + + Description of a unit cell, i.e., the crystal structure of a single + thermodynamic phase. + + + + Identifier of an entry resolvable via crystallographic_database + which was used for creating this structure model. + + + + + Name of the crystallographic database to resolve + crystallographic_database_identifier e.g. COD, ICSD, or others. + + + + + A lattice system is a group of lattices with the same set of lattice point groups. + For further information, see https://en.wikipedia.org/wiki/Crystal_system. + + + + + + + + + + + + + + Crystallographic space group. + A space group is the symmetry group of a repeating pattern in space. + For further information, see International Table for Crystallography (https://it.iucr.org/). + + + + + Crystallographic point group. + A crystallographic point group is a set of symmetry operations, corresponding to one of the point groups in three dimensions, + such that each operation (perhaps followed by a translation) would leave the structure of a crystal unchanged. + This field should use Schoenflies notation (see Schoenflies, A., Krystallsysteme und Krystallstructur, 1891). + For further information, see https://dictionary.iucr.org/Point_group. + + + + + Laue group (also called Laue class). + The Laue classes are eleven geometric crystal classes containing centrosymmetric crystallographic types of point groups and their subgroups. + When absorption is negligible and Friedel's law applies, it is impossible to distinguish by diffraction between a centrosymmetric point group + and one of its non-centrosymmetric subgroups; only point groups belonging to different Laue classes can then be distinguished. + For further information, see https://dictionary.iucr.org/Laue_class. + + + + + + Crystallography unit cell parameters a, b, and c + + + + + + + + Crystallography unit cell vector a + + + + + + + For definining which coordinate system the unit cell vector a is defined in. + + + + + + Crystallography unit cell vector b + + + + + + + For definining which coordinate system the unit cell vector b is defined in. + + + + + + Crystallography unit cell vector c + + + + + + + For definining which coordinate system the unit cell vector c is defined in. + + + + + + Crystallography unit cell angles alpha, beta, and gamma + + + + + + + + Volume of the unit cell + + + + + + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + + + + + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + + + + + Identifier for the phase. + The value 0 is reserved for the unknown phase which represents the null-model + that no phase model was sufficiently significantly confirmed. + + + + + Trivial name of the phase/alias. + + + + + Labels for each atom position + + + + + + + + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) <https://doi.org/10.1017/S1431927621012241>`_ + + + + + + + + Atom positions x, y, z. + + + + + + + + Reference to an instance of NXcoordinate_system whereby the positions can be + resolved. + + + + + + Relative occupancy of the atom position. + + + + + + + + For definining which coordinate system the unit cell parameters are defined in. + + + diff --git a/contributed_definitions/NXwaveplate.nxdl.xml b/contributed_definitions/NXwaveplate.nxdl.xml new file mode 100644 index 0000000000..e5c76dbfca --- /dev/null +++ b/contributed_definitions/NXwaveplate.nxdl.xml @@ -0,0 +1,173 @@ + + + + + + + + + Size of the wavelength array for which the refractive index of the material + and/or coating is given. + + + + + Number of discrete wavelengths for which the waveplate is designed. If it + operates for a range of wavelengths then N_wavelengths = 2 and the minimum + and maximum values of the range should be provided. + + + + + A waveplate or retarder. + + + + Type of waveplate (e.g. achromatic waveplate or zero-order waveplate). + + + + + + + + + + + + + + If you selected 'other' in type describe what it is. + + + + + Specify the retardance of the waveplate (e.g. full-wave, half-wave + (lambda/2), quarter-wave (lambda/4) plate). + + + + + + + + + + Discrete wavelengths for which the waveplate is designed. If the + waveplate operates over an entire range of wavelengths, enter the minimum + and maximum values of the wavelength range (in this case + N_wavelengths = 2). + + + + + + + + Diameter of the waveplate. + + + + + Clear aperture of the device (e.g. 90% of diameter for a disc or 90% of + length/height for square geometry). + + + + + + Describe the material of the substrate of the wave plate in + substrate/substrate_material and provide its index of refraction in + substrate/index_of_refraction_substrate, if known. + + + + Specify the material of the wave plate. If the device has a + coating it should be described in coating/coating_material. + + + + + Thickness of the wave plate substrate. + + + + + Complex index of refraction of the wave plate substrate. Specify at + given wavelength (or energy, wavenumber etc.) values. + + + + + + + + + + Is the wave plate coated? If yes, specify the type and material of the + coating and the wavelength range for which it is designed. If known, you + may also provide its index of refraction. + + + + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + + + + + Specify the coating material. + + + + + Thickness of the coating. + + + + + Wavelength range for which the coating is designed. Enter the minimum + and maximum values of the wavelength range. + + + + + + + + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + + + + + + + + + + Average reflectance of the waveplate in percentage. + + + diff --git a/contributed_definitions/NXxrd.nxdl.xml b/contributed_definitions/NXxrd.nxdl.xml new file mode 100644 index 0000000000..7c55fd9de1 --- /dev/null +++ b/contributed_definitions/NXxrd.nxdl.xml @@ -0,0 +1,99 @@ + + + + + + + NXxrd on top of NXmonopd + + + + + Official NeXus NXDL schema to which this file conforms + + + + + + + + + + + + + raw detector signal (usually counts) as colected + it can be a multi-dimensional dataset depending on + the detector type (faster axes) and + the scanning method (slower axes) + + + + + The 2-theta range of the difractogram + + + + + + + + + + + + + + + + link (suggested target:/NXentry/NXinstrument/NXdetector/polar_angle) + Link to ponglar ale in /NXentry/NXinstrument/NXdetector + + + + + + + + link (suggested target:/NXentry/NXinstrument/NXdetector/data) + Link to data in /Nxentry/Nxinstrument/Nxdetector + + + + + + + + + Description of a processing or analysis step, such as the + baseline extraction or azimuth integration. + Add additional fields as needed to describe value(s) of + any variable, parameter, or term related to + the NXprocess step. Be sure to include units attributes + for all numerical fields. + + + + diff --git a/contributed_definitions/NXxrd_pan.nxdl.xml b/contributed_definitions/NXxrd_pan.nxdl.xml new file mode 100644 index 0000000000..191cf8feb3 --- /dev/null +++ b/contributed_definitions/NXxrd_pan.nxdl.xml @@ -0,0 +1,302 @@ + + + + + + + NXxrd_pan is a specialisation of NXxrd with exptra properties + + + + + Official NeXus NXDL schema to which this file conforms. + + + + + + + + Method used to collect the data + default='X-Ray Diffraction (XRD)' + + + + + + + + + + + Type of the X-ray tube. + + + + + + + + + + + + + + Current of the X-ray tube. + + + + + Voltage of the X-ray tube. + + + + + + Wavelength of the K\u03b1 1 line. + + + + + + + + + + Wavelength of the K\u03b1 2 line. + + + + + + + + + + K\u03b1 2/K\u03b1 1 intensity ratio. + + + + + Wavelength of the K\u00df line. + + + + + + + + + + Wavelength of the X-ray source. Used to convert from 2-theta to Q. + + + + + + + Axis scanned. + + + + + Mode of scan. + + + + + Integration time per channel. + + + + + + + + Collect user inputs e.g. name or path of the input file. + + + + + Starting value of the diffraction angle. + + + + + Ending value of the diffraction angle. + + + + + Minimum step size in-between two diffraction angles. + + + + + + + Starting value of the incident angle. + + + + + Ending value of the incident angle. + + + + + Minimum step size in the between two incident angles. + + + + + + Name of the data file. + + + + + Type of measurement. + + + + + Beam attenuation factors over the path. + + + + + Goniometer position X. + + + + + Goniometer position Y. + + + + + Goniometer position Z + + + + + Total time of count. + + + + + + Desired plot would be two_theta vs intensity. + + + + Number of scattered electrons per unit time. + + + + + + + + Axis scale represeting the 2-theta range of the difractogram. + + + + + + + + The omega range of the difractogram. + + + + + + + + The phi range of the difractogram + + + + + + + + The chi range of the difractogram + + + + + + + + + Desired plot would be q_vector vs intensity. + + + + Axis scale representing wavevector for scatter energy. + + + + + Number of scattered electrons per unit time. + + + + + + Description on sample. + + + + Mode of sample. + + + + + Id of sample. + + + + + Usually in xrd sample are being analysed, but sample might be identified by + assumed name or given name. + + + + + + + + + + diff --git a/contributed_definitions/nyaml/NXaberration.yaml b/contributed_definitions/nyaml/NXaberration.yaml new file mode 100644 index 0000000000..9bbc1f462f --- /dev/null +++ b/contributed_definitions/nyaml/NXaberration.yaml @@ -0,0 +1,36 @@ +category: base +doc: | + Quantified aberration coefficient in an aberration_model. +type: group +NXaberration(NXobject): + magnitude(NX_NUMBER): + doc: | + Value of the aberration coefficient. + unit: NX_LENGTH + uncertainty(NX_NUMBER): + doc: | + Uncertainty of the value of the aberration coefficient + according to uncertainty_model. + unit: NX_LENGTH + uncertainty_model(NX_CHAR): + doc: | + How was the uncertainty quantified e.g. via the 95% confidence interval + and using which algorithm or statistical model. + delta_time(NX_NUMBER): + doc: | + Time elapsed since the last measurement. + unit: NX_TIME + angle(NX_NUMBER): + doc: | + For the CEOS definitions the C aberrations are radial-symmetric and have + no angle entry, while the A, B, D, S, or R aberrations are n-fold + symmetric and have an angle entry. + For the NION definitions the coordinate system differs to the one + used in CEOS and instead two aberration coefficients a and b are used. + unit: NX_ANGLE + name(NX_CHAR): + doc: | + Given name to this aberration. + alias(NX_CHAR): + doc: | + Alias also used to name and refer to this specific type of aberration. diff --git a/contributed_definitions/nyaml/NXaberration_model.yaml b/contributed_definitions/nyaml/NXaberration_model.yaml new file mode 100644 index 0000000000..534762555d --- /dev/null +++ b/contributed_definitions/nyaml/NXaberration_model.yaml @@ -0,0 +1,13 @@ +category: base +doc: | + Models for aberrations of electro-magnetic lenses in electron microscopy. + + See `S. J. Pennycock and P. D. Nellist `_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the Nion to the + CEOS definitions. +type: group +NXaberration_model(NXobject): + model: + enumeration: [ceos, nion] + (NXaberration): diff --git a/contributed_definitions/nyaml/NXaberration_model_ceos.yaml b/contributed_definitions/nyaml/NXaberration_model_ceos.yaml new file mode 100644 index 0000000000..14f9556140 --- /dev/null +++ b/contributed_definitions/nyaml/NXaberration_model_ceos.yaml @@ -0,0 +1,71 @@ +category: base +doc: | + CEOS definitions/model for aberrations of electro-magnetic lenses. + + See `S. J. Pennycock and P. D. Nellist `_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the NION to the + CEOS definitions. +type: group +NXaberration_model_ceos(NXaberration_model): + model: + enumeration: [ceos] + c_1(NXaberration): + a_1(NXaberration): + b_2(NXaberration): + a_2(NXaberration): + c_3(NXaberration): + s_3(NXaberration): + a_3(NXaberration): + + # based on feedback from Thilo Remmele the following aberrations could be measured + # (enhanced mode, tilt angle > 30 mrad) but are not corrected + b_4(NXaberration): + d_4(NXaberration): + a_4(NXaberration): + c_5(NXaberration): + s_5(NXaberration): + r_5(NXaberration): + a_6(NXaberration): + + # further comments from Thilo Remmele (Leibniz-Institut für Kristallzüchtung) + # ThermoFisher uses CEOS correctors but makes customizations to these in their microscopes + # Aberration naming schema: C_order_multiplicity (similar to NXem, but with + # another coordinate system and in addition with a confidence entry. + # Aberrations with multiplicity 0 have no angle entry (C1,C3,C5,.., CEOS notation) + # contrast transferfuntion: ctf = e^(-i*Xi(g)) in Fourier space + # aberration function: + # Xi(g) = 2*pi/lamda{ 1/2 * (lamda*g)^2 (C20 + C22 cos[2(phi-phi_22)] + # +1/3 * (lamda*g)^3 (C31 cos[(phi-phi_31) + C33 cos[3(phi-phi_33) + # +1/4 * (lamda*g)^4 (C40 + C42 cos[2(phi-phi_42)] + C44 cos[4(phi-phi_42)] + # +1/f * (lamda*g)^f Sum (Cfm cos[m(phi-phi_fm)] where m=[0,2,..f] for even f and m=[1,3,..,f] for odd f + + # Thilo Remmele also mentions that there is a mapping of aberration coefficient names: + # C_2_0 -> C1 Defocus + # C_2_2 -> A1 2-fold astigmatism + # C_3_3 -> A2 3-fold astigmatism + # C_3_1 -> B2 axial coma + # C_4_0 -> C3 spherical aberration + # C_4_4 -> A3 4-fold astigmatism + # C_4_2 -> S3 star aberration + # C_5_5 -> A4 5-fold astigmatism + + # C_5_1 -> B4 axial coma + # C_5_3 -> D4 three lobe aberration + # C_6_0 -> C5 spherical aberration + # C_6_2 -> S5 star aberration + # C_6_4 -> R5 rosette aberration + # C_6_6 -> A5 6-fold astigmatism + + # In a session with HRTEM images the corrector is commonly aligned. + # The final measurement with the estimated residual aberrations + # should be saved in a corrector.html file (an example is appended + # at the end of this file. Unfortunately the datetime is not included + # in that html output, nor is the used outer tilt angle and exposure time. + # The datetime may be estimated from the file datetime and the Delta t entry, + # but caution if that datetime is not preserved on file transfers! + # More than one detector entry could occure but is not common. + # A seperate corrector schema, so it can be easily exchanged to other correctors if necessary. + # It might be useful to collect all the corrector entries in one table, for example to analyse the performance of the corrector. + # The corrector entry of the nexus em definition lacks the confidence information and the + # parameter settings for the estimation oft the aberrations. diff --git a/contributed_definitions/nyaml/NXaberration_model_nion.yaml b/contributed_definitions/nyaml/NXaberration_model_nion.yaml new file mode 100644 index 0000000000..2d47ab703f --- /dev/null +++ b/contributed_definitions/nyaml/NXaberration_model_nion.yaml @@ -0,0 +1,37 @@ +category: base +doc: | + Nion definitions/model for aberrations of electro-magnetic lenses. + + See `S. J. Pennycock and P. D. Nellist `_ (page 44ff, and page 118ff) + for different definitions available and further details. Table 7-2 of Ibid. + publication (page 305ff) documents how to convert from the Nion to the + CEOS definitions. +type: group +NXaberration_model_nion(NXaberration_model): + model: + enumeration: [nion] + c_1_0(NXaberration): + c_1_2_a(NXaberration): + c_1_2_b(NXaberration): + c_2_1_a(NXaberration): + c_2_1_b(NXaberration): + c_2_3_a(NXaberration): + c_2_3_b(NXaberration): + c_3_0(NXaberration): + c_3_2_a(NXaberration): + c_3_2_b(NXaberration): + c_3_4_a(NXaberration): + c_3_4_b(NXaberration): + c_4_1_a(NXaberration): + c_4_1_b(NXaberration): + c_4_3_a(NXaberration): + c_4_3_b(NXaberration): + c_4_5_a(NXaberration): + c_4_5_b(NXaberration): + c_5_0(NXaberration): + c_5_2_a(NXaberration): + c_5_2_b(NXaberration): + c_5_4_a(NXaberration): + c_5_4_b(NXaberration): + c_5_6_a(NXaberration): + c_5_6_b(NXaberration): diff --git a/contributed_definitions/nyaml/NXactivity.yaml b/contributed_definitions/nyaml/NXactivity.yaml new file mode 100644 index 0000000000..0c440d9562 --- /dev/null +++ b/contributed_definitions/nyaml/NXactivity.yaml @@ -0,0 +1,84 @@ +category: base +doc: | + A planned or unplanned action that has a temporal extension and for some time depends on some entity. + + This class is planned be used in the future as the super class for all other activities if inheritance + in base classes is supported in NeXus. +type: group +NXactivity(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this activity started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this activity ended. + description: + doc: | + Short description of the activity. + notes(NXnote): + doc: | + This can be any data or other descriptor acquired during the activity + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 95b47c73f55c34a19e14162abf2d4cc56bcd3002210e9929947cdd588076202e +# +# +# +# +# +# A planned or unplanned action that has a temporal extension and for some time depends on some entity. +# +# This class is planned be used in the future as the super class for all other activities if inheritance +# in base classes is supported in NeXus. +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this activity started. +# +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this activity ended. +# +# +# +# +# Short description of the activity. +# +# +# +# +# This can be any data or other descriptor acquired during the activity +# (NXnote allows to add pictures, audio, movies). Alternatively, a +# reference to the location or a unique identifier or other metadata file. In the +# case these are not available, free-text description. +# +# +# diff --git a/contributed_definitions/nyaml/NXactuator.yaml b/contributed_definitions/nyaml/NXactuator.yaml new file mode 100644 index 0000000000..ccc15f7ec4 --- /dev/null +++ b/contributed_definitions/nyaml/NXactuator.yaml @@ -0,0 +1,184 @@ +category: base +doc: | + An actuator used to control an external condition. + + The condition itself is described in :ref:`NXenvironment`. +type: group +NXactuator(NXobject): + model: + doc: | + Actuator identification code/model number + name: + doc: | + Name of the actuator + short_name: + doc: | + Short name of actuator used e.g. on monitor display program + attached_to: + doc: | + Describe where the actuator is attached to. + This could be an instance of NXsample or a device on NXinstrument. + physical_quantity: + doc: | + Name for the physical quantity effected by the actuation + + Examples: + temperature | pH | magnetic_field | electric_field | current | conductivity | resistance | voltage | + pressure | flow | stress | strain | shear | surface_pressure + type: + doc: | + The type of hardware used for the actuation. + + Examples (suggestions, but not restrictions): + + :Temperature: laser | gas lamp | filament | resistive + :Pressure: anvil cell + :Voltage: potentiostat + OUTPUT(NX_FLOAT): + unit: NX_ANY + doc: | + Any output that the actuator produces. + For example, a heater can have the field heater_power(NX_FLOAT). + OUTPUT_log(NXlog): + doc: | + Time history of actuator outputs. + (NXpid): + doc: | + If the actuator is PID-controlled, the settings of the PID controller can be + stored here. + setpoint(NX_FLOAT): + unit: NX_ANY + doc: | + Nominal actuator setpoint. + Can be a scalar or a vector (of [n] actuations). + setpoint_log(NXlog): + doc: | + Time history of actuator setpoints. + depends_on(NX_CHAR): + doc: | + Refers to the last transformation specifying the position of the actuator + in the NXtransformations chain. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the actuator within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + (NXfabrication): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ace4abf5ad9c9c7c3c2127dd7f73de80b4200b40f9a820be62c19c8a0391deb5 +# +# +# +# +# +# An actuator used to control an external condition. +# +# The condition itself is described in :ref:`NXenvironment`. +# +# +# +# Actuator identification code/model number +# +# +# +# +# Name of the actuator +# +# +# +# +# Short name of actuator used e.g. on monitor display program +# +# +# +# +# Describe where the actuator is attached to. +# This could be an instance of NXsample or a device on NXinstrument. +# +# +# +# +# Name for the physical quantity effected by the actuation +# +# Examples: +# temperature | pH | magnetic_field | electric_field | current | conductivity | resistance | voltage | +# pressure | flow | stress | strain | shear | surface_pressure +# +# +# +# +# The type of hardware used for the actuation. +# +# Examples (suggestions, but not restrictions): +# +# :Temperature: laser | gas lamp | filament | resistive +# :Pressure: anvil cell +# :Voltage: potentiostat +# +# +# +# +# Any output that the actuator produces. +# For example, a heater can have the field heater_power(NX_FLOAT). +# +# +# +# +# Time history of actuator outputs. +# +# +# +# +# If the actuator is PID-controlled, the settings of the PID controller can be +# stored here. +# +# +# +# Nominal actuator setpoint. +# Can be a scalar or a vector (of [n] actuations). +# +# +# +# +# Time history of actuator setpoints. +# +# +# +# +# +# Refers to the last transformation specifying the position of the actuator +# in the NXtransformations chain. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the actuator within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXadc.yaml b/contributed_definitions/nyaml/NXadc.yaml new file mode 100644 index 0000000000..d86bd8d566 --- /dev/null +++ b/contributed_definitions/nyaml/NXadc.yaml @@ -0,0 +1,53 @@ +category: base +doc: | + Analog-to-digital converter component/integrated circuit. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXadc(NXobject): + value(NX_NUMBER): + unit: NX_UNITLESS + doc: | + TBD. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4804d0b6bf4c31429d0e602b482093871010cb40a4e62da03804396faa54d158 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Analog-to-digital converter component/integrated circuit. +# +# +# +# TBD. +# +# +# diff --git a/contributed_definitions/nyaml/NXamplifier.yaml b/contributed_definitions/nyaml/NXamplifier.yaml new file mode 100644 index 0000000000..2ec3b22a3b --- /dev/null +++ b/contributed_definitions/nyaml/NXamplifier.yaml @@ -0,0 +1,147 @@ +category: base +doc: | + Base classed definition for amplifier devices. +type: group +NXamplifier(NXobject): + hardware(NXfabrication): + doc: | + (IC, device) (NXmanufacturer?) + num_of_channels(NX_NUMBER): + doc: | + The number of preamplifier channels are assgined. + active_channels(NX_NUMBER): + doc: | + The number of preamplifier channels are ready tp to be used. (array for active + channels) + openloop_amplification(NX_NUMBER): + doc: | + The output signal does not go through a feedback loop to adjust the + amplification of the amplifier. (array for active channels) + + # amplification(NX_NUMBER): + # doc: !!! The ratio of the amplitude of the output signal to the amplitude of the input signal. (array for active channels) # From google. + signal_over_noise(NX_NUMBER): + doc: | + The ratio of the amplitue of the useful signal to the amplitude of the noise in + the output signal of the amplifier. S/N=V_signal/V_noise. (array for active + channels) + crosstalk_factor(NX_NUMBER): + doc: | + (if active >1) + crosstalk_compensation(NX_BOOLEAN): + doc: | + for reducing interferences between different signalling pathways + bandwidth(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + The spectrum of frequency it can amplify, from its lowest to highest frequency + limits. + low_pass(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) + hi_pass(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) + + # voltage_amplifier_factor(NX_NUMBER): + # doc: !!! Current Amplifier Factor typically refers to the gain of the probe current amplifier. (V/V) + # current_amplifier_capacitive_cross_talk_compensation(NX_CHAR): + # doc: !!! Reduces the effect of capacitive crosstalk in the circuit on experimental results. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 16ef5b7fc979cc0c049aa7a38d898c3a35b058f98046d7657a43e2cd3fac4c1f +# +# +# +# +# +# Base classed definition for amplifier devices. +# +# +# +# (IC, device) (NXmanufacturer?) +# +# +# +# +# The number of preamplifier channels are assgined. +# +# +# +# +# The number of preamplifier channels are ready tp to be used. (array for active +# channels) +# +# +# +# +# The output signal does not go through a feedback loop to adjust the +# amplification of the amplifier. (array for active channels) +# +# +# +# +# +# The ratio of the amplitue of the useful signal to the amplitude of the noise in +# the output signal of the amplifier. S/N=V_signal/V_noise. (array for active +# channels) +# +# +# +# +# (if active >1) +# +# +# +# +# for reducing interferences between different signalling pathways +# +# +# +# +# The spectrum of frequency it can amplify, from its lowest to highest frequency +# limits. +# +# +# +# +# Order and cut-off frequency of the low-pass filter applied on the demodulated +# signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) +# +# +# +# +# Order and cut-off frequency of the high-pass filter applied on the demodulation +# signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) +# +# +# +# diff --git a/contributed_definitions/nyaml/NXaperture_em.yaml b/contributed_definitions/nyaml/NXaperture_em.yaml new file mode 100644 index 0000000000..8cbb3fc14c --- /dev/null +++ b/contributed_definitions/nyaml/NXaperture_em.yaml @@ -0,0 +1,26 @@ +category: base +doc: | + Base class for an individual aperture for beams in electron microscopy. +type: group +NXaperture_em(NXcomponent_em): + value(NX_NUMBER): + doc: | + Relevant value from the control software. + + This is not always just the diameter of the aperture (not even in the case) + of a circular aperture. Usually, it is a value that is set in the control + software whereby a specific configuration of an aperture is selected by the + software. + + The control software of commercial microscope typically offers the user + access at a high abstraction level because of which many details about + the actual settings of the electrical components are typically unknown. + + However, if more details are known or should be documented one should + use the description field for this. + unit: NX_ANY + description(NX_CHAR): + doc: | + Ideally, a (globally) unique persistent identifier, link, or text to a + resource which gives further details. Alternatively a free-text field to + store details noteworthy for contextualization or more detail. diff --git a/contributed_definitions/nyaml/NXapm.yaml b/contributed_definitions/nyaml/NXapm.yaml new file mode 100644 index 0000000000..925aad4569 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm.yaml @@ -0,0 +1,3303 @@ +category: application +doc: | + Application definition for atom probe and field ion microscopy experiments. + + This application definition provides a place to document data and metadata to + an atom probe experiment. Primarily the measurement itself is documented. + However, as most atom probe experiments are controlled with commercial software + which does not allow to access the raw detector hits, this application definition + also includes two key groups of processing steps (reconstruction and ranging). + + During tomographic reconstruction measured data are processed into a point cloud + of reconstructed positions of certain ions. During ranging time-of-flight data + are identified as representing specific ions to annotate each ion with a label. + + Commercial software used in atom probe research is designed as an integrated + acquisition and instrument control software. For AMETEK/Cameca local electrode + atom probe (LEAP) instruments the least processed (rawest) numerical results + and metadata are stored in so-called STR, RRAW, RHIT, and HITS files, which + are proprietary and their file format specifications not publicly documented. + + Supplementary metadata are kept in a database (formerly known as the ISDb) + which is connected to the instrument control software and synced with the + experiment while ions are detected. In effect, RHIT and HITS files + store the (rawest) experiment data in a closed manner that is + practically useless for users unless they have access to the + commercial software. + + To arrive at a state that atom probe microscopy (APM) with LEAP instruments + delivers a dataset with which users can study reconstructed atomic + position and do e.g. composition analyses or other post-processing + analysis tasks, these raw data have to be processed. Therefore, it is + necessary that for an application definition to be useful, details about + the physical acquisition of the raw data and all its + processing steps have to be stored. + + With this a user can create derived quantities like ion hit positions + (on the detector) and calibrated time-of-flight data. These derived + quantities are also needed to obtain calibrated mass-to-charge-state + ratios, and finally the tomographic reconstruction of the ion positions. + + In most cases, an APM dataset is useful only if it gets post-processed + via so-called ranging. Ranging defines rules for mapping time-of-flight + and mass-to-charge-state ratio values on ion species. This is post-processing + even though in practice it is performed sometimes already (as preview) + already while data are still being collected. + + The ion types decode molecular identities which can very often be + mapped to elemental identities, and also be used to distinguish isotopes. + All these steps are in most cases performed using commercial software. + + Frequently, though, ranging and post-processing is also performed with + (open-source) research software. Therefore, there is strictly speaking + not a single program used throughout an atom probe analysis not even + for the early stage of data acquisition and processing stages to obtain + a useful reconstructed and ranged dataset. + + This application definition documents not only the measurement but also the + key post-processing steps which transform the proprietary data into a + tomographic reconstruction with ranging definitions. + + Future guidance by the technology partners like AMETEK/Cameca could improve + this description to cover a substantial larger number of eventually metadata + that so far are neither publicly documented nor accessible. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + Total number of ions collected. + n_dld_wires: | + Total number of independent wires in the delay-line detector. + n_support: | + Number of support points for e.g. modeling peaks. + n_ivec_max: | + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. + n_ranges: | + Number of mass-to-charge-state-ratio intervals of this ion type. + n_x: | + Number of bins in the x direction. + n_y: | + Number of bins in the y direction. + n_z: | + Number of bins in the z direction. + n_bins: | + Number of bins. + n_topology: | + Total number of integers in the supplementary XDMF topology array. + +# some consistence is not yet achieved with IFES_APT_TC APT HDF5 v1 format +# Language precision: Keywords such as “must” “required” “should”, etc are as per RFC-2119 [RFC2119]. https://tools.ietf.org/html/rfc2119 +# https://gitlab.com/apt_software_toolbox/apt-hdf5 an implementation for an +# IFES APT TC APT HDF5 v1 verifier +# NEW ISSUE: possible offspring application definitions: +# NXapm_opt/pl would be possible, as soon as NXluminescence by Carola Emminger and Florian Dobner is ready whereby +# then there would be two subentries one for an NXapm and one for NXphotoluminesence to capture the photonic atom probe of Rouen/GPM +# and finally if there were an NXapm_afm for atomic force microscopy the IMEC AFM/APT experiments could be stored with an NXapm_afm application definition +# with NXapm and NXafm being respective subentries of the appdef but as NXapm_afm is a step-by-step approach one would have to release the constraint +# that only a single measurement can be performed. +# NXasat which could just take two subentries NXem and NXapm +# NXasat should be a fuse of NXapm and NXem within an NXentry with NXsubentry, in this way we can combine the strength of both application definitions +# to describe also the upcoming technique of atomic scale analytical tomography https://doi.org/10.1017/9781316677292 +type: group +NXapm(NXobject): + (NXentry): + exists: ['min', '1', 'max', 'unbounded'] + \@version: + doc: | + An at least as strong as SHA256 hashvalue of the file + that specifies the application definition. + + # enumeration: [sha_256_hash] + definition: + doc: | + NeXus NXDL schema to which this file conforms. + enumeration: [NXapm] + experiment_identifier: + doc: | + Ideally, a (globally) unique persistent identifier + for referring to this experiment. + + The identifier is usually defined/issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments to e.g. proposals. + experiment_description: + exists: optional + doc: | + Free-text description about the experiment. + + Users are strongly advised to detail the sample history in the + respective field and fill rather as completely as possible the fields + of the application definition behind instead of filling in these + details into the experiment_description free-text description field. + + Users are encouraged to add in this field eventual DOIs to papers + which yield further details to the experiment. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the microscope session started. + If the application demands that time codes in this section of the + application definition should only be used for specifying when the + experiment was performed - and the exact duration is not relevant + - this start_time field should be used. + + Often though it is useful to specify a time interval with specifying + both start_time and end_time to allow for more detailed bookkeeping + and interpretation of the experiment. The user should be aware that + even with having both dates specified, it may not be possible + to infer how long the experiment took or for how long data + were collected. + + More detailed timing data over the course of the experiment have to be + collected to compute this event chain during the experiment. + + # These computations can take advantage of individual time stamps + # in NXevent_em instances to provide additional pieces of information. + end_time(NX_DATE_TIME): + exists: recommended + doc: | + ISO 8601 time code with local time zone offset to UTC included + when the microscope session ended. + + # NEW ISSUE: fields like duration need a clearer description as to how these + # quantities should be defined. Most atom probers do not care for this other + # than getting an approximate hour-accurate estimate of the time how long it + # took to evaporate the specimen. + # several programs and libraries are usually coupled together for LEAP instruments, + # if it is possible to have a different root version with a different ivas/apsuite + # version that having a single program and version field is not enough but multiple + # are required LAS root version camecaroot version analysis software + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + run_number: + exists: recommended + doc: | + Neither the specimen_name nor the experiment_identifier but the identifier + through which the experiment is referred to in the control software. + For LEAP instruments it is recommended to use the IVAS/APSuite + run_number. For other instruments, such as the one from Stuttgart or + Oxcart from Erlangen, or the instruments at GPM in Rouen, use the + identifier which is closest in meaning to the LEAP run number. + The field does not have to be required if the information is recoverable + in the dataset which for LEAP instruments is the case when RHIT or HITS + files are also stored alongside a data artifact instance which is + generated according to this NXapm application definition. + + As a destructive microscopy technique, a run can be performed only once. + It is possible, however, to interrupt a run and restart data acquisition + while still using the same specimen. In this case, each evaporation run + needs to be distinguished with different run numbers. + We follow this habit of most atom probe groups. + + This application definition does currently not allow storing the + entire set of such interrupted runs. Not because of a technical limitation + within NeXus but because we have not seen a covering use case based + on which we could have designed and implemented this case. + Atom probers are invited to contact the respective people in the + FAIRmat team to fix this. + experiment_documentation(NXnote): + exists: optional + doc: | + Binary container for a file or a compressed collection of files which + can be used to add further descriptions and details to the experiment. + The container can hold a compressed archive. + + Required for operation_mode apt_fim or other to give further details. + Users should not abuse this field to provide free-text information. + Instead, these pieces of information should be mapped to + respective groups and sections. + thumbnail(NXnote): + exists: optional + doc: | + A small image that is representative of the entry; this can be an + image taken from the dataset like a thumbnail of a spectrum. + A 640 x 480 pixel jpeg image is recommended. + Adding a scale bar to that image is recommended but not required + as the main purpose of the thumbnail is to provide e.g. thumbnail + images for displaying them in data repositories. + \@type: + operation_mode: + doc: | + What type of atom probe microscopy experiment is performed. + This field is primarily meant to inform materials database systems + to qualitatively filter experiments: + + * apt are experiments where the analysis_chamber has no imaging gas. + experiment with LEAP instruments are typically performed as apt. + * fim are experiments where the analysis_chamber has an imaging gas, + which should be specified with the atmosphere in the analysis_chamber group. + * apt_fim should be used for combinations of the two imaging modes. + * other should be used in combination with the user specifying details in the + experiment_documentation field. + enumeration: [apt, fim, apt_fim, other] + + # description: + # exists: optional + # doc: | + (NXuser): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Contact information and eventually details person(s) involved in the + microscope session. This can be the principle investigator who performed + this experiment. Adding multiple users if relevant is recommended. + name: + doc: | + Given (first) name and surname of the user. + affiliation: + exists: recommended + doc: | + Name of the affiliation of the user at the point in time + when the experiment was performed. + address: + exists: recommended + doc: | + Postal address of the affiliation. + email: + exists: recommended + doc: | + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + orcid: + exists: recommended + doc: | + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific + service should also be written in orcid_platform + orcid_platform: + exists: recommended + doc: | + Name of the OrcID or ResearcherID where the account + under orcid is registered. + telephone_number: + exists: optional + doc: | + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + role: + exists: recommended + doc: | + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope. Student, postdoc, principle investigator, guest + are common examples. + social_media_name: + exists: optional + doc: | + Account name that is associated with the user + in social media platforms. + social_media_platform: + exists: optional + doc: | + Name of the social media platform where the account + under social_media_name is registered. + sample(NXsample): + exists: recommended + doc: | + Description of the sample from which the specimen was prepared or + site-specifically cut out using e.g. a focused-ion beam instrument. + + The sample group is currently a place for storing suggestions from + atom probers about other knowledge they have gained about the sample + from which they cut the specimen which is field-evaporated during the + experiment. Typically this is possible because the atom probe specimen + is usually not heat treated as is but one assumes that one has the sample + prepared as needed (i.e. with a specific grain diameter) and can thus + just cut out the specimen from that material. + + There are cases though where the specimen is processed further, i.e. the + specimen is machined further or exposed to external stimuli during the + experiment. In this case, these details should not be stored in the + sample group but atom probers should make suggestions how this application + definition can be improved to find a better place and compromise + how to improve this application definition. + + In the future also details like how the grain_diameter was characterized, + how the sample was prepared, how the material was heat-treated etc., + should be stored as using specific application definitions/schemas + which are then arranged and documented with a description of the workflow + so that actionable graphs become instantiatable. + grain_diameter(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Qualitative information about the grain size, here specifically + described as the equivalent spherical diameter of an assumed + average grain size for the crystal ensemble. + Users of this information should be aware that although the grain + diameter or radius is often referred to as grain size and used in + e.g. Hall-Petch-type materials models this is if at all an ensemble + average whose reporting may be very informative or not if the specimen + contains a few grains only. In atom probe the latter is often the case + because grains are measured partially as their diameter can be in the + order of magnitude of the physical diameter of the specimen. + + Reporting a grain size is useful though as it allows judging if + specific features are expected to be found in the detector hit map. + grain_diameter_error(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Magnitude of the standard deviation of the grain_diameter. + heat_treatment_temperature(NX_FLOAT): + exists: optional + unit: NX_TEMPERATURE + doc: | + The temperature of the last heat treatment step before quenching. + Knowledge about this value can give an idea how the sample + was heat treated, however if available a documentation of the + annealing treatment should be delivered by adding additional files + which are uploaded alongside an NXapm instance. + In the future there should better be an own schema used for the + heat treatment. + heat_treatment_temperature_error(NX_FLOAT): + exists: optional + unit: NX_TEMPERATURE + doc: | + Magnitude of the standard deviation of the heat_treatment_temperature. + heat_treatment_quenching_rate(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Rate of the last quenching step. + Knowledge about this value can give an idea how the specimen + was heat treated, however there are many situations where one + can imagine that the scalar value for just the quenching rate, + i.e. the first derivative of the measured time-temperature profile + is itself time-dependant. An example is when the specimen was + left in the furnace after the furnace was switched off. In this case + the specimen cools down with a specific rate of how this furnace + cools down in the lab. Processes which in practice are often not + documented with measuring the time-temperature profile. + + This can be problematic because when the furnace door was left open + or the ambient temperature in the lab changes, i.e. for a series of + experiments where one is conducted on a hot summer + day and the next during winter as might have an effect on the + evolution of the microstructure. There are many cases where this + has been reported to be an issue in industry, e.g. think about aging + aluminium samples left on the factory parking lot on a hot summer + day. + heat_treatment_quenching_rate_error(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Magnitude of the standard deviation of the heat_treatment_quenching_rate. + description: + exists: optional + (NXchemical_composition): + exists: recommended + doc: | + The chemical composition of the sample. Typically it is assumed that + this more macroscopic composition is representative for the material + so that the composition of the typically substantially less voluminous + specimen probes from the more voluminous sample. + normalization: + doc: | + Reporting compositions as atom and weight percent yields both + dimensionless quantities but their conceptual interpretation + differs. A normalization based on atom_percent counts relative to the + total number of atoms are of a particular type. By contrast, weight_percent + normalization factorizes in the respective mass of the elements. + Python libraries like pint are challenged by these differences as + at.-% and wt.-% both yield fractional quantities. + enumeration: [atom_percent, weight_percent] + ION(NXion): + exists: ['min', '1', 'max', '118'] + name: + doc: | + Human-readable name of the element/ion (e.g. Fe). + Name has to be a symbol of an element from the periodic table. + All symbols in the set of NXion instances inside the group + chemical_composition need to be disjoint. + composition(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Composition value for the element/ion referred to under name. + The value is normalized based on normalization, i.e. composition + is either an atom or weight percent quantity. + composition_error(NX_FLOAT): + exists: optional + unit: NX_DIMENSIONLESS + doc: | + Magnitude of the standard deviation of the composition (value). + specimen(NXsample): + + # NEW ISSUE: inject the conclusion from the discussion with Andrea + # according to SAMPLE.yaml 0f8df14 2022/06/15 + # NEW ISSUE: addition of a NXfurnace in which one can define the atmosphere + # and partial pressures of the agents in that atmosphere with which the + # sample was annealed at which temperature see the work happening at PNNL + # NEW ISSUE: it would be good to have an application definition NXicp for chemical composition + name: + doc: | + Descriptive name or ideally (globally) unique persistent identifier. + The name distinguishes the specimen from all others and especially the + predecessor/origin (see the sample group) from where this specimen was cut. + In cases where the specimen was e.g. site-specifically cut from the + sample referred to in the sample group or in cases of an instrument session + during which multiple specimens are loaded, the name has to be descriptive + enough to resolve which specimen on e.g. the microtip array was taken. + + The user is advised to store the details how a specimen was cut/prepared + from a specific sample in the sample_history. The sample_history field + must not be used for writing an alias of the specimen. Instead, + use the field alias for this. As an example there may be a specimen/sample + monitoring system in a lab with bar codes. The bar code is a good + specimen/sample name. A shorter and more human readable alias like + A0 can be an example for something to write in the alias field. + + In cases where multiple specimens have been loaded into the microscope + the name has to be the specific one, whose results are stored + by this NXentry, because a single NXentry is to be used for the + characterization of a single specimen in a single continuous run. + + Details about the specimen preparation should be stored in the + sample_history or if this is not possible in the sample group. + sample_history: + exists: recommended + doc: | + Ideally, a reference to the location of or a (globally) unique + persistent identifier of e.g. another file which should document + ideally as many details as possible of the material, its + microstructure, and its thermo-chemo-mechanical processing/ + preparation history. + + In the case that such a detailed history of the sample/specimen is not + available, use this field as a free-text description to specify a + sub-set of the entire sample history, i.e. what you would consider + as being the key steps and relevant information about the specimen, + its material, microstructure, thermo-chemo-mechanical processing + state and details of the preparation. + preparation_date(NX_DATE_TIME): + exists: recommended + doc: | + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. Usually this + should be a part of the sample history, i.e. the sample is imagined + handed over for the analysis. At the point it enters the microscope + the session starts. + + Knowing when the specimen was exposed to e.g. specific atmosphere is + especially required for environmentally sensitive material such as + hydrogen charged specimens or experiments including tracers with a + short half time. Further time stamps prior to preparation_date should + better be placed in resources which describe the sample_history. + alias: + exists: optional + doc: | + Short_name or abbreviation of the specimen name field. + atom_types: + doc: | + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + + The purpose of the field is to offer materials database systems an + opportunity to parse the relevant elements without having to interpret + these from the sample history or from other data sources. + description: + exists: optional + doc: | + Discouraged free-text field in case properly designed records + for the sample_history or sample section are not available. + is_polycrystalline(NX_BOOLEAN): + exists: recommended + doc: | + Report if the specimen is polycrystalline, in which case it + contains a grain or phase boundary, or if the specimen is a + single crystal. + + # NEW ISSUE: error model + # NEW ISSUE: use Andrea and MarkusK groups for + # describing the geometry of the sample + (NXdata): + exists: optional + doc: | + Hard link to a location in the hierarchy of the NeXus file + where the data for default plotting are stored. + (NXcoordinate_system_set): + exists: recommended + doc: | + Container to hold different coordinate systems conventions. + + For the specific idea and conventions to use with the + NXcoordinate_system_set inspect the description of the + NXcoordinate_system_set base class. Specific details for application + in atom probe microscopy follow. + + In this research field scientists distinguish usually several + Euclidean coordinate systems (CS): + + * World space; + a CS specifying a local coordinate system of the planet earth which + identifies into which direction gravity is pointing such that + the laboratory space CS can be rotated into this world CS. + * The laboratory space; + a CS specifying the room where the instrument is located in or + a physical landmark on the instrument, e.g. the direction of the + transfer rod where positive is the direction how the rod + has to be pushed during loading a specimen into the instrument. + In summary, this CS is defined by the chassis of the instrument. + * The specimen space; + a CS affixed to either the base or the initial apex of the specimen, + whose z axis points towards the detector. + * The detector space; + a CS affixed to the detector plane whose xy plane is usually in the + detector and whose z axis points towards the specimen. + This is a distorted space with respect to the reconstructed ion + positions. + * The reconstruction space; + a CS in which the reconstructed ion positions are defined. + The orientation depends on the analysis software used. + * Eventually further coordinate systems attached to the + flight path of individual ions might be defined. + + Coordinate systems should be right-handed ones. + Clockwise rotations should be considered positive rotations. + + In atom probe microscopy a frequently used choice for the detector + space (CS) is discussed with the so-called detector space image + (stack). This is a stack of two-dimensional histograms of detected ions + within a predefined evaporation ID interval. Typically, the set of + ion evaporation sequence IDs is grouped into chunks. + + For each chunk a histogram of the ion hit positions on the detector + is computed. This leaves the possibility for inconsistency between + the so-called detector space and the e.g. specimen space. + + The transformation here resolves this ambiguity by specifying how + the positive z-axes of either coordinate systems is oriented. + Consult the work of A. J. Breen and B. Gault and team + for further details. + + # Spatial transformations are always active transformations; i.e. the location and direction of a vector in one coordinate system is expressed by the following transformation matrix, T Ptransformed = TPoriginal + # add a note about what is the tip space + # Conventions: right-handed, Cartesian, 3D Euclidean CS should be used Laboratory space to be set by This is the space that is set by the chassis of the instrument. The Z direction must be reasonably parallel to gravity (+ve defined to be gravity vector pointing towards lowest ground), but can be defined to be a direction that is nominally parallel to gravity during an experiment. The origin must be placed within a bounding box of the chassis. Tip space instead of specimen space, The space occupied by a tip in the neutral position when ready for analysis. Z+ should be located in the direction of the needle (apex is Z+ from needle centreline). i) If the specimen moves relative to the laboratory frame, and the electrode does not, or if no electrode is present, then the space should be defined such that when the tip is moved physically, it also moves through tip space. ii) If the electrode moves relative to the laboratory frame, then the space should be defined such that, in tip space, the electrode position does not change. + # iii) The transformation between laboratory space and Tip space must be describable by a fixed 3x3 transformation matrix. Detector space: This is a 2D space only, and contains X+ and Y+ directions. X+ and Y+ should indicate primary directions on the detector, and should be, for an equivalent straight-flight-path configuration, such that X+ and Y+ is matched to that of tip space. Laser space missing: Laser space: The coordinate frame describing the impinging wavefront on the sample. Z+ is the vector of the propagating wavefront. X+ is the orthogonal component of the tip direction within the tip-laser plane. The origin shall be placed at the best estimate for tip apex position at the start of the experiment. Reconstruction space : The space occupied by a correctly reconstructed dataset. X+ and Y+ should correspond to X+ and Y+ in the detector space. Z+ should be such that the needle centre line is normal to the detector position. The origin shall be placed at the tip apex. + TRANSFORMATIONS(NXtransformations): + exists: ['min', '0', 'max', 'unbounded'] + + # NEW ISSUE: add Breen's Ultramicroscopy paper on atom probe crystallography + # in what follows each component of the instrument might be equipped with an NXmonitor + (NXmonitor): + exists: ['min', '0', 'max', 'unbounded'] + + # NEW ISSUE ADD AS MANY MONITORS AS NEEDED, also for pressure etc. + # add a default plot V = f(time/evaporation_id), essentially for each quantity + atom_probe(NXinstrument): + doc: | + Metadata and numerical data of the atom probe and the lab in which it + stands. + + An atom probe microscope (experiment) is different compared to a large- + scale facility or electron accelerator experiments in at least two ways: + + * First, ionized atoms and molecular ion(s fragments) + (in the case of atom probe tomography) + and (primarily) imaging gas ions (in the case of field ion + microscopy) are accelerated towards a position-sensitive + and time-of-flight taking detector system. + Hence, there is no real probe/beam. + * Second, the specimen is the lens of the microscope. + (NXcsg): + exists: optional + instrument_name: + doc: | + Given name of the atom probe at the hosting institution. This is an + alias. Examples could be LEAP5000, Raptor, Oxcart, one atom at a time, + etc. + location: + exists: optional + doc: | + Location of the lab or place where the instrument is installed. + Using GEOREF is preferred. + (NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + flight_path_length(NX_FLOAT): + unit: NX_LENGTH + doc: | + The space inside the atom probe along which ions pass nominally + when they leave the specimen and travel to the detector. + + THIS DOCSTRING NEEDS CLARIFICATION. + + # NEW ISSUE: discussion depends on the type of instrument, + # straight flight path, curved, there were a few comments to made + # https://fairmat-experimental.github.io/nexus-fairmat-proposal/ + # 50433d9039b3f33299bab338998acb5335cd8951/classes/ + # contributed_definitions/NXapm.html + # where further details of the flight geometry should be recorded however + # in the majority of cases these data are not offered by APSuite and + # so far nobody has asked or seriously proceeded with how to use these + # pieces of information if they were to be stored + # MK::NEW ISSUE + field_of_view(NX_FLOAT): + exists: recommended + unit: NX_LENGTH + doc: | + The nominal diameter of the specimen ROI which is measured in the + experiment. It is important to mention that the physical specimen + cannot be measured completely because ions may launch but not be + detected or hit elsewhere in the analysis_chamber. + (NXreflectron): + + # check if doc string gets carried over doc: Device for reducing flight time differences of ions in ToF experiments. + applied(NX_BOOLEAN): + doc: | + Is a reflectron installed and was it used? + name: + exists: optional + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + description: + exists: recommended + (NXcsg): + exists: optional + + # NEW ISSUE: flat_test_data(NXcollection): + # exists: recommended + # doc: NEED FOR FURTHER DISCUSSIONS WITH APM COLLEAGUES WHAT IS RELEVANT HERE. + # NEW ISSUE: have a place to be more specific about the geometry and + # usage of additional lenses: + # for the invizo 6000 instrument it makes sense to add at least groups for the two additional lenses whereby the field of view is brought from 50-60 to at most 100 the key invention + # add: decelerating_electrode(NXlens_em) accelerating_mesh maybe needs an own base class + # I suggest that this section should be reworked with the local_electrode being required and all other components and opposite counter_electrodes being optional WO2016171675A1 details the key specifications of the components and the setup + # see https://en.wikipedia.org/wiki/Einzel_lens for details double einzel lens in the invizo 6000 according to A. Breen (UNSW) + local_electrode(NXlens_em): + doc: | + A local electrode guiding the ion flight path. Also called + counter or extraction electrode. + name: + doc: | + Identifier of the local_electrode in an e.g. database. + (NXaperture_em): + exists: optional + name: + exists: recommended + (NXfabrication): + exists: optional + identifier: + exists: recommended + capabilities: + exists: optional + value(NX_NUMBER): + exists: recommended + (NXcsg): + exists: optional + + # but the local_electrode does not really on purpose create a magnetic field, + # specific for an electro-magnetic lens is the symmetry of its field + # NEW ISSUE: for now keep that we have what is an NXlens_em + # NEW ISSUE: APEX MONITOR / LEAP distance monitoring + # NEW ISSUE: the definition of flat test data should be included and documented + # NEW ISSUE: local electrode, baking strategies, storage + ion_detector(NXdetector): + doc: | + Detector for taking raw time-of-flight and + ion/hit impact positions data. + type: + doc: | + Description of the detector type. Specify if the detector is + not the usual type, i.e. not a delay-line detector. + In the case the detector is a multi-channel plate/ + delay line detector, use mcp_dld. In the case the detector is + a phosphor CCD use phosphor_ccd. In other case specify + the detector type via free-text. + + # enumeration: [mcp_dld, phosphor_ccd, other] + name: + exists: recommended + doc: | + Given name/alias. + + # NEW ISSUE: why not (NXfabrication) + model: + exists: recommended + doc: | + Given brand or model name by the manufacturer. + serial_number: + exists: recommended + doc: | + Given hardware name/serial number or hash identifier + issued by the manufacturer. + manufacturer_name: + exists: recommended + doc: | + Given name of the manufacturer. + signal_amplitude(NX_FLOAT): + exists: optional + unit: NX_CURRENT + doc: | + Amplitude of the signal detected on the multi-channel plate (MCP). + + This field should be used for storing the signal amplitude quantity + within ATO files. The ATO file format is used primarily by the + atom probe groups of the GPM in Rouen, France. + dimensions: + rank: 1 + dim: [[1, n_ions]] + (NXcsg): + exists: optional + pulser(NXpulser_apm): + + # NEW ISSUE: other sources of pulsers are possible + # NEW ISSUE: see in WO2016171675A1 Invizo 6000 patent from AMETEK + pulse_mode: + pulse_frequency(NX_FLOAT): + pulse_fraction(NX_FLOAT): + pulsed_voltage(NX_FLOAT): + exists: recommended + standing_voltage(NX_FLOAT): + exists: recommended + (NXcsg): + exists: optional + SOURCE(NXsource): + exists: ['min', '0', 'max', '2'] + + # INVIZO 6000 instrument have two symmetric lasers! so for these + # laser_gun and laser_beam exists: [min, 0, max, 2] + doc: | + Atom probe microscopes use controlled laser, voltage, or a + combination of pulsing strategies to trigger the excitation + and eventual field evaporation/emission of an ion during + an experiment. + If pulse_mode is set to laser or laser_and_voltage (e.g. for + LEAP6000-type instruments) having the group/section laser_gun + is required and the following of its fields have to be filled: + + * name + * wavelength + * energy + name: + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + wavelength(NX_FLOAT): + exists: recommended + power(NX_FLOAT): + exists: recommended + pulse_energy(NX_FLOAT): + exists: recommended + (NXbeam): + exists: ['min', '0', 'max', 'unbounded'] + pinhole_position(NXcollection): + exists: recommended + spot_position(NXcollection): + exists: recommended + stage_lab(NXstage_lab): + + # NEW ISSUE: consider more detailed opportunities for specifying holders like cryo-controller holder, type of holder, material for pucks make a difference for studies which hunt for hydrogen signal, equally dwell time in buffer and load lock chamber and environmental transfer, the application definition does not account for this at the moment, would need a class representing stage and specimen holder hierarchy of the entire sample loading and transfer system and the contributions or not these components make wrt to contamination. + base_temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + Average temperature at the specimen base, i.e. + base_temperature during the measurement. + temperature(NX_FLOAT): + exists: optional + unit: NX_TEMPERATURE + doc: | + The best estimate, at experiment time, for the temperature at the + sample base (furthest point along sample apex and holding assembly + that is removable from the sample stage). + dimensions: + rank: 1 + dim: [[1, n_ions]] + (NXcsg): + exists: optional + + # evaporation control in which context is it used? + # NEW ISSUE: begin add and support I/O of further details + # NEW ISSUE: with Shyam Katnagallu fix that so far the application definition does not really cover fim as there is no place to store values for a gas injection system and a (partial) pressure sensor for the imaging gas it should be clarified in the docstring of the pressure field if this measured either a chamber total of a species partial pressure + # NEW ISSUE: add NXapm_energy_analyzer, a voltage grid like done in Rouen/GPM + analysis_chamber(NXchamber): + name: + exists: optional + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + description: + exists: optional + pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Average pressure in the analysis chamber. + (NXcsg): + exists: optional + buffer_chamber(NXchamber): + exists: optional + name: + exists: optional + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + description: + exists: optional + pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Average pressure in the buffer chamber. + (NXcsg): + exists: optional + load_lock_chamber(NXchamber): + exists: optional + name: + exists: optional + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + description: + exists: optional + pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Average pressure in the load_lock_chamber. + (NXcsg): + exists: optional + getter_pump(NXpump): + exists: optional + design: + exists: recommended + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + (NXcsg): + exists: optional + roughening_pump(NXpump): + exists: optional + design: + exists: recommended + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + (NXcsg): + exists: optional + turbomolecular_pump(NXpump): + exists: optional + design: + exists: recommended + (NXfabrication): + exists: optional + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + capabilities: + exists: optional + (NXcsg): + exists: optional + + # NEW ISSUE: end add and support I/O of further details + instrument_calibration(NXcollection): + exists: recommended + doc: | + A possible place, which has to be discussed with the atom probe + community more though, where quantitative details about the calibration + of the counter electrode could be stored. Work in this direction was + e.g. reported by the `Erlangen group `_ + (see `P. Felfer et al. `_ ) + + # gridded-counter-electrode shadow image polyline fits are exported as + # NXcg_spline_set see also https://www.youtube.com/watch?v=99hNEkqdj78t=2348s + # NEW ISSUE: dld_signal_amplitude monitoring + # arrival_time_pairs: (recommended) NX_NUMBER (Rank: 3, Dimensions: [n_ions, n_dld_wires, 2]) {units=NX_TIME} + # eventually one may wish to store values from an NXmonitoring tracking the DLD signal amplitude (mV) = f(t) + specimen_monitoring(NXcollection): + exists: recommended + + # NEW ISSUE: should be promoted to recommended at some point in particular with closer integration of APM and EM instruments + doc: | + A place where details about the initial shape of the specimen + can be stored. Ideally, here also data about the shape evolution + of the specimen can be stored. There are currently very few + techniques which can measure the shape evolution: + + * Correlative electron microscopy coupled with modeling + but this usually takes an interrupted experiment + in which the specimen is transferred, an image taken, + and a new evaporation sequence initiated. + Examples are `I. Mouton et al. `_ + and `C. Fletcher `_. + * Another method, which is less accurate though, is to monitor + the specimen evolution via the in-built camera system + (if available) in the instrument. + * Another method is to use correlated scanning force microscopy + methods like reported in `C. Fleischmann `_. + * A continuous monitoring of the specimen in a + correlative electron microscopy/atom probe experiment + is planned to be developed by `T. Kelly et al. `_ + Nothing can be said about the outcome of this research yet but + here is where such spatiotemporally data could be stored. + + # NEW ISSUE: consider the above comments into new fields when important progress has been made. + initial_radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + Ideally measured or best elaborated guess of the + initial radius of the specimen. + shank_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Ideally measured or best elaborated guess of the shank angle. + This is a measure of the specimen taper. Define it in such a way + that the base of the specimen is modelled as a conical frustrum so + that the shank angle is the (shortest) angle between the specimen + space z-axis and a vector on the lateral surface of the cone. + detection_rate(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Average detection rate over the course of the experiment. + + # NEW ISSUE: define e.g. radius(NX_FLOAT) and evaporation_id(NX_UINT) to store snapshots of the shape evolution of the specimen. + estimated_field_at_the_apex(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Estimated field at the apex along the evaporation sequence. + dimensions: + rank: 1 + dim: [[1, n_ions]] + control_software(NXcollection): + doc: | + The majority of atom probe microscopes come from a + single commercial manufacturer `AMETEK (formerly Cameca) `_. + Their instruments are controlled via an(/a set) of integrated + instrument control system(s) (APSuite/IVAS/DAVis). + + By contrast, instruments which were built by individual + research groups such as of the French (GPM, Rouen, France), + the Schmitz (Inspico, Stuttgart, Germany), + the Felfer (Oxcart, Erlangen, Germany), + the Northwestern (D. Isheim, Seidman group et al.), + or the PNNL group (Pacific Northwest National Laborary, + Portland, Oregon, U.S.) have other solutions + to control the instrument. + + Some of which are modularized and open, + some of which realize also integrated control units with + portions of eventually undisclosed source code and + (so far) lacking (support of)/open APIs. + + Currently, there is no accepted/implemented + community-specific API for getting finely granularized + access to such control settings. + + These considerations motivated the design of the NXapm + application definition in that it stores quantities in NXcollection. + groups to begin with. Holding heterogeneous, not yet standardized + but relevant pieces of information is the purpose of this collection. + + # NEW ISSUE: With new development pull fields out of this collection into dedicated groups. + # might consider moving this to individual groups under (NXpump) or (NXchamber) groups. + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + buffer_chamber(NXcollection): + exists: optional + doc: | + Track time-dependent details over the course of the measurement about the + buffer_chamber. + load_lock_chamber(NXcollection): + exists: optional + doc: | + Track time-dependent details over the course of the measurement about the + load_lock_chamber. + analysis_chamber(NXcollection): + exists: optional + doc: | + Track time-dependent details over the course of the measurement about the + analysis_chamber. + + # NEW ISSUE: pressure in the buffer and load lock chambers + # NEW ISSUE: atmosphere and partial pressures + + # so although strictly speaking the following steps are computational + # post-processing of detector raw data to be specific they are listed + # under the atom_lab group because for experiment with commercial instrument + # these steps are currently not fully separatable as all processing in + # most cases the processing is done in commercial software. + status: + exists: recommended + doc: | + A statement whether the measurement was successful or failed prematurely. + enumeration: [success, failure, unknown] + + # NEW ISSUE: atomic volume, detection efficiency, electric field (assumptions), + # final specimen state, pre, post image analysis, a reference to three images + # taken as recommended by cameca, before or after, radius evolution model, field # factor, image compression + + # default statistics would be good to report as output e.g. + # total ions (single, multiple, partial) reconstructed ions (ranged, unranged) + # voltage and bowl calibration (peak) mass_calibration as an own field + + # NEW ISSUE: check also here the PYCCAPT pipeline from P. Felfer's group + ion_impact_positions(NXprocess): + exists: recommended + doc: | + Details about where ions hit the ion_detector and data processing + steps related to analog-to-digital conversion of detector signals + into ion hit positions. For AMETEK LEAP instruments this processing + takes place partly in the control unit of the detector partly + in the software. The process is controlled by the acquisition/ + instrument control software (IVAS/APSuite/DAVis). + The exact details are not documented by AMETEK in an open manner. + For instruments built by individual research groups, + like the Oxcart instrument, individual timing data from the + delay-line detector are openly accessible. + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + + # NEW ISSUE: discuss with Oxcart developers which + # modifications might be necessary here. + arrival_time_pairs(NX_NUMBER): + exists: recommended + unit: NX_TIME + doc: | + Raw readings from the analog-to-digital-converter + timing circuits of the detector wires. + dimensions: + rank: 3 + dim: [[1, n_ions], [2, n_dld_wires], [3, 2]] + hit_positions(NX_NUMBER): + unit: NX_LENGTH + doc: | + Evaluated ion impact coordinates at the detector + (either as computed from the arrival time data + or as reported by the control software). + If the acquisition software enables it one can also store in this + field the hit_positions, as measured by the detector, without any + corrections. + dimensions: + rank: 2 + dim: [[1, n_ions], [2, 2]] + + # NEW ISSUE: follow the example of base_temperature_time_profile to monitor the temporal evolution of the detection_rate over the course of the evaporation sequence + # detection_rate_time_profile(NX_FLOAT): + # doc: Spatio-temporal profile of the detection rate since the start of the measurement. + # NEW ISSUE: discuss how to handle cases when we would like to store ideally an array where one dimensions is NX_TIME and the other one is e.g. NX_PERCENT + hit_quality_filtering(NXprocess): + exists: optional + doc: | + This could be a place where currently the publicly undocumented + algorithmic steps are stored how detected hits are judged for their + quality. In CamecaRoot this there is something mentioned like + golden and partial hits, here is where this could be documented. + sequence_index(NX_POSINT): + exists: recommended + + # NEW ISSUE: use symbols to monitor number of pulses + hit_multiplicity(NXprocess): + exists: recommended + doc: | + Data post-processing step which is, like the impact position analyses, + usually executed in the integrated control software. This processing + yields how many ions were detected with each pulse. + + It is possible that multiple ions evaporate and hit the same or + different pixels of the detector on the same pulse. + These data form the basis to analyses of the so-called + (hit) multiplicity of an ion. + + Multiplicity must not be confused with how many atoms + f the same element or isotope, respectively, a molecular + ion contains (which is instead encoded with the + isotope_vector field of each NXion instance). + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + pulses_since_last_ion(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + Number of pulses since the last detected ion pulse. + For multi-hit records, after the first record, this is zero. + dimensions: + rank: 1 + dim: [[1, n_ions]] + + # NEW ISSUE: I feel the name is misleading, the quantity is + # named like this de facto only because thats the jargon + # term with epos files. + pulse_id(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Number of pulses since the start of the atom probe + run/evaporation sequence. + dimensions: + rank: 1 + dim: [[1, n_ions]] + hit_multiplicity(NX_UINT): + unit: NX_UNITLESS + + # NEW ISSUE: further discussions with members of the APM community + # is required to clarify this field and what it means + doc: | + Hit multiplicity. + dimensions: + rank: 1 + dim: [[1, n_ions]] + ion_filtering(NXprocess): + exists: recommended + doc: | + Like impact position and hit multiplicity computations, + ion filtering is a data post-processing step with which users + identify which of the detected ions should be included + in the voltage-and-bowl correction. + This post-processing is usually performed via GUI interaction + in the reconstruction pipeline of IVAS/APSuite. + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + evaporation_id_included(NX_BOOLEAN): + doc: | + Bitmask which is set to true if the ion + is considered and false otherwise. + dimensions: + rank: 1 + dim: [[1, n_ions]] + + # NEW ISSUE: add section for propagation_delay(NXprocess) ? + voltage_and_bowl_correction(NXprocess): + exists: recommended + doc: | + Data post-processing step to correct for ion impact + position flight path differences, detector biases, + and nonlinearities. This step is usually performed + with commercial software. + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + + # NEW ISSUE: realistic is that currently scientists can pull always a calibrated time-of-flight + # but not necessarily unprocessed timing data from the detector (unless individuals built the instrument). + # Relevant for ranging are the calibrated data, thats why only these + # (as an intermediate/compromise solution) are required in this version of the application definition + raw_tof(NX_FLOAT): + exists: recommended + unit: NX_TIME + doc: | + Raw time-of-flight data as read out from the acquisition software + if these data are available and accessible. + dimensions: + rank: 1 + dim: [[1, n_ions]] + calibrated_tof(NX_FLOAT): + unit: NX_TIME + + # NEW ISSUE: which type of calibrations are applied is usually a modified + # sqrt tof to m/q mapping the exact parameter of which are for LEAP instruments not immediately accessible. + doc: | + Calibrated time-of-flight. + dimensions: + rank: 1 + dim: [[1, n_ions]] + tof_calibration(NXcollection): + exists: recommended + doc: | + The key idea and algorithm of the voltage-and-bowl correction is + qualitatively similar for instruments of different manufacturers + or research groups. + + Specific differences exists though in the form of different + calibration models. For now we do not wish to resolve or + generalize these differences. Rather the purpose of this collection + is to provide a container where model-specific parameters + and calibration models can be stored if users know these + for sure. + + For AMETEK LEAP instruments this should be the place for + storing initial calibration values. These values are + accessible normally only by AMETEK service engineers. + They use these for calibrating the detector and instrument. + + Users can also use this NXcollection for storing the + iteratively identified calibrations which scientists + will see displayed in e.g. APSuite while they execute + the voltage-and-bowl correction as a part of the + reconstruction pipeline in APSuite. + + # NEW ISSUE: should be recommended as otherwise one cannot ensure that + # numerically the same voltage-and-bowl correction results are obtained + # (without knowning the parameters...) + mass_to_charge_conversion(NXprocess): + exists: recommended + doc: | + Data post-processing step in which calibrated time-of-flight data + (ToF) are interpreted into mass-to-charge-state ratios. + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + parameter(NXcollection): + exists: recommended + doc: | + Store vendor-specific calibration models here (if available). + mass_to_charge(NX_FLOAT): + unit: NX_ANY + doc: | + Mass-to-charge-state ratio values. + + # \@units: Da / a unitless quantity because it is the charge state and not the charge + dimensions: + rank: 1 + dim: [[1, n_ions]] + + # NEW ISSUE: make this rather an own subentry NXapm_reconstruction + reconstruction(NXprocess): + exists: recommended + doc: | + Data post-processing step to create a tomographic reconstruction + of the specimen based on selected calibrated ion hit positions, + the evaporation sequence, and voltage curve data. + Very often scientists use own software scripts according to + published procedures, so-called reconstruction protocols, + i.e. numerical recipes how to compute x, y, z atomic positions + from the input data. + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + protocol_name: + doc: | + Qualitative statement about which reconstruction protocol was used. + enumeration: [bas, geiser, gault, cameca, other] + parameter: + + # NEW ISSUE: the status here should be promoted to required but currently + # one needs to manually extract the reconstruction parameters + # NEW ISSUE: for instance from commercial software, here a better strategy + # is needed how to document the reconstruction parameter. + doc: | + Different reconstruction protocols exist. Although these approaches + are qualitatively similar, each protocol uses different parameters + (and interprets these differently). The source code to IVAS/APSuite + is not open. For now users should store reconstruction parameter + in a collection. + + # k(NX_FLOAT): + # doc: Field factor + # unit: ?? + # icf(NX_FLOAT): + # doc: Image compression factor. + # unit: ?? + # NEW ISSUE: for AMETEK, as well as for the Bas, Geiser, and + # Gault protocols we know the usual naming of the parameters + # they should be added as optional quantities. + # Therefore, it is difficult for now to generalize the meaning + # and idea behind all relevant reconstruction parameters. + # One could create a class for each reconstruction method, as + # these methods are de facto application definitions. + crystallographic_calibration: + doc: | + Different strategies for crystallographic calibration of the + reconstruction are possible. The field is required and details + should be specified in free-text at least. If the not crystallographic + calibration was performed the field should be filled with the n/a, + meaning not applied. + reconstructed_positions(NX_FLOAT): + unit: NX_LENGTH + doc: | + Three-dimensional reconstructed positions of the ions. + Interleaved array of x, y, z positions in the specimen space. + dimensions: + rank: 2 + dim: [[1, n_ions], [2, 3]] + visualization(NXprocess): + exists: recommended + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + An array of triplets of integers which can serve as a supplementary + array for Paraview to display the reconstructed dataset. + The XDMF primitive type is here 1, the number of primitives 1 per + triplet, the last integer in each triplet is the identifier of + each point starting from zero. + dimensions: + rank: 1 + dim: [[1, n_topology]] + + # n_topology == 3*n_ions + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + Six equally formatted sextets chained together. For each + sextett the first entry is an XDMF primitive topology + key (here 5 for polygon), the second entry the XDMF primitive + count value (here 4 because each face is a quad). + The remaining four values are the vertex indices. + dimensions: + rank: 1 + dim: [[1, 36]] + naive_point_cloud_density_map(NXprocess): + doc: | + To get a first overview of the reconstructed dataset, + the format conversion computes a simple 3d histogram + of the ion density using one nanometer cubic bins without + applying smoothening algorithms on this histogram. + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + (NXdata): + doc: | + A default three-dimensional histogram of the total + number of ions in each bin obtained via using a rectangular + transfer function. + \@signal: + \@axes: + \@AXISNAME_indices: + + # \@long_name: + title: + data_counts(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of counts for each bin. + dimensions: + rank: 3 + dim: [[1, n_z], [2, n_y], [3, n_x]] + axis_z(NX_FLOAT): + unit: NX_LENGTH + doc: | + Bin center of mass position along the z axis. + dimensions: + rank: 1 + dim: [[1, n_z]] + \@long_name: + axis_y(NX_FLOAT): + unit: NX_LENGTH + doc: | + Bin center of mass position along the y axis. + dimensions: + rank: 1 + dim: [[1, n_y]] + \@long_name: + axis_x(NX_FLOAT): + unit: NX_LENGTH + doc: | + Bin center of mass position along the x axis. + dimensions: + rank: 1 + dim: [[1, n_x]] + \@long_name: + + # NEW ISSUE: make this rather an own subentry NXapm_ranging + ranging(NXprocess): + exists: recommended + doc: | + Data post-processing step in which elemental, isotopic, + and/or molecular identities are assigned to the ions. + The documentation of these steps is based on ideas + described in the literature: + + * `M. K. Miller `_ + * `D. Haley et al. `_ + * `M. Kühbach et al. `_ + sequence_index(NX_POSINT): + exists: recommended + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + number_of_ion_types(NX_UINT): + unit: NX_UNITLESS + doc: | + How many ion types are distinguished. + If no ranging was performed each ion is of the special unknown type. + The iontype ID of this unknown type is 0 which is a reserve value. + Consequently, iontypes start counting from 1. + maximum_number_of_atoms_per_molecular_ion(NX_UINT): + unit: NX_UNITLESS + doc: | + Assumed maximum value that suffices to store all relevant + molecular ions, even the most complicated ones. + Currently a value of 32 is used. + mass_to_charge_distribution(NXprocess): + exists: recommended + doc: | + Specifies the computation of the mass-to-charge histogram. + Usually mass-to-charge values are studied as an ensemble quantity, + specifically these values are binned. + This (NXprocess) stores the settings of this binning. + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + range_minmax(NX_FLOAT): + unit: NX_ANY + doc: | + Smallest and largest mass-to-charge-state ratio value. + + # \@units: Da + # NEW ISSUE: NX_ATOMIC_MASS_UNIT use Tommasso scheme here Da + dimensions: + rank: 1 + dim: [[1, 2]] + range_increment(NX_FLOAT): + unit: NX_ANY + doc: | + Binning width of the mass-to-charge-state ratio values. + + # \@units: Da + # NEW ISSUE: unit must match with range, is Da + mass_spectrum(NXdata): + doc: | + A default histogram aka mass spectrum of + the mass-to-charge-state ratio values. + \@signal: + \@axes: + \@AXISNAME_indices: + + # \@long_name: + title: + data_counts(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of counts for each bin. + dimensions: + rank: 1 + dim: [[1, n_bins]] + \@long_name: + axis_mass_to_charge(NX_FLOAT): + unit: NX_ANY + doc: | + Right boundary of each mass-to-charge-state ratio value bin. + + # \@units: Da + dimensions: + rank: 1 + dim: [[1, n_bins]] + \@long_name: + background_quantification(NXprocess): + exists: recommended + doc: | + Details of the background model which was used to + correct the total counts per bin into counts. + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + + # NEW ISSUE: add parameters of the background model in an e.g. + # NXcollection as these are specific to every background model + # NEW ISSUE: touching upon i.e. research activities by Andrew London et al. + # substantiating the need for a clearer description how peak/signals were + # eventually processed via deconvolution methods + peak_search_and_deconvolution(NXprocess): + exists: recommended + doc: | + How where peaks in the background-corrected in the histogram + of mass-to-charge-state ratio values identified? + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + (NXpeak): + exists: ['min', '0', 'max', 'unbounded'] + label: + exists: recommended + peak_model: + doc: | + THIS DOCSTRING NEEDS CLARIFICATION. + peak_identification(NXprocess): + exists: recommended + doc: | + Details about how peaks, with taking into account + error models, were interpreted as ion types or not. + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + (NXion): + exists: ['min', '0', 'max', '256'] + isotope_vector(NX_UINT): + charge_state(NX_INT): + mass_to_charge_range(NX_FLOAT): + nuclid_list(NX_UINT): + exists: recommended + name: + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 612ced9157105a0063ebb6500dcdb1852b6094678e7f79eda066ae6b4a8a08ed +# +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Total number of ions collected. +# +# +# +# +# Total number of independent wires in the delay-line detector. +# +# +# +# +# Number of support points for e.g. modeling peaks. +# +# +# +# +# Maximum number of allowed atoms per (molecular) ion (fragment). +# Needs to match maximum_number_of_atoms_per_molecular_ion. +# +# +# +# +# Number of mass-to-charge-state-ratio intervals of this ion type. +# +# +# +# +# Number of bins in the x direction. +# +# +# +# +# Number of bins in the y direction. +# +# +# +# +# Number of bins in the z direction. +# +# +# +# +# Number of bins. +# +# +# +# +# Total number of integers in the supplementary XDMF topology array. +# +# +# +# +# Application definition for atom probe and field ion microscopy experiments. +# +# This application definition provides a place to document data and metadata to +# an atom probe experiment. Primarily the measurement itself is documented. +# However, as most atom probe experiments are controlled with commercial software +# which does not allow to access the raw detector hits, this application definition +# also includes two key groups of processing steps (reconstruction and ranging). +# +# During tomographic reconstruction measured data are processed into a point cloud +# of reconstructed positions of certain ions. During ranging time-of-flight data +# are identified as representing specific ions to annotate each ion with a label. +# +# Commercial software used in atom probe research is designed as an integrated +# acquisition and instrument control software. For AMETEK/Cameca local electrode +# atom probe (LEAP) instruments the least processed (rawest) numerical results +# and metadata are stored in so-called STR, RRAW, RHIT, and HITS files, which +# are proprietary and their file format specifications not publicly documented. +# +# Supplementary metadata are kept in a database (formerly known as the ISDb) +# which is connected to the instrument control software and synced with the +# experiment while ions are detected. In effect, RHIT and HITS files +# store the (rawest) experiment data in a closed manner that is +# practically useless for users unless they have access to the +# commercial software. +# +# To arrive at a state that atom probe microscopy (APM) with LEAP instruments +# delivers a dataset with which users can study reconstructed atomic +# position and do e.g. composition analyses or other post-processing +# analysis tasks, these raw data have to be processed. Therefore, it is +# necessary that for an application definition to be useful, details about +# the physical acquisition of the raw data and all its +# processing steps have to be stored. +# +# With this a user can create derived quantities like ion hit positions +# (on the detector) and calibrated time-of-flight data. These derived +# quantities are also needed to obtain calibrated mass-to-charge-state +# ratios, and finally the tomographic reconstruction of the ion positions. +# +# In most cases, an APM dataset is useful only if it gets post-processed +# via so-called ranging. Ranging defines rules for mapping time-of-flight +# and mass-to-charge-state ratio values on ion species. This is post-processing +# even though in practice it is performed sometimes already (as preview) +# already while data are still being collected. +# +# The ion types decode molecular identities which can very often be +# mapped to elemental identities, and also be used to distinguish isotopes. +# All these steps are in most cases performed using commercial software. +# +# Frequently, though, ranging and post-processing is also performed with +# (open-source) research software. Therefore, there is strictly speaking +# not a single program used throughout an atom probe analysis not even +# for the early stage of data acquisition and processing stages to obtain +# a useful reconstructed and ranged dataset. +# +# This application definition documents not only the measurement but also the +# key post-processing steps which transform the proprietary data into a +# tomographic reconstruction with ranging definitions. +# +# Future guidance by the technology partners like AMETEK/Cameca could improve +# this description to cover a substantial larger number of eventually metadata +# that so far are neither publicly documented nor accessible. +# +# +# +# +# An at least as strong as SHA256 hashvalue of the file +# that specifies the application definition. +# +# +# +# +# +# NeXus NXDL schema to which this file conforms. +# +# +# +# +# +# +# +# Ideally, a (globally) unique persistent identifier +# for referring to this experiment. +# +# The identifier is usually defined/issued by the facility, laboratory, +# or the principle investigator. The identifier enables to link +# experiments to e.g. proposals. +# +# +# +# +# Free-text description about the experiment. +# +# Users are strongly advised to detail the sample history in the +# respective field and fill rather as completely as possible the fields +# of the application definition behind instead of filling in these +# details into the experiment_description free-text description field. +# +# Users are encouraged to add in this field eventual DOIs to papers +# which yield further details to the experiment. +# +# +# +# +# ISO 8601 time code with local time zone offset to UTC information +# included when the microscope session started. +# If the application demands that time codes in this section of the +# application definition should only be used for specifying when the +# experiment was performed - and the exact duration is not relevant +# - this start_time field should be used. +# +# Often though it is useful to specify a time interval with specifying +# both start_time and end_time to allow for more detailed bookkeeping +# and interpretation of the experiment. The user should be aware that +# even with having both dates specified, it may not be possible +# to infer how long the experiment took or for how long data +# were collected. +# +# More detailed timing data over the course of the experiment have to be +# collected to compute this event chain during the experiment. +# +# +# +# +# +# ISO 8601 time code with local time zone offset to UTC included +# when the microscope session ended. +# +# +# +# +# +# +# +# +# +# +# Neither the specimen_name nor the experiment_identifier but the identifier +# through which the experiment is referred to in the control software. +# For LEAP instruments it is recommended to use the IVAS/APSuite +# run_number. For other instruments, such as the one from Stuttgart or +# Oxcart from Erlangen, or the instruments at GPM in Rouen, use the +# identifier which is closest in meaning to the LEAP run number. +# The field does not have to be required if the information is recoverable +# in the dataset which for LEAP instruments is the case when RHIT or HITS +# files are also stored alongside a data artifact instance which is +# generated according to this NXapm application definition. +# +# As a destructive microscopy technique, a run can be performed only once. +# It is possible, however, to interrupt a run and restart data acquisition +# while still using the same specimen. In this case, each evaporation run +# needs to be distinguished with different run numbers. +# We follow this habit of most atom probe groups. +# +# This application definition does currently not allow storing the +# entire set of such interrupted runs. Not because of a technical limitation +# within NeXus but because we have not seen a covering use case based +# on which we could have designed and implemented this case. +# Atom probers are invited to contact the respective people in the +# FAIRmat team to fix this. +# +# +# +# +# Binary container for a file or a compressed collection of files which +# can be used to add further descriptions and details to the experiment. +# The container can hold a compressed archive. +# +# Required for operation_mode apt_fim or other to give further details. +# Users should not abuse this field to provide free-text information. +# Instead, these pieces of information should be mapped to +# respective groups and sections. +# +# +# +# +# A small image that is representative of the entry; this can be an +# image taken from the dataset like a thumbnail of a spectrum. +# A 640 x 480 pixel jpeg image is recommended. +# Adding a scale bar to that image is recommended but not required +# as the main purpose of the thumbnail is to provide e.g. thumbnail +# images for displaying them in data repositories. +# +# +# +# +# +# What type of atom probe microscopy experiment is performed. +# This field is primarily meant to inform materials database systems +# to qualitatively filter experiments: +# +# * apt are experiments where the analysis_chamber has no imaging gas. +# experiment with LEAP instruments are typically performed as apt. +# * fim are experiments where the analysis_chamber has an imaging gas, +# which should be specified with the atmosphere in the analysis_chamber group. +# * apt_fim should be used for combinations of the two imaging modes. +# * other should be used in combination with the user specifying details in the +# experiment_documentation field. +# +# +# +# +# +# +# +# +# +# +# +# Contact information and eventually details person(s) involved in the +# microscope session. This can be the principle investigator who performed +# this experiment. Adding multiple users if relevant is recommended. +# +# +# +# Given (first) name and surname of the user. +# +# +# +# +# Name of the affiliation of the user at the point in time +# when the experiment was performed. +# +# +# +# +# Postal address of the affiliation. +# +# +# +# +# Email address of the user at the point in time when the experiment +# was performed. Writing the most permanently used email is recommended. +# +# +# +# +# Globally unique identifier of the user as offered by services +# like ORCID or ResearcherID. If this field is field the specific +# service should also be written in orcid_platform +# +# +# +# +# Name of the OrcID or ResearcherID where the account +# under orcid is registered. +# +# +# +# +# (Business) (tele)phone number of the user at the point +# in time when the experiment was performed. +# +# +# +# +# Which role does the user have in the place and at the point +# in time when the experiment was performed? Technician operating +# the microscope. Student, postdoc, principle investigator, guest +# are common examples. +# +# +# +# +# Account name that is associated with the user +# in social media platforms. +# +# +# +# +# Name of the social media platform where the account +# under social_media_name is registered. +# +# +# +# +# +# Description of the sample from which the specimen was prepared or +# site-specifically cut out using e.g. a focused-ion beam instrument. +# +# The sample group is currently a place for storing suggestions from +# atom probers about other knowledge they have gained about the sample +# from which they cut the specimen which is field-evaporated during the +# experiment. Typically this is possible because the atom probe specimen +# is usually not heat treated as is but one assumes that one has the sample +# prepared as needed (i.e. with a specific grain diameter) and can thus +# just cut out the specimen from that material. +# +# There are cases though where the specimen is processed further, i.e. the +# specimen is machined further or exposed to external stimuli during the +# experiment. In this case, these details should not be stored in the +# sample group but atom probers should make suggestions how this application +# definition can be improved to find a better place and compromise +# how to improve this application definition. +# +# In the future also details like how the grain_diameter was characterized, +# how the sample was prepared, how the material was heat-treated etc., +# should be stored as using specific application definitions/schemas +# which are then arranged and documented with a description of the workflow +# so that actionable graphs become instantiatable. +# +# +# +# Qualitative information about the grain size, here specifically +# described as the equivalent spherical diameter of an assumed +# average grain size for the crystal ensemble. +# Users of this information should be aware that although the grain +# diameter or radius is often referred to as grain size and used in +# e.g. Hall-Petch-type materials models this is if at all an ensemble +# average whose reporting may be very informative or not if the specimen +# contains a few grains only. In atom probe the latter is often the case +# because grains are measured partially as their diameter can be in the +# order of magnitude of the physical diameter of the specimen. +# +# Reporting a grain size is useful though as it allows judging if +# specific features are expected to be found in the detector hit map. +# +# +# +# +# Magnitude of the standard deviation of the grain_diameter. +# +# +# +# +# The temperature of the last heat treatment step before quenching. +# Knowledge about this value can give an idea how the sample +# was heat treated, however if available a documentation of the +# annealing treatment should be delivered by adding additional files +# which are uploaded alongside an NXapm instance. +# In the future there should better be an own schema used for the +# heat treatment. +# +# +# +# +# Magnitude of the standard deviation of the heat_treatment_temperature. +# +# +# +# +# Rate of the last quenching step. +# Knowledge about this value can give an idea how the specimen +# was heat treated, however there are many situations where one +# can imagine that the scalar value for just the quenching rate, +# i.e. the first derivative of the measured time-temperature profile +# is itself time-dependant. An example is when the specimen was +# left in the furnace after the furnace was switched off. In this case +# the specimen cools down with a specific rate of how this furnace +# cools down in the lab. Processes which in practice are often not +# documented with measuring the time-temperature profile. +# +# This can be problematic because when the furnace door was left open +# or the ambient temperature in the lab changes, i.e. for a series of +# experiments where one is conducted on a hot summer +# day and the next during winter as might have an effect on the +# evolution of the microstructure. There are many cases where this +# has been reported to be an issue in industry, e.g. think about aging +# aluminium samples left on the factory parking lot on a hot summer +# day. +# +# +# +# +# Magnitude of the standard deviation of the heat_treatment_quenching_rate. +# +# +# +# +# +# The chemical composition of the sample. Typically it is assumed that +# this more macroscopic composition is representative for the material +# so that the composition of the typically substantially less voluminous +# specimen probes from the more voluminous sample. +# +# +# +# Reporting compositions as atom and weight percent yields both +# dimensionless quantities but their conceptual interpretation +# differs. A normalization based on atom_percent counts relative to the +# total number of atoms are of a particular type. By contrast, weight_percent +# normalization factorizes in the respective mass of the elements. +# Python libraries like pint are challenged by these differences as +# at.-% and wt.-% both yield fractional quantities. +# +# +# +# +# +# +# +# +# +# Human-readable name of the element/ion (e.g. Fe). +# Name has to be a symbol of an element from the periodic table. +# All symbols in the set of NXion instances inside the group +# chemical_composition need to be disjoint. +# +# +# +# +# Composition value for the element/ion referred to under name. +# The value is normalized based on normalization, i.e. composition +# is either an atom or weight percent quantity. +# +# +# +# +# Magnitude of the standard deviation of the composition (value). +# +# +# +# +# +# +# +# +# +# Descriptive name or ideally (globally) unique persistent identifier. +# The name distinguishes the specimen from all others and especially the +# predecessor/origin (see the sample group) from where this specimen was cut. +# In cases where the specimen was e.g. site-specifically cut from the +# sample referred to in the sample group or in cases of an instrument session +# during which multiple specimens are loaded, the name has to be descriptive +# enough to resolve which specimen on e.g. the microtip array was taken. +# +# The user is advised to store the details how a specimen was cut/prepared +# from a specific sample in the sample_history. The sample_history field +# must not be used for writing an alias of the specimen. Instead, +# use the field alias for this. As an example there may be a specimen/sample +# monitoring system in a lab with bar codes. The bar code is a good +# specimen/sample name. A shorter and more human readable alias like +# A0 can be an example for something to write in the alias field. +# +# In cases where multiple specimens have been loaded into the microscope +# the name has to be the specific one, whose results are stored +# by this NXentry, because a single NXentry is to be used for the +# characterization of a single specimen in a single continuous run. +# +# Details about the specimen preparation should be stored in the +# sample_history or if this is not possible in the sample group. +# +# +# +# +# Ideally, a reference to the location of or a (globally) unique +# persistent identifier of e.g. another file which should document +# ideally as many details as possible of the material, its +# microstructure, and its thermo-chemo-mechanical processing/ +# preparation history. +# +# In the case that such a detailed history of the sample/specimen is not +# available, use this field as a free-text description to specify a +# sub-set of the entire sample history, i.e. what you would consider +# as being the key steps and relevant information about the specimen, +# its material, microstructure, thermo-chemo-mechanical processing +# state and details of the preparation. +# +# +# +# +# ISO 8601 time code with local time zone offset to UTC information +# when the specimen was prepared. +# +# Ideally, report the end of the preparation, i.e. the last known time +# the measured specimen surface was actively prepared. Usually this +# should be a part of the sample history, i.e. the sample is imagined +# handed over for the analysis. At the point it enters the microscope +# the session starts. +# +# Knowing when the specimen was exposed to e.g. specific atmosphere is +# especially required for environmentally sensitive material such as +# hydrogen charged specimens or experiments including tracers with a +# short half time. Further time stamps prior to preparation_date should +# better be placed in resources which describe the sample_history. +# +# +# +# +# Short_name or abbreviation of the specimen name field. +# +# +# +# +# List of comma-separated elements from the periodic table +# that are contained in the sample. +# If the sample substance has multiple components, all +# elements from each component must be included in `atom_types`. +# +# The purpose of the field is to offer materials database systems an +# opportunity to parse the relevant elements without having to interpret +# these from the sample history or from other data sources. +# +# +# +# +# Discouraged free-text field in case properly designed records +# for the sample_history or sample section are not available. +# +# +# +# +# Report if the specimen is polycrystalline, in which case it +# contains a grain or phase boundary, or if the specimen is a +# single crystal. +# +# +# +# +# +# +# Hard link to a location in the hierarchy of the NeXus file +# where the data for default plotting are stored. +# +# +# +# +# Container to hold different coordinate systems conventions. +# +# For the specific idea and conventions to use with the +# NXcoordinate_system_set inspect the description of the +# NXcoordinate_system_set base class. Specific details for application +# in atom probe microscopy follow. +# +# In this research field scientists distinguish usually several +# Euclidean coordinate systems (CS): +# +# * World space; +# a CS specifying a local coordinate system of the planet earth which +# identifies into which direction gravity is pointing such that +# the laboratory space CS can be rotated into this world CS. +# * The laboratory space; +# a CS specifying the room where the instrument is located in or +# a physical landmark on the instrument, e.g. the direction of the +# transfer rod where positive is the direction how the rod +# has to be pushed during loading a specimen into the instrument. +# In summary, this CS is defined by the chassis of the instrument. +# * The specimen space; +# a CS affixed to either the base or the initial apex of the specimen, +# whose z axis points towards the detector. +# * The detector space; +# a CS affixed to the detector plane whose xy plane is usually in the +# detector and whose z axis points towards the specimen. +# This is a distorted space with respect to the reconstructed ion +# positions. +# * The reconstruction space; +# a CS in which the reconstructed ion positions are defined. +# The orientation depends on the analysis software used. +# * Eventually further coordinate systems attached to the +# flight path of individual ions might be defined. +# +# Coordinate systems should be right-handed ones. +# Clockwise rotations should be considered positive rotations. +# +# In atom probe microscopy a frequently used choice for the detector +# space (CS) is discussed with the so-called detector space image +# (stack). This is a stack of two-dimensional histograms of detected ions +# within a predefined evaporation ID interval. Typically, the set of +# ion evaporation sequence IDs is grouped into chunks. +# +# For each chunk a histogram of the ion hit positions on the detector +# is computed. This leaves the possibility for inconsistency between +# the so-called detector space and the e.g. specimen space. +# +# The transformation here resolves this ambiguity by specifying how +# the positive z-axes of either coordinate systems is oriented. +# Consult the work of A. J. Breen and B. Gault and team +# for further details. +# +# +# +# +# +# +# +# +# +# Metadata and numerical data of the atom probe and the lab in which it +# stands. +# +# An atom probe microscope (experiment) is different compared to a large- +# scale facility or electron accelerator experiments in at least two ways: +# +# * First, ionized atoms and molecular ion(s fragments) +# (in the case of atom probe tomography) +# and (primarily) imaging gas ions (in the case of field ion +# microscopy) are accelerated towards a position-sensitive +# and time-of-flight taking detector system. +# Hence, there is no real probe/beam. +# * Second, the specimen is the lens of the microscope. +# +# +# +# +# Given name of the atom probe at the hosting institution. This is an +# alias. Examples could be LEAP5000, Raptor, Oxcart, one atom at a time, +# etc. +# +# +# +# +# Location of the lab or place where the instrument is installed. +# Using GEOREF is preferred. +# +# +# +# +# +# +# +# +# +# +# The space inside the atom probe along which ions pass nominally +# when they leave the specimen and travel to the detector. +# +# THIS DOCSTRING NEEDS CLARIFICATION. +# +# +# +# +# +# The nominal diameter of the specimen ROI which is measured in the +# experiment. It is important to mention that the physical specimen +# cannot be measured completely because ions may launch but not be +# detected or hit elsewhere in the analysis_chamber. +# +# +# +# +# +# +# Is a reflectron installed and was it used? +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A local electrode guiding the ion flight path. Also called +# counter or extraction electrode. +# +# +# +# Identifier of the local_electrode in an e.g. database. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Detector for taking raw time-of-flight and +# ion/hit impact positions data. +# +# +# +# Description of the detector type. Specify if the detector is +# not the usual type, i.e. not a delay-line detector. +# In the case the detector is a multi-channel plate/ +# delay line detector, use mcp_dld. In the case the detector is +# a phosphor CCD use phosphor_ccd. In other case specify +# the detector type via free-text. +# +# +# +# +# +# Given name/alias. +# +# +# +# +# +# Given brand or model name by the manufacturer. +# +# +# +# +# Given hardware name/serial number or hash identifier +# issued by the manufacturer. +# +# +# +# +# Given name of the manufacturer. +# +# +# +# +# Amplitude of the signal detected on the multi-channel plate (MCP). +# +# This field should be used for storing the signal amplitude quantity +# within ATO files. The ATO file format is used primarily by the +# atom probe groups of the GPM in Rouen, France. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Atom probe microscopes use controlled laser, voltage, or a +# combination of pulsing strategies to trigger the excitation +# and eventual field evaporation/emission of an ion during +# an experiment. +# If pulse_mode is set to laser or laser_and_voltage (e.g. for +# LEAP6000-type instruments) having the group/section laser_gun +# is required and the following of its fields have to be filled: +# +# * name +# * wavelength +# * energy +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Average temperature at the specimen base, i.e. +# base_temperature during the measurement. +# +# +# +# +# The best estimate, at experiment time, for the temperature at the +# sample base (furthest point along sample apex and holding assembly +# that is removable from the sample stage). +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Average pressure in the analysis chamber. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Average pressure in the buffer chamber. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Average pressure in the load_lock_chamber. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A possible place, which has to be discussed with the atom probe +# community more though, where quantitative details about the calibration +# of the counter electrode could be stored. Work in this direction was +# e.g. reported by the `Erlangen group <https://www.youtube.com/watch?v=99hNEkqdj78t=1876s>`_ +# (see `P. Felfer et al. <http://dx.doi.org/10.1016/j.ultramic.2016.07.008>`_ ) +# +# +# +# +# +# +# A place where details about the initial shape of the specimen +# can be stored. Ideally, here also data about the shape evolution +# of the specimen can be stored. There are currently very few +# techniques which can measure the shape evolution: +# +# * Correlative electron microscopy coupled with modeling +# but this usually takes an interrupted experiment +# in which the specimen is transferred, an image taken, +# and a new evaporation sequence initiated. +# Examples are `I. Mouton et al. <https://doi.org/10.1017/S1431927618016161>`_ +# and `C. Fletcher <https://doi.org/10.1088/1361-6463/abaaa6>`_. +# * Another method, which is less accurate though, is to monitor +# the specimen evolution via the in-built camera system +# (if available) in the instrument. +# * Another method is to use correlated scanning force microscopy +# methods like reported in `C. Fleischmann <https://doi.org/10.1016/j.ultramic.2018.08.010>`_. +# * A continuous monitoring of the specimen in a +# correlative electron microscopy/atom probe experiment +# is planned to be developed by `T. Kelly et al. <https://doi.org/10.1017/S1431927620022205>`_ +# Nothing can be said about the outcome of this research yet but +# here is where such spatiotemporally data could be stored. +# +# +# +# +# Ideally measured or best elaborated guess of the +# initial radius of the specimen. +# +# +# +# +# Ideally measured or best elaborated guess of the shank angle. +# This is a measure of the specimen taper. Define it in such a way +# that the base of the specimen is modelled as a conical frustrum so +# that the shank angle is the (shortest) angle between the specimen +# space z-axis and a vector on the lateral surface of the cone. +# +# +# +# +# Average detection rate over the course of the experiment. +# +# +# +# +# +# Estimated field at the apex along the evaporation sequence. +# +# +# +# +# +# +# +# +# The majority of atom probe microscopes come from a +# single commercial manufacturer `AMETEK (formerly Cameca) <https://www.atomprobe.com>`_. +# Their instruments are controlled via an(/a set) of integrated +# instrument control system(s) (APSuite/IVAS/DAVis). +# +# By contrast, instruments which were built by individual +# research groups such as of the French (GPM, Rouen, France), +# the Schmitz (Inspico, Stuttgart, Germany), +# the Felfer (Oxcart, Erlangen, Germany), +# the Northwestern (D. Isheim, Seidman group et al.), +# or the PNNL group (Pacific Northwest National Laborary, +# Portland, Oregon, U.S.) have other solutions +# to control the instrument. +# +# Some of which are modularized and open, +# some of which realize also integrated control units with +# portions of eventually undisclosed source code and +# (so far) lacking (support of)/open APIs. +# +# Currently, there is no accepted/implemented +# community-specific API for getting finely granularized +# access to such control settings. +# +# These considerations motivated the design of the NXapm +# application definition in that it stores quantities in NXcollection. +# groups to begin with. Holding heterogeneous, not yet standardized +# but relevant pieces of information is the purpose of this collection. +# +# +# +# +# +# +# +# +# +# Track time-dependent details over the course of the measurement about the +# buffer_chamber. +# +# +# +# +# Track time-dependent details over the course of the measurement about the +# load_lock_chamber. +# +# +# +# +# Track time-dependent details over the course of the measurement about the +# analysis_chamber. +# +# +# +# +# +# +# +# A statement whether the measurement was successful or failed prematurely. +# +# +# +# +# +# +# +# +# +# +# +# +# Details about where ions hit the ion_detector and data processing +# steps related to analog-to-digital conversion of detector signals +# into ion hit positions. For AMETEK LEAP instruments this processing +# takes place partly in the control unit of the detector partly +# in the software. The process is controlled by the acquisition/ +# instrument control software (IVAS/APSuite/DAVis). +# The exact details are not documented by AMETEK in an open manner. +# For instruments built by individual research groups, +# like the Oxcart instrument, individual timing data from the +# delay-line detector are openly accessible. +# +# +# +# +# +# +# +# +# +# +# Raw readings from the analog-to-digital-converter +# timing circuits of the detector wires. +# +# +# +# +# +# +# +# +# +# Evaluated ion impact coordinates at the detector +# (either as computed from the arrival time data +# or as reported by the control software). +# If the acquisition software enables it one can also store in this +# field the hit_positions, as measured by the detector, without any +# corrections. +# +# +# +# +# +# +# +# +# +# +# This could be a place where currently the publicly undocumented +# algorithmic steps are stored how detected hits are judged for their +# quality. In CamecaRoot this there is something mentioned like +# golden and partial hits, here is where this could be documented. +# +# +# +# +# +# +# Data post-processing step which is, like the impact position analyses, +# usually executed in the integrated control software. This processing +# yields how many ions were detected with each pulse. +# +# It is possible that multiple ions evaporate and hit the same or +# different pixels of the detector on the same pulse. +# These data form the basis to analyses of the so-called +# (hit) multiplicity of an ion. +# +# Multiplicity must not be confused with how many atoms +# f the same element or isotope, respectively, a molecular +# ion contains (which is instead encoded with the +# isotope_vector field of each NXion instance). +# +# +# +# +# +# +# +# +# +# Number of pulses since the last detected ion pulse. +# For multi-hit records, after the first record, this is zero. +# +# +# +# +# +# +# +# +# Number of pulses since the start of the atom probe +# run/evaporation sequence. +# +# +# +# +# +# +# +# +# Hit multiplicity. +# +# +# +# +# +# +# +# +# Like impact position and hit multiplicity computations, +# ion filtering is a data post-processing step with which users +# identify which of the detected ions should be included +# in the voltage-and-bowl correction. +# This post-processing is usually performed via GUI interaction +# in the reconstruction pipeline of IVAS/APSuite. +# +# +# +# +# +# +# +# +# +# Bitmask which is set to true if the ion +# is considered and false otherwise. +# +# +# +# +# +# +# +# +# +# Data post-processing step to correct for ion impact +# position flight path differences, detector biases, +# and nonlinearities. This step is usually performed +# with commercial software. +# +# +# +# +# +# +# +# +# +# +# Raw time-of-flight data as read out from the acquisition software +# if these data are available and accessible. +# +# +# +# +# +# +# +# +# Calibrated time-of-flight. +# +# +# +# +# +# +# +# The key idea and algorithm of the voltage-and-bowl correction is +# qualitatively similar for instruments of different manufacturers +# or research groups. +# +# Specific differences exists though in the form of different +# calibration models. For now we do not wish to resolve or +# generalize these differences. Rather the purpose of this collection +# is to provide a container where model-specific parameters +# and calibration models can be stored if users know these +# for sure. +# +# For AMETEK LEAP instruments this should be the place for +# storing initial calibration values. These values are +# accessible normally only by AMETEK service engineers. +# They use these for calibrating the detector and instrument. +# +# Users can also use this NXcollection for storing the +# iteratively identified calibrations which scientists +# will see displayed in e.g. APSuite while they execute +# the voltage-and-bowl correction as a part of the +# reconstruction pipeline in APSuite. +# +# +# +# +# +# +# Data post-processing step in which calibrated time-of-flight data +# (ToF) are interpreted into mass-to-charge-state ratios. +# +# +# +# +# +# +# +# +# +# Store vendor-specific calibration models here (if available). +# +# +# +# +# Mass-to-charge-state ratio values. +# +# +# +# +# +# +# +# +# +# +# Data post-processing step to create a tomographic reconstruction +# of the specimen based on selected calibrated ion hit positions, +# the evaporation sequence, and voltage curve data. +# Very often scientists use own software scripts according to +# published procedures, so-called reconstruction protocols, +# i.e. numerical recipes how to compute x, y, z atomic positions +# from the input data. +# +# +# +# +# +# +# +# +# +# Qualitative statement about which reconstruction protocol was used. +# +# +# +# +# +# +# +# +# +# +# +# +# Different reconstruction protocols exist. Although these approaches +# are qualitatively similar, each protocol uses different parameters +# (and interprets these differently). The source code to IVAS/APSuite +# is not open. For now users should store reconstruction parameter +# in a collection. +# +# +# +# +# +# Different strategies for crystallographic calibration of the +# reconstruction are possible. The field is required and details +# should be specified in free-text at least. If the not crystallographic +# calibration was performed the field should be filled with the n/a, +# meaning not applied. +# +# +# +# +# Three-dimensional reconstructed positions of the ions. +# Interleaved array of x, y, z positions in the specimen space. +# +# +# +# +# +# +# +# +# +# An array of triplets of integers which can serve as a supplementary +# array for Paraview to display the reconstructed dataset. +# The XDMF primitive type is here 1, the number of primitives 1 per +# triplet, the last integer in each triplet is the identifier of +# each point starting from zero. +# +# +# +# +# +# +# +# +# +# Six equally formatted sextets chained together. For each +# sextett the first entry is an XDMF primitive topology +# key (here 5 for polygon), the second entry the XDMF primitive +# count value (here 4 because each face is a quad). +# The remaining four values are the vertex indices. +# +# +# +# +# +# +# +# To get a first overview of the reconstructed dataset, +# the format conversion computes a simple 3d histogram +# of the ion density using one nanometer cubic bins without +# applying smoothening algorithms on this histogram. +# +# +# +# +# +# +# +# +# A default three-dimensional histogram of the total +# number of ions in each bin obtained via using a rectangular +# transfer function. +# +# +# +# +# +# +# +# +# Array of counts for each bin. +# +# +# +# +# +# +# +# +# +# Bin center of mass position along the z axis. +# +# +# +# +# +# +# +# +# Bin center of mass position along the y axis. +# +# +# +# +# +# +# +# +# Bin center of mass position along the x axis. +# +# +# +# +# +# +# +# +# +# +# +# +# Data post-processing step in which elemental, isotopic, +# and/or molecular identities are assigned to the ions. +# The documentation of these steps is based on ideas +# described in the literature: +# +# * `M. K. Miller <https://doi.org/10.1002/sia.1719>`_ +# * `D. Haley et al. <https://doi.org/10.1017/S1431927620024290>`_ +# * `M. Kühbach et al. <https://doi.org/10.1017/S1431927621012241>`_ +# +# +# +# +# +# +# +# +# +# How many ion types are distinguished. +# If no ranging was performed each ion is of the special unknown type. +# The iontype ID of this unknown type is 0 which is a reserve value. +# Consequently, iontypes start counting from 1. +# +# +# +# +# Assumed maximum value that suffices to store all relevant +# molecular ions, even the most complicated ones. +# Currently a value of 32 is used. +# +# +# +# +# Specifies the computation of the mass-to-charge histogram. +# Usually mass-to-charge values are studied as an ensemble quantity, +# specifically these values are binned. +# This (NXprocess) stores the settings of this binning. +# +# +# +# +# +# +# +# +# Smallest and largest mass-to-charge-state ratio value. +# +# +# +# +# +# +# +# +# Binning width of the mass-to-charge-state ratio values. +# +# +# +# +# +# A default histogram aka mass spectrum of +# the mass-to-charge-state ratio values. +# +# +# +# +# +# +# +# +# Array of counts for each bin. +# +# +# +# +# +# +# +# +# Right boundary of each mass-to-charge-state ratio value bin. +# +# +# +# +# +# +# +# +# +# +# +# Details of the background model which was used to +# correct the total counts per bin into counts. +# +# +# +# +# +# +# +# +# +# +# How where peaks in the background-corrected in the histogram +# of mass-to-charge-state ratio values identified? +# +# +# +# +# +# +# +# +# +# +# THIS DOCSTRING NEEDS CLARIFICATION. +# +# +# +# +# +# +# Details about how peaks, with taking into account +# error models, were interpreted as ion types or not. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_composition_space_results.yaml b/contributed_definitions/nyaml/NXapm_composition_space_results.yaml new file mode 100644 index 0000000000..30fae546b6 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_composition_space_results.yaml @@ -0,0 +1,903 @@ +category: application +doc: | + Results of a run with Alaukik Saxena's composition space tool. + + This is an initial draft application definition for the common NFDI-MatWerk, + FAIRmat infrastructure use case IUC09 how to improve the organization and + results storage of the composition space tool and make these data at the same + time directly understandable for NOMAD. + + This draft does no contain yet the annotations for how to also store + in the HDF5 file a default visualization whereby the composition grid + could directly be explored using H5Web. I am happy to add this ones the + data have been mapped on this schema, i.e. more discussion needed. + + Also iso-surfaces can be described, for paraprobe, this is a solved problem, + check the respective group in the NXapm_paraprobe_results_nanochem data + schema/application definition. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_voxel: | + Number of voxel of discretized domain for analyzed part of the dataset. + d: | + The dimensionality of the grid. + c: | + The cardinality or total number of cells/grid points. + n_clst_dict: | + Number of terms in the composition clustering dictionary + n_spat_dict: | + Number of terms in the position clustering dictionary +type: group +NXapm_composition_space_results(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_composition_space_results] + + # can be used for the name of the tool and version but also + # for if desired all the dependencies and libraries + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program: + \@version: + job_pyiron_identifier: + exists: recommended + doc: | + TBD, maybe how to link between pyiron state tracking and app state tracking + description: + exists: optional + doc: | + Disencouraged place for free-text for e.g. comments. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. when composition space tool was started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and composition space tool exited as a process. + config_filename: + doc: | + The path and name of the config file for this analysis. + TBD, this can be e.g. Alaukik's YAML file for composition space. + + # one could also wrap the entire triple of NXprocess (voxelization, gmm, real space) + # by a parent NXprocess whereby one could store the results of multiple analyses + # runs of the tool in the same individually documented way for as many parameter + # runs as desired... + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + dataset(NXapm_input_reconstruction): + filename: + doc: | + The path and name of the file (technology partner or community format) + from which reconstructed ion positions were loaded. + \@version: + iontypes(NXapm_input_ranging): + filename: + doc: | + The path and name of the file (technology partner or community format + from which ranging definitions, i.e. how to map mass-to- + charge-state ratios on iontypes were loaded. + \@version: + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the executable managed to process the analysis + or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + exists: optional + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Some suggestions follow, e.g. that field names should be prefixed + with the following controlled terms indicating which individual + coordinate system is described: + + * world + * composition_space + * lab + * specimen + * laser + * leap + * detector + * recon + voxelization(NXprocess): + sequence_index(NX_POSINT): + enumeration: [1] + + # specify the grid your using and for each ion in which cell i.e. voxel it is + # one could also have a more sophisticated data model where there is some + # fuzziness i.e. if an ML/AI model returns multiple values or a probability + # how likely an ion is in which voxel, for this + # inspect the example of the NXem_ebsd application definition + (NXcg_grid): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + enumeration: [1, 2, 3] + cardinality(NX_POSINT): + unit: NX_UNITLESS + + # default behaviour, if no coordinate system defined, unclear + # if one coordinate system is defined the origin is defined in this cs + origin(NX_NUMBER): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, d]] + symmetry: + enumeration: [cubic] + cell_dimensions(NX_NUMBER): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, d]] + extent(NX_POSINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, d]] + (NXtransformations): + exists: recommended + doc: | + Reference to or definition of a coordinate system with + which the positions and directions are interpretable. + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + + position(NX_NUMBER): + unit: NX_LENGTH + doc: | + Position of each cell in Euclidean space. + dimensions: + rank: 2 + dim: [[1, c], [2, d]] + coordinate(NX_INT): + exists: optional + unit: NX_DIMENSIONLESS + dimensions: + rank: 2 + dim: [[1, c], [2, d]] + + # bounding box if needed + voxel_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + For each ion, the identifier of the voxel in which the ion is located. + dimensions: + rank: 1 + dim: [[1, n_ions]] + (NXion): + exists: ['min', '0', 'max', 'unbounded'] + name: + composition(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, n_voxel]] + clustering_composition_space(NXprocess): + doc: | + In Alaukik's tool the GMM step. + sequence_index(NX_POSINT): + enumeration: [2] + cluster_dict_keyword: + doc: | + The keywords of the dictionary of distinguished compositionally- + defined cluster, e.g. the phases. Examples for keywords could be + phase1, phase2, and so one and so forth. + dimensions: + rank: 1 + dim: [[1, n_clst_dict]] + cluster_dict_value(NX_UINT): + unit: NX_UNITLESS + doc: | + Resolves for each keyword in cluster_dict which integer is used to + label something that it belongs or is assumed to represent this + cluster. + dimensions: + rank: 1 + dim: [[1, n_clst_dict]] + + # again for fuzzy or probabilistic multi solution approaches see NXem_ebsd + cluster_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + For example if the voxel grid is used to report that there + are voxels which are assumed to represent volume of either phase1 + or phase2, the cluster_dict_keyword would be a list with two names + phase1 and phase2, respectively. The cluster_dict_value would be a + list of e.g. integers 1 and 2. These could be used to build an + array with as many entries as there are voxel and store in this array + the respective value to encode which phase is assumed for each voxel. + dimensions: + rank: 1 + dim: [[1, n_voxel]] + + # use the fact that with e.g. XDMF one can on-the-fly reinterpret + # a 1d array to represent an explicit 3d grid + # default plots would be nice could directly be integrated in the results file + clustering_real_space(NXprocess): + doc: | + In Alaukik's tool the DBScan step after the GMM step. + sequence_index(NX_POSINT): + enumeration: [3] + cluster_dict_keyword: + doc: | + The keywords of the dictionary of distinguished spatially-contiguous + clusters. Examples for keywords could be precipitate1, precipitate2, + and so one and so forth. + dimensions: + rank: 1 + dim: [[1, n_spat_dict]] + cluster_dict_value(NX_UINT): + unit: NX_UNITLESS + doc: | + Resolves for each keyword in cluster_dict which integer is used to + label something that it belongs or is assumed to represent this + cluster. + dimensions: + rank: 1 + dim: [[1, n_spat_dict]] + + # again for fuzzy or probabilistic multi solution approaches see NXem_ebsd + cluster_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + For example if the voxel grid is used to report that there + are voxels which are assumed to represent volume of certain precipitates, + say we found ten precipitates and consider the rest as matrix. + We could make a list of say matrix, precipitate1, precipitate2, ..., + precipitate10. With cluster_dict_value then running from 0 to 10, + i.e. matrix is flagged special as 0 and the remaining particles + are indexed conveniently as 1, 2, ..., 10 like end users expect. + dimensions: + rank: 1 + dim: [[1, n_voxel]] + + # use the fact that with e.g. XDMF one can on-the-fly reinterpret + # a 1d array to represent an explicit 3d grid + # then the entire visualization just needs a smart XDMF file with + # one section with the coordinates of the voxel center of masses + # one section with the voxel identifier + # one section with the "phase" identifier referring to the clustering_composition_space NXprocess group + # one section with the "precipitate" identifier referring to the clustering_real_space NXprocess group + # technically one should get rid of the unnecessary chunks + # instead define an (nx, ny, nz) C-style array which whose data space + # is reserved by the h5py library upon first call and then (if desired) + # filled incrementally + # the array should be chunked not with an auto-chunking but with a nx, ny, >=1 chunking + # which will make visualization of nx, ny slices naturally fast, making the z-dimension + # chunking as fast as large as possible (needs compromise to remain within chunk cache size) + # will also make the orthogonal section a good compromise fast + # data should be gzip, level 1 compressed and all the redundant parts of the current + # output will collapse substantially + performance(NXcs_profiling): + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# fe3315d020167a5d984295fad8ed2070693508cd60801e40acaac2a61f21f1b4 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of voxel of discretized domain for analyzed part of the dataset. +# +# +# +# +# The dimensionality of the grid. +# +# +# +# +# The cardinality or total number of cells/grid points. +# +# +# +# +# Number of terms in the composition clustering dictionary +# +# +# +# +# Number of terms in the position clustering dictionary +# +# +# +# +# Results of a run with Alaukik Saxena's composition space tool. +# +# This is an initial draft application definition for the common NFDI-MatWerk, +# FAIRmat infrastructure use case IUC09 how to improve the organization and +# results storage of the composition space tool and make these data at the same +# time directly understandable for NOMAD. +# +# This draft does no contain yet the annotations for how to also store +# in the HDF5 file a default visualization whereby the composition grid +# could directly be explored using H5Web. I am happy to add this ones the +# data have been mapped on this schema, i.e. more discussion needed. +# +# Also iso-surfaces can be described, for paraprobe, this is a solved problem, +# check the respective group in the NXapm_paraprobe_results_nanochem data +# schema/application definition. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# +# +# +# +# +# TBD, maybe how to link between pyiron state tracking and app state tracking +# +# +# +# +# Disencouraged place for free-text for e.g. comments. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. when composition space tool was started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and composition space tool exited as a process. +# +# +# +# +# The path and name of the config file for this analysis. +# TBD, this can be e.g. Alaukik's YAML file for composition space. +# +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# +# The path and name of the file (technology partner or community format) +# from which reconstructed ion positions were loaded. +# +# +# +# +# +# +# +# The path and name of the file (technology partner or community format +# from which ranging definitions, i.e. how to map mass-to- +# charge-state ratios on iontypes were loaded. +# +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the executable managed to process the analysis +# or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Some suggestions follow, e.g. that field names should be prefixed +# with the following controlled terms indicating which individual +# coordinate system is described: +# +# * world +# * composition_space +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Reference to or definition of a coordinate system with +# which the positions and directions are interpretable. +# +# +# +# +# +# +# +# +# +# Position of each cell in Euclidean space. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# For each ion, the identifier of the voxel in which the ion is located. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# In Alaukik's tool the GMM step. +# +# +# +# +# +# +# +# +# The keywords of the dictionary of distinguished compositionally- +# defined cluster, e.g. the phases. Examples for keywords could be +# phase1, phase2, and so one and so forth. +# +# +# +# +# +# +# +# Resolves for each keyword in cluster_dict which integer is used to +# label something that it belongs or is assumed to represent this +# cluster. +# +# +# +# +# +# +# +# +# For example if the voxel grid is used to report that there +# are voxels which are assumed to represent volume of either phase1 +# or phase2, the cluster_dict_keyword would be a list with two names +# phase1 and phase2, respectively. The cluster_dict_value would be a +# list of e.g. integers 1 and 2. These could be used to build an +# array with as many entries as there are voxel and store in this array +# the respective value to encode which phase is assumed for each voxel. +# +# +# +# +# +# +# +# +# +# In Alaukik's tool the DBScan step after the GMM step. +# +# +# +# +# +# +# +# +# The keywords of the dictionary of distinguished spatially-contiguous +# clusters. Examples for keywords could be precipitate1, precipitate2, +# and so one and so forth. +# +# +# +# +# +# +# +# Resolves for each keyword in cluster_dict which integer is used to +# label something that it belongs or is assumed to represent this +# cluster. +# +# +# +# +# +# +# +# +# For example if the voxel grid is used to report that there +# are voxels which are assumed to represent volume of certain precipitates, +# say we found ten precipitates and consider the rest as matrix. +# We could make a list of say matrix, precipitate1, precipitate2, ..., +# precipitate10. With cluster_dict_value then running from 0 to 10, +# i.e. matrix is flagged special as 0 and the remaining particles +# are indexed conveniently as 1, 2, ..., 10 like end users expect. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_input_ranging.yaml b/contributed_definitions/nyaml/NXapm_input_ranging.yaml new file mode 100644 index 0000000000..8735f8baa8 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_input_ranging.yaml @@ -0,0 +1,101 @@ +category: base +doc: | + Metadata to ranging definitions made for a dataset in atom probe microscopy. + + Ranging is the process of labeling time-of-flight data with so-called iontypes + which ideally specify the most likely ion/molecular ion evaporated within a + given mass-to-charge-state-ratio value interval. + + The paraprobe-toolbox uses the convention that the so-called UNKNOWNTYPE + iontype (or unranged ions) represents the default iontype. + The ID of this special iontype is always reserved as 0. Each ion + is assigned to the UNKNOWNTYPE by default. Iontypes are assigned + by checking if the mass-to-charge-state-ratio values of an ion matches + to any of the defined mass-to-charge-state-ratio intervals. + +# symbols: +type: group +NXapm_input_ranging(NXobject): + filename: + doc: | + Path and name of the NeXus/HDF5 file which stores ranging definitions. + \@version: + doc: | + Version identifier of the file (representing an at least SHA256 strong) + hash. Such hashes serve reproducibility as they can be used for tracking + provenance metadata in a workflow. + group_name_iontypes: + doc: | + Name of the group (prefix to the individual ranging definitions) inside + the file referred to by filename which points to the specific ranging + definition to use. + An HDF5 file can store multiple ranging definitions. Using an ID is + the mechanism to distinguish which specific ranging (version) will + be processed. Reconstruction and ranging IDs can differ. + They specify different IDs. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 84be754a74580064b6e83b8cc1e513bdcad4ae264f96c9203c5341fc784b2a03 +# +# +# +# +# +# +# Metadata to ranging definitions made for a dataset in atom probe microscopy. +# +# Ranging is the process of labeling time-of-flight data with so-called iontypes +# which ideally specify the most likely ion/molecular ion evaporated within a +# given mass-to-charge-state-ratio value interval. +# +# The paraprobe-toolbox uses the convention that the so-called UNKNOWNTYPE +# iontype (or unranged ions) represents the default iontype. +# The ID of this special iontype is always reserved as 0. Each ion +# is assigned to the UNKNOWNTYPE by default. Iontypes are assigned +# by checking if the mass-to-charge-state-ratio values of an ion matches +# to any of the defined mass-to-charge-state-ratio intervals. +# +# +# +# Path and name of the NeXus/HDF5 file which stores ranging definitions. +# +# +# +# Version identifier of the file (representing an at least SHA256 strong) +# hash. Such hashes serve reproducibility as they can be used for tracking +# provenance metadata in a workflow. +# +# +# +# +# +# Name of the group (prefix to the individual ranging definitions) inside +# the file referred to by filename which points to the specific ranging +# definition to use. +# An HDF5 file can store multiple ranging definitions. Using an ID is +# the mechanism to distinguish which specific ranging (version) will +# be processed. Reconstruction and ranging IDs can differ. +# They specify different IDs. +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_input_reconstruction.yaml b/contributed_definitions/nyaml/NXapm_input_reconstruction.yaml new file mode 100644 index 0000000000..0d3fb996fe --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_input_reconstruction.yaml @@ -0,0 +1,89 @@ +category: base +doc: | + Metadata of a dataset (tomographic reconstruction) in atom probe microscopy. + +# symbols: +type: group +NXapm_input_reconstruction(NXobject): + filename: + doc: | + Name of the (NeXus)/HDF5 file which stores reconstructed ion position + and mass-to-charge-state ratios. Such an HDF5 file can store multiple + reconstructions. Using the information within the dataset_name fields + is the mechanism whereby paraprobe decides which reconstruction to + process. With this design it is possible that the same HDF5 + file can store multiple versions of a reconstruction. + \@version: + doc: | + Version identifier of the file (representing an at least SHA256 strong) + hash. Such hashes serve reproducibility as they can be used for tracking + provenance metadata in a workflow. + dataset_name_reconstruction: + doc: | + Name of the dataset inside the HDF5 file which refers to the + specific reconstructed ion positions to use for this analysis. + dataset_name_mass_to_charge: + doc: | + Name of the dataset inside the HDF5 file which refers to the + specific mass-to-charge-state-ratio values to use for this analysis. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5f409b194cbe10570c31933903ade8ac14d43cbc05493d52f0494615fe2071d7 +# +# +# +# +# +# +# Metadata of a dataset (tomographic reconstruction) in atom probe microscopy. +# +# +# +# Name of the (NeXus)/HDF5 file which stores reconstructed ion position +# and mass-to-charge-state ratios. Such an HDF5 file can store multiple +# reconstructions. Using the information within the dataset_name fields +# is the mechanism whereby paraprobe decides which reconstruction to +# process. With this design it is possible that the same HDF5 +# file can store multiple versions of a reconstruction. +# +# +# +# Version identifier of the file (representing an at least SHA256 strong) +# hash. Such hashes serve reproducibility as they can be used for tracking +# provenance metadata in a workflow. +# +# +# +# +# +# Name of the dataset inside the HDF5 file which refers to the +# specific reconstructed ion positions to use for this analysis. +# +# +# +# +# Name of the dataset inside the HDF5 file which refers to the +# specific mass-to-charge-state-ratio values to use for this analysis. +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_clusterer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_clusterer.yaml new file mode 100644 index 0000000000..063f13f3a0 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_clusterer.yaml @@ -0,0 +1,860 @@ +category: application +doc: | + Configuration of a paraprobe-clusterer tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + + # n_positions: Number of position values. + # n_disjoint_clusters: Number of disjoint cluster. + n_ivecmax: | + Maximum number of atoms per molecular ion. Should be 32 for paraprobe. + n_clust_algos: | + Number of clustering algorithms used. + n_ions: | + Number of different iontypes to distinguish during clustering. +type: group +NXapm_paraprobe_config_clusterer(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_clusterer] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many tasks to perform? + cameca_to_nexus(NXprocess): + exists: optional + doc: | + This process maps results from cluster analyses performed with IVAS/APSuite + into an interoperable representation. Specifically in this process + paraprobe-clusterer takes results from clustering methods from other tools + of the APM community, like IVAS/APSuite. These results are usually reported + in two ways. Either as an explicit list of reconstructed ion positions. + In the case of IVAS these positions are reported through a text file + with a cluster label for each position. + + Alternatively, the list of positions is reported, as it is the case for + AMETEK (IVAS/AP Suite) but the cluster labels are specified implicitly + only in the following way: The mass-to-charge-state ratio column of a + what is effectively a file formatted like POS is used to assign a hypothetical + mass-to-charge value which resolves a floating point representation + of the cluster ID. + + Another case can occur where all disjoint floating point values, + i.e. here cluster labels, are reported and then a dictionary is created + how each value matches to a cluster ID. + + In general the cluster ID zero is reserved for marking the dataset + as to not be assigned to any cluster. Therefore, indices of disjoint + clusters start at 1. + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + doc: | + AMETEK/Cameca results of cluster analyses, like with the maximum- + separation (MS) method clustering algorithm `J. Hyde et al. `_ + are stored as an improper POS file: This is a matrix of floating + point quadruplets, one for each ion and as many quadruplets as + ions were investigated. The first three values encode the position + of the ion. The fourth value is an improper mass-to-charge-state-ratio + value which encodes the integer identifier of the cluster as a floating + point number. + + # mapping_method: + # doc: | + # How should cluster labels be created from the cluster_labels information + # especially when these areNcluste floating point values. + # enumeration: [take_as_is, use_dictionary] + # mapping_dictionary_keyword(NX_NUMBER): + # doc: | + # The list of all keywords of a dictionary which maps implicit cluster + # indices like those from IVAS/APSuite which were0ass-to-charge-state ratios. + # unit: NX_UNITLESS + # dimensions: + # rank: 1 + # dim: [[1, n_disjoint_clusters]] + # mapping_dictionary_value(NX_UINT): + # doc: | + # The list of all values of a dictionary which maps implicit cluster + # indices like those from IVAS/APSuite which were0ass-to-charge-state ratios. + # The sequences of mapping_dictionary_keyword and mapping_dictionary_value + # have to match. + # unit: NX_UNITLESS + # dimensions: + # rank: 1 + # dim: [[1, n_disjoint_clusters]] + recover_evaporation_id(NX_BOOLEAN): + doc: | + Specifies if the tool should try to recover for each position the closest + matching position from dataset/dataset_name_reconstruction (within + floating point accuracy). This can be useful for instance when users + wish to recover the original evaporation ID, which IVAS/AP Suite drops + for instance when writing their *.indexed.* cluster results POS files. + + # recover_bitmask(NX_BOOLEAN): + # doc: | + # Specifies if the tool should try to recover, after a recovery of the + # evaporation IDs a bitmask which identifies which of the positions + # in dataset/dataset/dataset_name_reconstruction where covered + # by the IVAS/APSuite cluster analysis. This can be useful to recover + # the region of interest. + cluster_analysis(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + This process performs a cluster analysis on a reconstructed dataset + or a portion of the reconstruction. + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + ion_to_edge_distances(NXprocess): + exists: optional + doc: | + The tool enables to inject precomputed distance information for each + point/ion which can be used for further post-processing and analysis. + filename: + doc: | + Name of an HDF5 file which contains the ion distances. + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + dataset_name: + doc: | + Absolute HDF5 path to the dataset with distance values for each ion. + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + enumeration: [entire_dataset] + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + hit_multiplicity_filter(NXmatch_filter): + exists: optional + + # clustering_algorithm: + # doc: | + # Name of the clustering algorithm used. + # enumeration: [dbscan] # , optics, hpdbscan] + # dimensions: + # rank: 1 + # dim: [[1, n_clust_algos]] + ion_type_filter: + doc: | + How should iontypes be interpreted/considered during the cluster analysis. + Different options exist how iontypes are interpreted (if considered at all) + given an iontype represents in general a (molecular) ion with different isotopes + that have individually different multiplicity. + + The value resolve_all will set an ion active in the analysis + regardless of which iontype it is. + The value resolve_unknown will set an ion active when it is of the + UNKNOWNTYPE. + The value resolve_ion will set an ion active if it is of the + specific iontype, irregardless of its elemental or isotopic details. + The value resolve_element will set an ion active, and most importantly, + account as many times for it, as the (molecular) ion contains + atoms of elements in the whitelist ion_query_isotope_vector. + The value resolve_isotope will set an ion active, and most importantly, + account as many times for it, as the (molecular) ion contains isotopes + in the whitelist ion_query_isotope_vector. + + In effect, ion_query_isotope_vector acts as a whitelist to filter + which ions are considered as source ions of the correlation statistics + and how the multiplicity of each ion will be factorized. + + This is relevant as in atom probe we have the situation that a ion + of a molecular ion with more than one nuclid, say Ti O for example + is counted such that although there is a single TiO molecular ion + at a position that the cluster has two members. This multiplicity + affects the size of the feature and chemical composition. + + # enumeration: [resolve_all, resolve_unknown, resolve_ion, resolve_element, resolve_isotope] + enumeration: [resolve_element] + ion_query_isotope_vector(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of isotope vectors, as many as rows as different candidates + for iontypes should be distinguished as possible source iontypes. + In the simplest case, the matrix contains only the proton number + of the element in the row, all other values set to zero. + Combined with ion_query_type_source set to resolve_element this will + recover usual spatial correlation statistics like the 1NN C-C + spatial statistics. + dimensions: + rank: 2 + dim: [[1, n_ions], [2, n_ivecmax]] + dbscan(NXprocess): + doc: | + Settings for DBScan clustering algorithm. For original details about the + algorithms and (performance-relevant) details consider: + + * `M. Ester et al. `_ + * `M. Götz et al. `_ + + For details about how the DBScan algorithms is the key behind the + specific modification known as the maximum-separation method in the + atom probe community consider `E. Jägle et al. `_ + high_throughput_method: + doc: | + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + As an example we may define eps with ten entries and min_pts with + three entries. If high_throughput_method is tuple the analysis is + invalid as we have an insufficient number of min_pts for the ten + eps values. + By contrast, for combinatorics paraprobe-clusterer will run three + individual min_pts runs for each eps value, resulting in a total + of 30 analyses. + As an example the DBScan analysis reported in `M. Kühbach et al. `_ + would have defined an array of values np.linspace(0.2, 5.0, nums=241, endpoint=True) + eps values, min_pts one, and high_throughput_method set to combinatorics. + enumeration: [tuple, combinatorics] + eps(NX_FLOAT): + unit: NX_LENGTH + doc: | + Array of epsilon (eps) parameter values. + dimensions: + rank: 1 + dim: [[1, i]] + min_pts(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of minimum points (min_pts) parameter values. + dimensions: + rank: 1 + dim: [[1, j]] + + # THE IDEA BEHIND paraprobe-clusterer is that users can run a number of + # cluster analyses on their dataset on exactly the same point cloud and under + # the same conditions + optics(NXprocess): + doc: | + Settings for the OPTICS clustering algorithm. + + * `M. Ankerest et al. `_ + high_throughput_method: + doc: | + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + See the explanation for the corresponding parameter for dbscan + processes above-mentioned for further details. + enumeration: [tuple, combinatorics] + min_pts(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of minimum points (min_pts) parameter values. + dimensions: + rank: 1 + dim: [[1, i]] + max_eps(NX_FLOAT): + unit: NX_LENGTH + doc: | + Array of maximum epsilon (eps) parameter values. + dimensions: + rank: 1 + dim: [[1, j]] + hdbscan(NXprocess): + doc: | + Settings for the HPDBScan clustering algorithm. + + * L. McInnes et al. `_ + * scikit-learn hdbscan library ``_ + + See also this documentation for details about the parameter. + Here we use the terminology of the hdbscan documentation. + high_throughput_method: + doc: | + Strategy how runs are performed with different parameter: + + * For tuple as many runs are performed as parameter values. + * For combinatorics individual parameter arrays are looped over. + + See the explanation for the corresponding parameter for dbscan + processes above-mentioned for further details. + enumeration: [tuple, combinatorics] + min_cluster_size(NX_NUMBER): + unit: NX_ANY + doc: | + Array of min_cluster_size parameter values. + dimensions: + rank: 1 + dim: [[1, i]] + min_samples(NX_NUMBER): + unit: NX_ANY + doc: | + Array of min_samples parameter values. + dimensions: + rank: 1 + dim: [[1, j]] + cluster_selection_epsilon(NX_NUMBER): + unit: NX_ANY + doc: | + Array of cluster_selection parameter values. + dimensions: + rank: 1 + dim: [[1, k]] + alpha(NX_NUMBER): + unit: NX_ANY + doc: | + Array of alpha parameter values. + dimensions: + rank: 1 + dim: [[1, m]] + + # ADD FURTHER ALGORITHMS, see L. Stephenson for further details + # e.g. https://doi.org/10.1017/S1431927607070900 + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 619a54e03721a20d851c9a68159a0166deaa651651c085d15cfcc2593efdefb2 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# +# Maximum number of atoms per molecular ion. Should be 32 for paraprobe. +# +# +# +# +# Number of clustering algorithms used. +# +# +# +# +# Number of different iontypes to distinguish during clustering. +# +# +# +# +# Configuration of a paraprobe-clusterer tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# How many tasks to perform? +# +# +# +# +# This process maps results from cluster analyses performed with IVAS/APSuite +# into an interoperable representation. Specifically in this process +# paraprobe-clusterer takes results from clustering methods from other tools +# of the APM community, like IVAS/APSuite. These results are usually reported +# in two ways. Either as an explicit list of reconstructed ion positions. +# In the case of IVAS these positions are reported through a text file +# with a cluster label for each position. +# +# Alternatively, the list of positions is reported, as it is the case for +# AMETEK (IVAS/AP Suite) but the cluster labels are specified implicitly +# only in the following way: The mass-to-charge-state ratio column of a +# what is effectively a file formatted like POS is used to assign a hypothetical +# mass-to-charge value which resolves a floating point representation +# of the cluster ID. +# +# Another case can occur where all disjoint floating point values, +# i.e. here cluster labels, are reported and then a dictionary is created +# how each value matches to a cluster ID. +# +# In general the cluster ID zero is reserved for marking the dataset +# as to not be assigned to any cluster. Therefore, indices of disjoint +# clusters start at 1. +# +# +# +# +# +# +# +# +# AMETEK/Cameca results of cluster analyses, like with the maximum- +# separation (MS) method clustering algorithm `J. Hyde et al. <https://doi.org/10.1557/PROC-650-R6.6>`_ +# are stored as an improper POS file: This is a matrix of floating +# point quadruplets, one for each ion and as many quadruplets as +# ions were investigated. The first three values encode the position +# of the ion. The fourth value is an improper mass-to-charge-state-ratio +# value which encodes the integer identifier of the cluster as a floating +# point number. +# +# +# +# +# +# +# Specifies if the tool should try to recover for each position the closest +# matching position from dataset/dataset_name_reconstruction (within +# floating point accuracy). This can be useful for instance when users +# wish to recover the original evaporation ID, which IVAS/AP Suite drops +# for instance when writing their *.indexed.* cluster results POS files. +# +# +# +# +# +# +# This process performs a cluster analysis on a reconstructed dataset +# or a portion of the reconstruction. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The tool enables to inject precomputed distance information for each +# point/ion which can be used for further post-processing and analysis. +# +# +# +# Name of an HDF5 file which contains the ion distances. +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# Absolute HDF5 path to the dataset with distance values for each ion. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# How should iontypes be interpreted/considered during the cluster analysis. +# Different options exist how iontypes are interpreted (if considered at all) +# given an iontype represents in general a (molecular) ion with different isotopes +# that have individually different multiplicity. +# +# The value resolve_all will set an ion active in the analysis +# regardless of which iontype it is. +# The value resolve_unknown will set an ion active when it is of the +# UNKNOWNTYPE. +# The value resolve_ion will set an ion active if it is of the +# specific iontype, irregardless of its elemental or isotopic details. +# The value resolve_element will set an ion active, and most importantly, +# account as many times for it, as the (molecular) ion contains +# atoms of elements in the whitelist ion_query_isotope_vector. +# The value resolve_isotope will set an ion active, and most importantly, +# account as many times for it, as the (molecular) ion contains isotopes +# in the whitelist ion_query_isotope_vector. +# +# In effect, ion_query_isotope_vector acts as a whitelist to filter +# which ions are considered as source ions of the correlation statistics +# and how the multiplicity of each ion will be factorized. +# +# This is relevant as in atom probe we have the situation that a ion +# of a molecular ion with more than one nuclid, say Ti O for example +# is counted such that although there is a single TiO molecular ion +# at a position that the cluster has two members. This multiplicity +# affects the size of the feature and chemical composition. +# +# +# +# +# +# +# +# +# Matrix of isotope vectors, as many as rows as different candidates +# for iontypes should be distinguished as possible source iontypes. +# In the simplest case, the matrix contains only the proton number +# of the element in the row, all other values set to zero. +# Combined with ion_query_type_source set to resolve_element this will +# recover usual spatial correlation statistics like the 1NN C-C +# spatial statistics. +# +# +# +# +# +# +# +# +# Settings for DBScan clustering algorithm. For original details about the +# algorithms and (performance-relevant) details consider: +# +# * `M. Ester et al. <https://dx.doi.org/10.5555/3001460.3001507>`_ +# * `M. Götz et al. <https://dx.doi.org/10.1145/2834892.2834894>`_ +# +# For details about how the DBScan algorithms is the key behind the +# specific modification known as the maximum-separation method in the +# atom probe community consider `E. Jägle et al. <https://dx.doi.org/10.1017/S1431927614013294>`_ +# +# +# +# Strategy how runs are performed with different parameter: +# +# * For tuple as many runs are performed as parameter values. +# * For combinatorics individual parameter arrays are looped over. +# +# As an example we may define eps with ten entries and min_pts with +# three entries. If high_throughput_method is tuple the analysis is +# invalid as we have an insufficient number of min_pts for the ten +# eps values. +# By contrast, for combinatorics paraprobe-clusterer will run three +# individual min_pts runs for each eps value, resulting in a total +# of 30 analyses. +# As an example the DBScan analysis reported in `M. Kühbach et al. <https://dx.doi.org/10.1038/s41524-020-00486-1>`_ +# would have defined an array of values np.linspace(0.2, 5.0, nums=241, endpoint=True) +# eps values, min_pts one, and high_throughput_method set to combinatorics. +# +# +# +# +# +# +# +# +# Array of epsilon (eps) parameter values. +# +# +# +# +# +# +# +# Array of minimum points (min_pts) parameter values. +# +# +# +# +# +# +# +# +# +# Settings for the OPTICS clustering algorithm. +# +# * `M. Ankerest et al. <https://dx.doi.org/10.1145/304181.304187>`_ +# +# +# +# Strategy how runs are performed with different parameter: +# +# * For tuple as many runs are performed as parameter values. +# * For combinatorics individual parameter arrays are looped over. +# +# See the explanation for the corresponding parameter for dbscan +# processes above-mentioned for further details. +# +# +# +# +# +# +# +# +# Array of minimum points (min_pts) parameter values. +# +# +# +# +# +# +# +# Array of maximum epsilon (eps) parameter values. +# +# +# +# +# +# +# +# +# Settings for the HPDBScan clustering algorithm. +# +# * L. McInnes et al. <https://dx.doi.org/10.21105/joss.00205>`_ +# * scikit-learn hdbscan library `<https://hdbscan.readthedocs.io/en/latest/how_hdbscan_works.html>`_ +# +# See also this documentation for details about the parameter. +# Here we use the terminology of the hdbscan documentation. +# +# +# +# Strategy how runs are performed with different parameter: +# +# * For tuple as many runs are performed as parameter values. +# * For combinatorics individual parameter arrays are looped over. +# +# See the explanation for the corresponding parameter for dbscan +# processes above-mentioned for further details. +# +# +# +# +# +# +# +# +# Array of min_cluster_size parameter values. +# +# +# +# +# +# +# +# Array of min_samples parameter values. +# +# +# +# +# +# +# +# Array of cluster_selection parameter values. +# +# +# +# +# +# +# +# Array of alpha parameter values. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_distancer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_distancer.yaml new file mode 100644 index 0000000000..3c19b4f50f --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_distancer.yaml @@ -0,0 +1,453 @@ +category: application +doc: | + Configuration/settings of a paraprobe-distancer software tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXapm_paraprobe_config_distancer(NXobject): + (NXentry): + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_distancer] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many individual analyses should the tool execute. + (NXprocess): + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + hit_multiplicity_filter(NXmatch_filter): + exists: optional + point_to_triangle(NXprocess): + doc: | + Compute for all filtered points, e.g. ions of the point set + the shortest Euclidean distance to the closest triangle of the + set of triangles. The triangles can formed a closed surface mesh. + Distances are not simple distances based on normal projections but + giving an exact solution. + triangle_soup(NXprocess): + + # NEW ISSUE NXtriangle_soup + doc: | + Paraprobe-distancer enables the computation of the Euclidean shortest + distance for each member of a set of points against a set of triangles. + In contrast to comparable methods used in atom probe the here computed + distance is not simply the projected distance to one of the triangles + but the more costly but robust computation of the distance between + a point and a triangle. + + The triangles can represent for instance the facets of a triangulated + surface mesh of a model for the edge of the dataset. Such a model can + be computed with paraprobe-surfacer. Alternatively, the triangles can + be those from the set of all facets for a set of convex hulls, alpha-shapes, + or alpha wrappings about three-dimensional objects like precipitates + (computed with e.g. paraprobe-nanochem). + + Currently, the tool does not check if the respectively specified + triangle sets are consistent, what their topology is, or whether or + not they are consistently oriented. + Each dataset that is referred to in the list_of _dataset_names_vertices + should be an (Nvertices, 3) array of NX_FLOAT. Each dataset referred + to in the list_of_dataset_names_facet_indices should be an + (Nfacets, 3) array of NX_UINT. + Facet indices refer to vertex indices. These need to start at zero + and must not exceed Nvertices - 1, i.e. the identifier_offset is 0 + and vertices are indexed thus implicitly. + Facet normal vectors have to be also an array + of shape (Nfacets, 3) of NX_FLOAT. + number_of_files(NX_UINT): + unit: NX_UNITLESS + doc: | + How many triangle sets to consider. + (NXprocess): + doc: | + List of triangle sets. This design allows users to combine + multiple triangle sets. + filename: + doc: | + Name of the HDF5 file(s) which contain(s) vertex coordinates + and facet indices to describe the desired set of triangles. + \@version: + doc: | + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility. + dataset_name_vertices: + doc: | + Absolute HDF5 path to the dataset which + specifies the array of vertex positions. + dataset_name_facet_indices: + doc: | + Absolute HDF5 path to the dataset which + specifies the array of facet indices. + dataset_name_facet_normals: + exists: optional + doc: | + Absolute HDF5 path to the dataset which + specifies the array of facet normal vectors. + method: + doc: | + Specifies for which ions/points the tool will compute distances. + The purpose of this setting is to avoid unnecessary computations + when the user requests to only compute distances of ions within a + threshold distance to the triangle soup. + + By default the distances are computed for all ions; however + the setting skin enables to compute distances only for those + ions which are not farther away located to a triangle + than threshold_distance. + enumeration: [default, skin] + threshold_distance(NX_FLOAT): + unit: NX_LENGTH + + ##MK::only required when method is skin + doc: | + Maximum distance for which distances are computed when method is skin. + + # \@units: nm + + # point_set_to_polyline_set(NXprocess): + # doc: | + # Compute the shortest Euclidean distance of all filtered points/ions + # of a point set to the closest point on the closest polyline. + # polyhedra_set_to_triangle_set(NXprocess): + # doc: | + # Compute the (shortest Euclidean) distance of all polyhedra of a set + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0259801d31681cbca8200fa0fc8f653a013001487c419770f15d735970553d91 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Configuration/settings of a paraprobe-distancer software tool run. +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# How many individual analyses should the tool execute. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Compute for all filtered points, e.g. ions of the point set +# the shortest Euclidean distance to the closest triangle of the +# set of triangles. The triangles can formed a closed surface mesh. +# Distances are not simple distances based on normal projections but +# giving an exact solution. +# +# +# +# +# Paraprobe-distancer enables the computation of the Euclidean shortest +# distance for each member of a set of points against a set of triangles. +# In contrast to comparable methods used in atom probe the here computed +# distance is not simply the projected distance to one of the triangles +# but the more costly but robust computation of the distance between +# a point and a triangle. +# +# The triangles can represent for instance the facets of a triangulated +# surface mesh of a model for the edge of the dataset. Such a model can +# be computed with paraprobe-surfacer. Alternatively, the triangles can +# be those from the set of all facets for a set of convex hulls, alpha-shapes, +# or alpha wrappings about three-dimensional objects like precipitates +# (computed with e.g. paraprobe-nanochem). +# +# Currently, the tool does not check if the respectively specified +# triangle sets are consistent, what their topology is, or whether or +# not they are consistently oriented. +# Each dataset that is referred to in the list_of _dataset_names_vertices +# should be an (Nvertices, 3) array of NX_FLOAT. Each dataset referred +# to in the list_of_dataset_names_facet_indices should be an +# (Nfacets, 3) array of NX_UINT. +# Facet indices refer to vertex indices. These need to start at zero +# and must not exceed Nvertices - 1, i.e. the identifier_offset is 0 +# and vertices are indexed thus implicitly. +# Facet normal vectors have to be also an array +# of shape (Nfacets, 3) of NX_FLOAT. +# +# +# +# How many triangle sets to consider. +# +# +# +# +# List of triangle sets. This design allows users to combine +# multiple triangle sets. +# +# +# +# Name of the HDF5 file(s) which contain(s) vertex coordinates +# and facet indices to describe the desired set of triangles. +# +# +# +# Version identifier of the file such as a secure hash which +# documents the binary state of the file to add an additional +# layer of reproducibility. +# +# +# +# +# +# Absolute HDF5 path to the dataset which +# specifies the array of vertex positions. +# +# +# +# +# Absolute HDF5 path to the dataset which +# specifies the array of facet indices. +# +# +# +# +# Absolute HDF5 path to the dataset which +# specifies the array of facet normal vectors. +# +# +# +# +# +# +# Specifies for which ions/points the tool will compute distances. +# The purpose of this setting is to avoid unnecessary computations +# when the user requests to only compute distances of ions within a +# threshold distance to the triangle soup. +# +# By default the distances are computed for all ions; however +# the setting skin enables to compute distances only for those +# ions which are not farther away located to a triangle +# than threshold_distance. +# +# +# +# +# +# +# +# +# +# Maximum distance for which distances are computed when method is skin. +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_intersector.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_intersector.yaml new file mode 100644 index 0000000000..1455a60b9b --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_intersector.yaml @@ -0,0 +1,610 @@ +category: application +doc: | + Configuration of a paraprobe-intersector tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXapm_paraprobe_config_intersector(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_intersector] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to + UTC information included when this configuration file was created. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + For now a support field for the tool to identify how many individual + analyses the tool should execute as part of the analysis. + VOLUME_VOLUME_SPATIAL_CORRELATION(NXprocess): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + Tracking volume_volume_spatial_correlation is the process of building logical + relations between volumetric features based on meshes, their proximity and + eventual intersections. Volumetric overlap and proximity of volumetric + features is identified for members of sets of features to members of + other sets of volumetric features. + Specifically, for each time step k pairs of sets are compared: + Members of a so-called current_set to members of a so-called next_set. + Members can be different types of volumetric features. + In the analysis of M. Kuehbach et al. specifically features can be + so-called objects (closed non-degnerated polyhedra representing watertight + parts of an e.g. iso-surface) and/or proxies. Proxies are computed + doppelganger/replacement meshes for parts of an iso-surface which initially + were not resulting in watertight meshes because objects at the edge + of the dataset or incompletely measured or truncated objects. + intersection_detection_method: + doc: | + Specifies the method whereby to decide if two objects intersect volumetrically. + For reasons which are detailed in the supplementary material of + `M. Kühbach et al. `_, the tool by + default assumes that two objects intersect if they share at least one + ion with the same evaporation ID (shared_ion). + Alternatively, with specifying tetrahedra_intersections, + the tool can perform an intersection analysis which attempts to + tetrahedralize first each polyhedron. If successful, the tool then checks + for at least one pair of intersecting tetrahedra to identify if two objects + intersect or not. + + However, we found that these geometrical analyses can result in corner + cases which the currently used library (TetGen) was not unable to + tetrahedralize successfully. These cases were virtually always + associated with complicated non-convex polyhedra which had portions + of the mesh that were connected by almost point like tubes of triangles. + Finding more robust methods for computing intersections between + not necessarily convex polyhedra might improve the situation in the future. + enumeration: [shared_ion] + analyze_intersection(NX_BOOLEAN): + doc: | + Specifies if the tool evaluates if for each pair the two objects + (and proxies if used) intersect volumetrically. + analyze_proximity(NX_BOOLEAN): + doc: | + Specifies if the tool evaluates if for each pair the two objects + (and proxies if used) lie closer to one another than the + threshold_proximity. + analyze_coprecipitation(NX_BOOLEAN): + doc: | + Specifies if the tool evaluates, ones all tracking tasks were + successfully completed, how intersecting or proximity related + objects build sub-graphs. This is the feature which enabled + M. Kühbach et al. 2022 the high-throughput analyses of how many + objects are coprecipitates in the sense that they are single, + duplet, triplet, or high-order. For these analyses to work + has_object_volume needs to be activated. + threshold_proximity(NX_FLOAT): + unit: NX_LENGTH + doc: | + The maximum Euclidean distance between two objects below which + both objects are still considered within proximity. + + # \@units: nm + has_current_to_next_links(NX_BOOLEAN): + doc: | + Specifies if the tool stores the so-called forward relations between + nodes representing members of the current_set to nodes representing + members of the next_set. + has_next_to_current_links(NX_BOOLEAN): + doc: | + Specifies if the tool stores the so-called backward relations between + nodes representing members of the next_set to nodes representing + members of the current_set. + current_set(NXprocess): + doc: | + Current set stores a set of members, meshes of volumetric features, + which will be checked for proximity and/or volumetric intersection, + to members of the current_set. + The meshes were generated as a result of some other meshing process. + set_identifier(NX_UINT): + unit: NX_ANY + doc: | + This identifier can be used to label the current set. The label + effectively represents (can be interpreted as) the time/iteration + step when the current set was taken. As it is detailed in `M. Kühbach + et al. 2022 `_, this identifier + takes the role of the time variable :math:`k`. + + # number_of_objects(NX_UINT): + # doc: For now a support field to tell the tool how many objects to load. + # unit: NX_UNITLESS + number_of_feature_types(NX_UINT): + unit: NX_UNITLESS + doc: | + The total number of distinguished feature sets FEATURE. + It is assumed that the members within all these FEATURE sets + are representing a set together. As an example this set might represent + all volumetric_features. However, users might have formed + a subset of this set where individuals were regrouped. + For paraprobe-nanochem this is the case for objects and proxies. + Specifically, objects are distinguished further into those far + from and those close to the edge of the dataset. + Similarly, proxies are distinguished further into those far + from and those close to the edge of the dataset. + So while these four sub-sets contain different so-called types of + features key is that they were all generated for one set, here the + current_set. + FEATURE(NXcollection): + exists: ['min', '1', 'max', '4'] + feature_type: + doc: | + Descriptive category explaining what these features are. + enumeration: [objects_far_from_edge, objects_close_to_edge, proxies_far_from_edge, proxies_close_to_edge] + filename: + doc: | + Name of the (NeXus)/HDF5 file which contains triangulated + surface meshes of the members of the set as instances of + NXcg_polyhedron_set. + + # NEW ISSUE: make more robust checks wrt to the consistence of the datasets + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + groupname_geometry_prefix: + doc: | + String whereby the path to the geometry data can be interferred automatically. + Currently groupname_geometry_prefix/object/polyhedron. + feature_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of identifier whereby the path to the geometry data + can be interferred automatically. + dimensions: + rank: 1 + dim: [[1, i]] + next_set(NXcollection): + doc: | + Next set stores a set of members, meshes of volumetric features, + which will be checked for proximity and/or volumetric intersection, + to members of the next_set. + The meshes were generated as a result of some other meshing process. + set_identifier(NX_UINT): + unit: NX_ANY + doc: | + This identifier can be used to label the next_set. The label + effectively represents (can be interpreted as) the time/iteration + step when the current set was taken. As it is detailed in `M. Kühbach + et al. 2022 `_, this identifier + takes the role of the time variable :math:`k + 1`. + + # number_of_objects(NX_UINT): + # doc: For now a support field to tell the tool how many objects to load. + # unit: NX_UNITLESS + number_of_feature_types(NX_UINT): + unit: NX_UNITLESS + doc: | + The total number of distinguished feature sets FEATURE. + It is assumed that the members within all these FEATURE sets + are representing a set together. As an example this set might represent + all volumetric_features. However, users might have formed + a subset of this set where individuals were regrouped. + For paraprobe-nanochem this is the case for objects and proxies. + Specifically, objects are distinguished further into those far + from and those close to the edge of the dataset. + Similarly, proxies are distinguished further into those far + from and those close to the edge of the dataset. + So while these four sub-sets contain different so-called types of + features key is that they were all generated for one set, here the + next_set. + FEATURE(NXcollection): + exists: ['min', '1', 'max', '4'] + feature_type: + doc: | + Descriptive category explaining what these features are. + enumeration: [objects_far_from_edge, objects_close_to_edge, proxies_far_from_edge, proxies_close_to_edge] + filename: + doc: | + Name of the (NeXus)/HDF5 file which contains triangulated + surface meshes of the members of the set as instances of + NXcg_polyhedron_set. + + # NEW ISSUE: make more robust checks wrt to the consistence of the datasets + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + groupname_geometry_prefix: + doc: | + String whereby the path to the geometry data can be interferred automatically. + Currently groupname_geometry_prefix/object/polyhedron. + feature_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of identifier whereby the path to the geometry data + can be interferred automatically. + dimensions: + rank: 1 + dim: [[1, j]] + + ##MK::tetrahedra volume intersection and tessellation, and Nef polyhedra intersection + ##MK::are considered guru features and therefore currently supported via modifying the C/C++ source code + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 71b282f148e5f311dd9a3f3e1cc87d973706430edb00a844eb901dd5b8812aba +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Configuration of a paraprobe-intersector tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to +# UTC information included when this configuration file was created. +# +# +# +# +# For now a support field for the tool to identify how many individual +# analyses the tool should execute as part of the analysis. +# +# +# +# +# Tracking volume_volume_spatial_correlation is the process of building logical +# relations between volumetric features based on meshes, their proximity and +# eventual intersections. Volumetric overlap and proximity of volumetric +# features is identified for members of sets of features to members of +# other sets of volumetric features. +# Specifically, for each time step k pairs of sets are compared: +# Members of a so-called current_set to members of a so-called next_set. +# Members can be different types of volumetric features. +# In the analysis of M. Kuehbach et al. specifically features can be +# so-called objects (closed non-degnerated polyhedra representing watertight +# parts of an e.g. iso-surface) and/or proxies. Proxies are computed +# doppelganger/replacement meshes for parts of an iso-surface which initially +# were not resulting in watertight meshes because objects at the edge +# of the dataset or incompletely measured or truncated objects. +# +# +# +# Specifies the method whereby to decide if two objects intersect volumetrically. +# For reasons which are detailed in the supplementary material of +# `M. Kühbach et al. <https://arxiv.org/abs/2205.13510>`_, the tool by +# default assumes that two objects intersect if they share at least one +# ion with the same evaporation ID (shared_ion). +# Alternatively, with specifying tetrahedra_intersections, +# the tool can perform an intersection analysis which attempts to +# tetrahedralize first each polyhedron. If successful, the tool then checks +# for at least one pair of intersecting tetrahedra to identify if two objects +# intersect or not. +# +# However, we found that these geometrical analyses can result in corner +# cases which the currently used library (TetGen) was not unable to +# tetrahedralize successfully. These cases were virtually always +# associated with complicated non-convex polyhedra which had portions +# of the mesh that were connected by almost point like tubes of triangles. +# Finding more robust methods for computing intersections between +# not necessarily convex polyhedra might improve the situation in the future. +# +# +# +# +# +# +# +# Specifies if the tool evaluates if for each pair the two objects +# (and proxies if used) intersect volumetrically. +# +# +# +# +# Specifies if the tool evaluates if for each pair the two objects +# (and proxies if used) lie closer to one another than the +# threshold_proximity. +# +# +# +# +# Specifies if the tool evaluates, ones all tracking tasks were +# successfully completed, how intersecting or proximity related +# objects build sub-graphs. This is the feature which enabled +# M. Kühbach et al. 2022 the high-throughput analyses of how many +# objects are coprecipitates in the sense that they are single, +# duplet, triplet, or high-order. For these analyses to work +# has_object_volume needs to be activated. +# +# +# +# +# The maximum Euclidean distance between two objects below which +# both objects are still considered within proximity. +# +# +# +# +# +# Specifies if the tool stores the so-called forward relations between +# nodes representing members of the current_set to nodes representing +# members of the next_set. +# +# +# +# +# Specifies if the tool stores the so-called backward relations between +# nodes representing members of the next_set to nodes representing +# members of the current_set. +# +# +# +# +# Current set stores a set of members, meshes of volumetric features, +# which will be checked for proximity and/or volumetric intersection, +# to members of the current_set. +# The meshes were generated as a result of some other meshing process. +# +# +# +# This identifier can be used to label the current set. The label +# effectively represents (can be interpreted as) the time/iteration +# step when the current set was taken. As it is detailed in `M. Kühbach +# et al. 2022 <https://arxiv.org/abs/2205.13510>`_, this identifier +# takes the role of the time variable :math:`k`. +# +# +# +# +# +# The total number of distinguished feature sets FEATURE. +# It is assumed that the members within all these FEATURE sets +# are representing a set together. As an example this set might represent +# all volumetric_features. However, users might have formed +# a subset of this set where individuals were regrouped. +# For paraprobe-nanochem this is the case for objects and proxies. +# Specifically, objects are distinguished further into those far +# from and those close to the edge of the dataset. +# Similarly, proxies are distinguished further into those far +# from and those close to the edge of the dataset. +# So while these four sub-sets contain different so-called types of +# features key is that they were all generated for one set, here the +# current_set. +# +# +# +# +# +# Descriptive category explaining what these features are. +# +# +# +# +# +# +# +# +# +# +# Name of the (NeXus)/HDF5 file which contains triangulated +# surface meshes of the members of the set as instances of +# NXcg_polyhedron_set. +# +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# String whereby the path to the geometry data can be interferred automatically. +# Currently groupname_geometry_prefix/object<ID>/polyhedron. +# +# +# +# +# Array of identifier whereby the path to the geometry data +# can be interferred automatically. +# +# +# +# +# +# +# +# +# +# Next set stores a set of members, meshes of volumetric features, +# which will be checked for proximity and/or volumetric intersection, +# to members of the next_set. +# The meshes were generated as a result of some other meshing process. +# +# +# +# This identifier can be used to label the next_set. The label +# effectively represents (can be interpreted as) the time/iteration +# step when the current set was taken. As it is detailed in `M. Kühbach +# et al. 2022 <https://arxiv.org/abs/2205.13510>`_, this identifier +# takes the role of the time variable :math:`k + 1`. +# +# +# +# +# +# The total number of distinguished feature sets FEATURE. +# It is assumed that the members within all these FEATURE sets +# are representing a set together. As an example this set might represent +# all volumetric_features. However, users might have formed +# a subset of this set where individuals were regrouped. +# For paraprobe-nanochem this is the case for objects and proxies. +# Specifically, objects are distinguished further into those far +# from and those close to the edge of the dataset. +# Similarly, proxies are distinguished further into those far +# from and those close to the edge of the dataset. +# So while these four sub-sets contain different so-called types of +# features key is that they were all generated for one set, here the +# next_set. +# +# +# +# +# +# Descriptive category explaining what these features are. +# +# +# +# +# +# +# +# +# +# +# Name of the (NeXus)/HDF5 file which contains triangulated +# surface meshes of the members of the set as instances of +# NXcg_polyhedron_set. +# +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# String whereby the path to the geometry data can be interferred automatically. +# Currently groupname_geometry_prefix/object<ID>/polyhedron. +# +# +# +# +# Array of identifier whereby the path to the geometry data +# can be interferred automatically. +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_nanochem.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_nanochem.yaml new file mode 100644 index 0000000000..07fab0a79e --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_nanochem.yaml @@ -0,0 +1,2048 @@ +category: application +doc: | + Configuration of a paraprobe-nanochem tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ityp_deloc_cand: | + How many iontypes does the delocalization filter specify. + n_control_pts: | + How many disjoint control points are defined. + n_fct_filter_cand: | + How many iontypes does the interface meshing iontype filter specify. + n_fct_iterations: | + How many DCOM iterations. + n_ivec: | + Maximum number of atoms per molecular ion. +type: group +NXapm_paraprobe_config_nanochem(NXobject): + (NXentry): + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_nanochem] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to + UTC information included when this configuration file was created. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many individual analyses should the tool execute as part of the analysis. + (NXprocess): + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + hit_multiplicity_filter(NXmatch_filter): + exists: optional + edge_of_the_dataset(NXprocess): + doc: | + The tool enables to inject a previously computed triangle soup or + triangulated surface mesh representing a model (of the surface) of + the edge of the dataset. This model can be used to detect and control + various sources of bias in the analyses. + + # NEW ISSUE: exists: optional + filename: + doc: | + Name of the HDF5 file which contains vertex coordinates and facet + indices to describe the desired set of triangles which represents + the edge of the dataset. + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + dataset_name_vertices: + doc: | + Absolute path to the HDF5 dataset in the respectively specified HDF5 + file under filename which details the array of vertex positions. + dataset_name_facet_indices: + doc: | + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details the array of facet indices. + ion_to_edge_distances(NXprocess): + exists: optional + doc: | + The tool enables to inject precomputed distance information for each + point/ion which can be used for further post-processing and analysis. + + # NEW ISSUE: is this optional? + filename: + doc: | + Name of an HDF5 file which contains the ion distances. + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + dataset_name: + doc: | + Absolute HDF5 path to the dataset with distance values for each ion. + + # number_of_delocalizations(NX_UINT): + # doc: | + # For now a support field for the tool to identify how many individual + # delocalization analyses for the above-mentioned dataset and supplementary + # files are executed as part of the high-throughput analysis. + # unit: NX_UNITLESS + + # NEW ISSUE delocalization is all lower case meaning you cannot have right now multiple of these + # even though paraprobe-nanochem triggers a number of delocalizations for each of which triggering again isosurfaces + # currently the principal idea behind this design is that you normally focus iso-surface-based analyses + # on specific elements and for these you may have different discretization and isosurface computation demands + # for instance you might be super interested in analyzing in find details the iso-surfaces of carbon in a dataset + # but in addition you could be interested also to study chromium iso-surfaces but for completely different iso-contour values + # etc. this is what paraprobe-nanochem allows you to do + # you create one process for all your carbon related delocalizations, isosurfaces etc + # plus another process packing all your chromium delocalization and isosurfaces + delocalization(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Discretization of the ion point cloud on a three-dimensional grid. + input: + doc: | + Delocalization in the field of atom probe microscopy is the process + of discretizing a point cloud. By default the tool computes a full + kernel density estimation of decomposed ions to create one discretized + field for each element. + + Although, this uses an efficient multithreaded algorithm, + the computation is costly. Therefore, it can be advantageous for users + to load an already computed delocalization. This can be achieved with + the load_existent option. + When using this option the user is responsible to assure that the + settings which were used for computing this already existent delocalization + are specified in the same manner as they were. + + # NEW ISSUE: improve UX experience + enumeration: [default, load_existent] + + # NEW ISSUE: base class filter + isotope_whitelist(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of isotope vectors representing iontypes. + The filter specifies a matrix of isotope_vectors which is the most + general approach to define if and how many times an ion is counted. + Currently, paraprobe_nanochem performs a so-called atomic decomposition + of all iontypes. Specifically, the tool interprets of how many + elements/atoms a molecular ion is composed; and thus determines the + atoms multiplicity with respect to the iontype. + + Let's take the hydroxonium H3O+ molecular ion as an example: + It contains hydrogen and oxygen as atoms. The multiplicity of hydrogen + is three whereas that of oxygen is one. Therefore in an atomic + decomposition computation of the iso-surface each H3O+ ion adds + three hydrogen counts. This is a practical solution which accepts + the situation that during an atom probe experiment not each bond + of each ion/a group of neighboring atoms is broken but molecular + ions get detected. The exact ab-initio details depend on the local + field conditions and thus also the detailed spatial arrangement + of the atoms and their own electronic state and that of the neighbors + before and upon launch. + Being able to measure the information for such sites only as + molecular ions causes an inherent information loss with respect to the + detailed spatial arrangement. This information loss is more relevant + for local electrode atom probe than for field ion microscopy setting + how precisely the atomic positions can be reconstructed. + Accounting for multiplicities assures that at least the + compositional information is analyzed. + dimensions: + rank: 2 + dim: [[1, n_ityp_deloc_cand], [2, n_ivec]] + gridresolutions(NX_FLOAT): + unit: NX_LENGTH + doc: | + List of individual grid resolutions to analyse. + Paraprobe discretizes on a cuboidal 3D grid with cubic cells, with + an edge length of values in gridresolutions. + + # \@units: nm + kernel_size(NX_UINT): + unit: NX_UNITLESS + doc: | + Half the width of a :math:`{(2 \cdot n + 1)}^3` cubic kernel of voxel + beyond which the Gaussian Ansatz function will be truncated. + Intensity beyond the kernel is refactored into the kernel via + a normalization procedure. + kernel_variance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Variance of the Gaussian Ansatz kernel :math:`\sigma_x = \sigma_y = 2 \cdot + \sigma_z`. + + # \@units: nm + normalization: + doc: | + How should the results of the kernel-density estimation be computed + into quantities. By default the tool computes the total number + (intensity) of ions or elements. Alternatively the tool can compute + the total intensity, the composition, or the concentration of the + ions/elements specified by the white list of elements in each voxel. + enumeration: [total, candidates, composition, concentration] + has_scalar_fields(NX_BOOLEAN): + doc: | + Specifies if the tool should report the delocalization 3D field values. + + # number_of_isosurfaces: + # doc: For now a support field for the tool to identify how many individual analyses the tool should execute during the analysis run. + # unit: NX_UNITLESS + + # NEW ISSUE: currently isosurface has to be a child of delocalization because otherwise + # you could construct the incorrect situation that you leave delocalization optional do not add sth there but fill isosurface + # and this does not work because without a delocalization/field quantity you cannot compute iso-surfaces + isosurfacing(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Optional computation of iso-surfaces after each computed delocalization + to identify for instance objects in the microstructure + (line features, interfaces, precipitates). + edge_handling_method: + doc: | + As it is detailed in M. Kühbach et al. 2022 npj Comp. Mat., + the handling of triangles at the edge of the dataset requires + special attention. Especially for composition-normalized + delocalization it is possible that the composition increases + towards the edge of the dataset because the quotient of two numbers + which are both smaller than one is larger instead of smaller than + the counter. By default, the tool uses a modified marching cubes + algorithm of Lewiner et al. which detects if voxels face such a + situation. In this case, no triangles are generated for such voxels. + Alternatively, (via setting keep_edge_triangles) the user can + instruct the tool to not remove these triangles at the cost of bias. + + Specifically, in this case the user should understand that all + objects/microstructural features in contact with the edge of the + dataset get usually artificial enlarged and their surface mesh + often closed during the marching. This closure however is artificial! + It can result in biased shape analyses for those objects. + The reason why this should in general be avoided is a similar + argument as when one analyzes grain shapes in orientation microscopy + via e.g. SEM/EBSD. Namely, these grains, here the objects at the + edge of the dataset, were not fully captured during e.g. limited + field of view. + Therefore, it is questionable if one would like to make + substantiated quantitative statements about them. + + Thanks to collaboration with the V. V. Rielli and S. Primig, though, + paraprobe-nanochem implements a complete pipeline to + process even these objects at the edge of the dataset. Specifically, + the objects are replaced by so-called proxies, i.e. replacement + objects whose holes on the surface mesh have been closed if possible + via iterative mesh and hole-filling procedures with fairing operations. + In the results of each paraprobe-nanochem run, these proxy objects + are listed separately to allow users to quantify and analyze in + detail the differences when accounting for these objects or not. + Especially this is relevant in atom probe microscopy as objects + can contain a few dozen atoms only. + Users should be aware that results from fairing operations should + be compared to results from analyses where all objects at the edge + of the dataset have been removed. + + Also users should be careful with overestimating the statistical + significance of their dataset especially when using atom probe + to compare multiple descriptors: Even though a dataset may give + statistically significant results for compositions, this does not + necessarily mean it will yield also statistically significant + and unbiased results for three-dimensional object analyses. + Being able to quantify these effects and making atom probers + aware of these subtleties was one of the main reasons why the + paraprobe-nanochem tool was implemented. + enumeration: [default, keep_edge_triangles] + edge_threshold(NX_FLOAT): + unit: NX_LENGTH + doc: | + The ion-to-edge-distance that is used in the analyses of objects + (and proxies) to identify whether these are inside the dataset or + close to the edge of the dataset. If an object has at least one ion + with an ion-to-edge-distance below this threshold, the object is + considered as one which lies close to the edge of the dataset. + This implements essentially a distance-based approach to solve + the in general complicated and involved treatment of computing + volumetric intersections between not-necessarily convex + closed 2-manifolds. In fact, such computational geometry analyses + can face numerical robustness issues as a consequence of which a + mesh can be detected as lying completely inside a dataset although + in reality it is epsilon-close only, i.e. almost touching only + the edge (e.g. from inside). + Practically, humans would state in such case that the object is + close to the edge of the dataset; however mathematically the object + is indeed completely inside. + In short, a distance-based approach is rigorous and more flexible. + + # \@units: nm + phi(NX_FLOAT): + unit: NX_ANY + doc: | + Array of iso-contour values. For each value the tool computes + an iso-surface and performs subsequent analyses. + The unit depends on the choice for the normalization of the + accumulated ion intensity values per voxel: + + * total, total number of ions, irrespective their iontype + * candidates, total number of ions with type in the isotope_whitelist. + * composition, candidates but normalized by composition, i.e. at.-% + * concentration, candidates but normalized by voxel volume, i.e. ions/nm^3 + + # NEW ISSUE: details what these options activate need to be described in more detail !!!!! + has_triangle_soup(NX_BOOLEAN): + doc: | + Specifies if the tool should report the triangle soup which represents + each triangle of the iso-surface complex. + Each triangle is reported with an ID specifying to which triangle + cluster (with IDs starting at zero) the triangle belongs. + The clustering is performed with a modified DBScan algorithm. + has_object(NX_BOOLEAN): + doc: | + Specifies if the tool should analyze for each cluster of triangles + how they can be combinatorially processed to describe a closed + polyhedron. Such a closed polyhedron (not-necessarily convex!) + can be used to describe objects with relevance in the microstructure. + Users should be aware that the resulting mesh does not necessarily + represent the original precipitate. In fact, inaccuracies in the + reconstructed positions cause inaccuracies in all downstream + processing operations. Especially the effect on one-dimensional + spatial statistics like nearest neighbor correlation functions these + effects were discussed in the literature + `B. Gault et al. `_ + In continuation of these thoughts this applies also to reconstructed + objects. A well-known example is the discussion of shape deviations + of Al3Sc precipitates in aluminium alloys which in reconstructions + can appear as ellipsoids although they should be almost spherical, + depending on their size. + has_object_geometry(NX_BOOLEAN): + doc: | + Specifies if the tool should report a triangulated surface mesh + for each identified closed polyhedron. It is common that a + marching cubes algorithm creates iso-surfaces with a fraction of very + small sub-complexes (e.g. small isolated tetrahedra). + + These can be for instance be small tetrahedra/polyhedra about the + center of a voxel of the support grid on which marching cubes operates. + When these objects are small, it is possible that they contain no ion; + especially when considering that delocalization procedures smoothen + the positions of the ions. Although these small objects are interesting + from a numerical point of view, scientists may argue they are not worth + to be reported: + Physically a microstructural feature should contain at least a few + atoms to become relevant. Therefore, paraprobe-nanochem by default + does not report closed objects which bound not at least one ion. + has_object_properties(NX_BOOLEAN): + doc: | + Specifies if the tool should report properties of each closed + polyhedron, such as volume and other details. + has_object_obb(NX_BOOLEAN): + doc: | + Specifies if the tool should report for each closed polyhedron an + approximately optimal bounding box fitted to all triangles of the + surface mesh of the object and ion positions inside or on the + surface of the mesh. + This bounding box informs about the closed object's shape + (aspect ratios). + + # NEW ISSUE: Addendum Alternatively it is possible to fit triaxial ellipsoids. + has_object_ions(NX_BOOLEAN): + doc: | + Specifies if the tool should report for each closed polyhedron + all evaporation IDs of those ions which lie inside or on the + boundary of the polyhedron. This information can be used e.g. + in the paraprobe-intersector tool to infer if two objects share + common ions, which can be interpreted as an argument to assume + that the two objects intersect. + + Users should be aware that two arbitrarily closed polyhedra + in three-dimensional space can intersect but not share a common ion. + In fact, the volume bounded by the polyhedron has sharp edges. + When taking two objects, an edge of one object may for instance + pierce into the surface of another object. In this case the + objects partially overlap / intersect volumetrically; + however this piercing might be so small or happening in the volume + between two ion positions and thus sharing ions is a sufficient + but not a necessary condition for object intersections. + + Paraprobe-intersector implements a rigorous alternative to handle + such intersections using a tetrahedralization of closed objects. + However, in many practical cases, we found through examples that there + are polyhedra (especially when they are non-convex and have almost + point-like) connected channels, where tetrahedralization libraries + have challenges dealing with. In this case checking intersections + via shared_ions is a more practical alternative. + has_object_edge_contact(NX_BOOLEAN): + doc: | + Specifies if the tool should report if a (closed) object has + contact with the edge of the dataset. For this the tool currently + inspects if the shortest distance between the set of triangles of the + surface mesh and the triangles of the edge model is larger than the + edge_threshold. If this is the case, the object is assumed to be + deeply embedded in the interior of the dataset. Otherwise, the object + is considered to have an edge contact, i.e. it is likely affected + by the fact that the dataset is finite. + + # the edge_threshold can be decided based on half the length of the diagonal of the delocalization kernel. + # as a consequence of which wider kernels result in larger threshold values causing more objects to become + # qualified as having edge contact. + has_proxy(NX_BOOLEAN): + doc: | + Specifies if the tool should analyze a doppelganger/proxy mesh for + each cluster of triangles whose combinatorial analysis according + to has_object showed that the object is not a closed polyhedron. + Such proxies are closed via iterative hole-filling, mesh refinement, + and fairing operations. + Users should be aware that the resulting mesh does not necessarily + represent the original precipitate. In most cases objects, + like precipitates in atom probe end up as open objects because + they have been clipped by the edge of the dataset. Using a proxy is + then a strategy to still be able to account for these objects. + Nevertheless users should make themselves familiar with the + potential consequences and biases which this can introduce + into the analysis. + has_proxy_geometry(NX_BOOLEAN): + doc: | + Like has_object_geometry but for the proxies. + has_proxy_properties(NX_BOOLEAN): + doc: | + Like has_object_properties but for the proxies. + has_proxy_obb(NX_BOOLEAN): + doc: | + Like has_object_obb but for the proxies. + has_proxy_ions(NX_BOOLEAN): + doc: | + Like has_object_ions but for the proxies. + has_proxy_edge_contact(NX_BOOLEAN): + doc: | + Like has_object_edge_contact but for the proxies. + has_object_auto_proxigram(NX_BOOLEAN): + doc: | + Specifies if the tool should report for each closed object a + (cylindrical) region of interest placed, centered, and align + with the local normal for each triangle of the object. + has_object_auto_proxigram_edge_contact(NX_BOOLEAN): + doc: | + Specifies if the tool should report for each ROI that was placed + at a triangle of each object if this ROI intersects the edge of + the dataset. Currently paraprobe-nanochem supports cylindrical + ROIs. A possible intersection of these with the edge of the + dataset, i.e. the triangulated surface mesh model for the edge + is performed. This test checks if the cylinder intersects with + a triangle of the surface mesh. If this is the case, the ROI is + assumed to make edge contact, else, the ROI is assumed to have + no edge contact. + + This approach does not work if the ROI would be completely + outside the dataset. Also in this case there would be + no intersection. For atom probe this case is practically + irrelevant because for such a ROI there would also be no ion + laying inside the ROI. Clearly it has thus to be assumed that + the edge model culls the entire dataset. Instead, if one would + cut a portion of the dataset, compute an edge model for this + point cloud, it might make sense to place a ROI but in this + case the edge contact detection is not expected to work properly. + + # has_object_mesh_smoothing(NX_BOOLEAN): + # doc: Specifies if the tool should post-process each mesh to improve the mesh quality. + # mesh_smoothing(NXprocess): + # NEW ISSUE: here we need to specify how the meshes were smoothened + ##MK::is this group not at the previous level of the hierarchy? + interfacial_excess(NXprocess): + exists: optional + doc: | + Analyses of interfacial excess. + interface_model: + doc: | + Interfacial excess computations are performed for local regions-of-interests + (ROIs) at selected facets or interface patch. + For instance many scientist compute the interfacial excess for + selected triangle facets of a created iso-surface. In this case, + computed iso-surfaces of paraprobe could be used. An example are triangle + facet sets about closed polyhedra, for instance to compute interfacial + excess related to phase boundaries of second-phase precipitates. + + Another example are free-standing triangle patches of the iso- + surfaces which paraprobe creates. These could be characterized + for interfacial excess. The sub-routines during iso-surface + computations already include a procedure to automatically align + local triangle normals based on the gradients of e.g. composition + fields. In this case, these triangulated surface patches + could also be used as a source for computing interfacial + excess. + + Often scientists face situations, though, in which there is no + immediately evident composition gradient across the interface + (grain or phase boundary) and orientation information about the + adjoining crystal is neither available nor reliable enough. + + In this case `P. Felfer et al. `_ proposed a method + to manually place control points and run an automated tessellation-based + algorithm to create a triangulated surface patch, i.e. a model of the + location of the interface. In a post-processing step this triangle + set can then be used to compute again interfacial excess in an + automated manner by placing ROIs and aligning them with + consistently precomputed triangle normals. + + A similar use case is conceptually the one proposed by `X. Zhou et al. `_ + They used first a deep-learning method to locate planar triangulated + grain boundary patches. These are eventually processed further + with manual editing of the mesh via tools like Blender. + Once the user is satisfied with the mesh, the computations of interfacial + excess reduce again to an automated placing of ROIs, computations + of the distributing of ions to respective ROIs and + reporting the findings via plotting. + + Yet another approach for constructing an triangulated surface patch + of an interface is to use point cloud processing methods which have + been proposed in the laser-scanning, geoinformatics, and CAD community. + Different computational geometry methods are available for fitting + a parameterized surface to a set of points, using e.g. non-uniform + rational B-splines (NURBS) and triangulating these according + to prescribed mesh quality demands. + + The advantage of these methods is that they can be automated and + pick up curved interface segments. The disadvantage is their often + strong sensitivity to parameterization. As a result also such methods + can be post-processed to yield a triangulated surface patch, + and thus enable to run again automated ROI placement methods. + For example like these which were explored for the use case of + iso-surfaces with closed objects and free-standing + surface patches that delineate regions of the dataset with a + pronounced composition gradient normal to the interface. + + This summary of the situations which atom probers can face when + requesting for interfacial excess computations, substantiates there + exists a common set of settings which can describe all of these methods + and, specifically, as here exemplified, the automated placing + and alignment functionalities for ROIs that is an important + step all these workflows. + + Specifically, paraprobe-nanochem operates on an already existent + triangle set. + enumeration: [isosurface, external] + + # NEW ISSUE: how to implement and also check consistently via NeXus that a + # NEW ISSUE: child group is required only when a field has a certain value? + external(NXprocess): + exists: optional + doc: | + The interface model is the result of a previous (set of) processing + steps as a result of which the user has created a triangulated + surface mesh (or a set of, eventually connected such meshes). + These interface models are useful, if not required, in cases when + there is no other independent approach to locate an interface. + + These are cases when insufficient crystallographic latent + information is available and also no consistent concentration + gradient detectable across the interface. It is then the users' + responsibility to deliver a triangle mesh of the interface model. + file_name: + doc: | + Filename to HDF5 file which contain vertex coordinates, facet indices, + facet unit normals. The user is responsible for the triangle + and winding order to be consistent. + Input is expected as a matrix of the coordinates for all disjoint + vertices, a (Nvertices, 3)-shaped array of NX_FLOAT. + Input is expected to include also a matrix of facet indices + referring to these disjoint vertices. This matrix should be a + (Nfacets, 3)-shaped array of NX_UINT. Further required input + is a (Nfacets, 3)-shaped array of NX_FLOAT signed facet unit + normals and a (Nvertices, 3)-shaped array of NX_FLOAT signed + vertex unit normals. Vertex indices need to start at zero and + must not exceed Nvertices - 1, i.e. the identifier_offset is 0 + and facet indices are indexed implicitly, i.e. [0, Nvertices-1]. + \@version: + doc: | + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically + contains these data. + dataset_name_vertices: + doc: | + Absolute HDF5 path to the dataset which specifies the + array of vertex positions. + dataset_name_facet_indices: + doc: | + Absolute HDF5 path to the dataset which specifies the + array of facet indices. + dataset_name_facet_normals: + doc: | + Absolute HDF5 path to the dataset which specifies the + array of facet signed unit normals. + dataset_name_facet_vertices: + doc: | + Absolute HDF5 path to the dataset which specifies the + array of vertex signed unit normals. + + Users should be aware that triangulated surface meshes are + only approximations to a given complex, eventually curved shape. + Consequently, computations of normals show differences between + the vertex and facet normals. Vertex normals have to be + interpolated from normals of neighboring facets. Consequently, + these normals are affected by the underlying parameterization + and curvature estimation algorithms, irrespective of how + contributions from neighboring facets are weighted. By contrast, + facet normals are clearly defined by the associated triangle. + Their disadvantage is that they the normal field has discontinuities + at the edges. In general the coarser an object is triangulated + the more significant the difference becomes between computations + based on facet or vertex normals. + Paraprobe-nanochem works with facet normals as it can use + parts of the numerical performance gained by using cutting + edge libraries to work rather with finer meshes. + interface_meshing(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Create a simple principle component analysis (PCA) to mesh a + free-standing interface patch through a point cloud of decorating solutes. + These models can be useful for quantification of Gibbsian + interfacial excess for interfaces where iso-surface based methods + may fail or closed objects from iso-surfaces are not desired or + when e.g. there are no substantial or consistently oriented + concentration gradients across the interface patch. + + The interface_meshing functionality of paraprobe-nanochem can be useful + when there is also insufficient latent crystallographic information + available that could otherwise support modelling the interface, + via e.g. ion density traces in field-desorption maps, as were used and + discussed by `Y. Wei et al. `_ + or are discussed by `A. Breen et al. `_ + + It is noteworthy that the method here used is conceptually very similar + in implementation to the work by `Z. Peng et al. `_ + Noteworthy, her team uses the DCOM approach originally proposed by P. Felfer et al. + However, both of these previous works neither discuss in detail + nor implement inspection functionalities which enable a detection of + potential geometric inconsistencies or self-interactions of the + resulting DCOM mesh. This is what paraprobe-nanochem implements + via the Computational Geometry Algorithms Library. + initialization: + doc: | + Method how to initialize the PCA: + + * default, means based on segregated solutes in the ROI + * control_point_file, means based on reading an external list of + control points, currently coming from the Leoben APT_Analyzer. + + The control_point_file is currently expected with a specific format. + The Leoben group lead by L. Romaner has developed a GUI tool `A. Reichmann et al. `_ + to create a control_point_file which can be parsed by paraprobe-parmsetup + to match the here required formatting in control_points. + enumeration: [default, control_point_file] + filename: + doc: | + The name of the control point file to use. + \@version: + doc: | + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically + contains these data. + control_points(NX_FLOAT): + unit: NX_LENGTH + doc: | + X, Y, Z coordinates of disjoint control point read from + an HDF5 file named according to control_point_file. + + # \@units: nm + dimensions: + rank: 2 + dim: [[1, N], [2, n_control_pts]] + method: + doc: | + Method used for identifying and refining the location of the + interface. Currently, paraprobe-nanochem implements a PCA followed + by an iterative loop of isotropic mesh refinement and DCOM step(s), + paired with self-intersection detection in a more robust + implementation. + enumeration: [pca_plus_dcom] + decorating_iontypes_filter(NXprocess): + doc: | + Specify the types of those ions which decorate the interface and + can thus be assumed as markers for locating the interface and + refining its local curvature. + candidates(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of iontypes to filter. The list is interpreted as a whitelist, + i.e. ions of these types are considered the decorating species (solutes). + dimensions: + rank: 1 + dim: [[1, n_fct_filter_cand]] + number_of_iterations(NX_UINT): + unit: NX_UNITLESS + doc: | + How many times should the DCOM and mesh refinement be applied? + target_edge_length(NX_FLOAT): + unit: NX_LENGTH + doc: | + Array of decreasing positive not smaller than one nanometer real values + which specify how the initial triangles of the mesh should be iteratively + refined by edge splitting and related mesh refinement operations. + + # \@units: nm + dimensions: + rank: 1 + dim: [[1, n_fct_iterations]] + target_dcom_radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + Array of decreasing positive not smaller than one nanometer real values + which specify the radius of the spherical region of interest within + which the DCOM algorithm decides for each vertex how the vertex will + be eventually relocated. The larger the DCOM radius is relative to + the target_edge_length the more likely it is that vertices will be + relocated so substantially that eventually triangle self-intersections + can occur. If the code detects these it warns and stops in a + controlled manner so that the user can repeat the analyses + with a smaller value. + + # \@units: nm + dimensions: + rank: 1 + dim: [[1, n_fct_iterations]] + target_smoothing_step(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of integers which specify for each DCOM step how many times + the mesh should be iteratively smoothened. + + Users should be aware the three array target_edge_length, + target_dcom_radius, and target_smoothing_step are interpreted in the + same sequence, i.e. the zeroth entry of each array specifies the + values to be used in the first DCOM iteration. The first entry of + each array those for the second DCOM iteration and so on and so forth. + dimensions: + rank: 1 + dim: [[1, n_fct_iterations]] + composition_profiling(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Functionalities for placing regions-of-interest (ROIs) in the dataset + or at specific microstructural features to characterize composition + profiles and cumulated profiles for quantification of interfacial excess. + Paraprobe-nanochem currently places cylindrical ROIs. ROIs are probed + across the triangulated surface of a user-defined mesh. + ROIs are placed at the barycenter of the triangular facet. + + The tool can be instructed to orient the profile for each ROIs with + the positive normal of the triangle facet normals. Profiles are + computed for each ROI and facet triangle. The code will test which + ROIs are completely embedded in the dataset. + Specifically, in this test the tool evaluates if the ROI cuts at least + one triangle of the triangulated surface mesh of the edge of the dataset. + If this is the case the ROI will be considered close to the edge + (of the dataset) and not analyzed further; else the ROI will be + processed further. + Users should be aware that the latter intersection analysis is strictly + speaking not a volumetric intersection analysis as such one is much + more involved because the edge model can be a closed non-convex polyhedron + in which case one would have to test robustly if the cylinder pierces + or is laying completely inside the polyhedron. For this the polyhedron has + to be tessellated into convex polyhedra as otherwise tests like the + Gilbert-Johnson-Keerthi algorithm would not be applicable. + + Specifically, the tool computes atomically decomposed profiles. + This means molecular ions are split into atoms/isotopes with respective + multiplicity. As an example an H3O+ molecular ion contains three + hydrogen and one oxygen atom respectively. The tool then evaluates + how many ions are located inside the ROI or on the surface of the + ROI respectively. All atom types and the unranged ions are distinguished. + As a result, the analyses yield for each ROI a set of sorted lists of + signed distance values. Currently, the distance is the projected + distance of the ion position to the barycenter of the triangle + and triangle plane. + + This will return a one-dimensional profile. Post-processing the set + of atom-type-specific profiles into cumulated profiles enable the + classical Krakauer/Seidman-style interfacial excess analyses. + Furthermore, the tool can be instructed to compute for each + (or a selected sub-set of facet) a set of differently oriented profiles. + + # In the second case, these profiles will be probed in the direction of + # the outer unit surface normal vectors of a sphere. The sphere is + # discretized via a geodesic sphere (according to ideas of M. Kühbach + # et al. Journal of Applied Crystallography 2021) model with 40962 + # directions, some of which are duplicates (for now). This direction + # sampling enables substantially more detailed analyses of the effect + # of aligning the ROI because alignments of ROI based on triangle + # surface normals of the feature mesh can result in larger direction + # differences between neighboring ROIs when the mesh for rough + # surface meshes. + feature_mesh(NXprocess): + doc: | + The feature mesh enables the injection of previously computed triangle + soup or mesh data. Such a mesh can be the model for a grain- or phase + boundary patch (from e.g. interface_meshing) jobs. + filename: + doc: | + Name of the HDF5 file which contains vertex coordinates and facet + indices to describe the desired set of triangles which represents + the feature. + \@version: + doc: | + Version identifier of the file such as a secure hash which documents + the binary state of the file to add an additional layer of + reproducibility from which file specifically contains these data. + dataset_name_vertices: + doc: | + Absolute path to the HDF5 dataset in the respectively specified HDF5 + file under filename which details the array of vertex positions. + dataset_name_facet_indices: + doc: | + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details the array of facet indices. + dataset_name_facet_normals: + doc: | + Absolute path to the HDF5 dataset in the respective specified HDF5 + file under filename which details consistently oriented facet + normals of the facets. + + # dataset_name_vertex_normals: + # doc: Absolute path to the HDF5 dataset in the respective specified + # HDF5 file under filename which details consistently oriented + # vertex normals of the facets. + # exists: optional + patch_identifier_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + ion_to_feature_distances(NXprocess): + exists: optional + doc: | + The tool enables to inject precomputed distance information for each + point which can be used for further post-processing and analysis. + + # NEW ISSUE: is this optional? + filename: + doc: | + Name of an HDF5 file which contains ion distances. + \@version: + doc: | + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional + layer of reproducibility from which file specifically contains + these data. + dataset_name: + doc: | + Absolute HDF5 path to the dataset with distance values for each ion. + distancing_model: + doc: | + Which type of distance should be reported for the profile. + enumeration: [project_to_triangle_plane] + + # NEW ISSUE:, ion_to_feature] + direction_model: + doc: | + In which directions should the tool probe for each ROI. + enumeration: [triangle_outer_unit_normal] + + # NEW ISSUE:, angularly_geodesic_sphere] + roi_cylinder_height(NX_FLOAT): + unit: NX_LENGTH + doc: | + For each ROI, how high (projected on the cylinder axis) + should the cylindrical ROI be. + + # \@units: nm + # all ROIs the same height + # dimensions: + # rank: 1 + # dim: [[1, 1]] + roi_cylinder_radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + For each ROI, how wide (radius) should the cylindrical ROI be. + + # \@units: nm + # all ROIs the same radius + # dimensions: + # rank: 1 + # dim: [[1, 1]] + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1284c5c27884acb07242d7f237e65ab62a417f86051e12e75d536a4656d03f82 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# How many iontypes does the delocalization filter specify. +# +# +# +# +# How many disjoint control points are defined. +# +# +# +# +# How many iontypes does the interface meshing iontype filter specify. +# +# +# +# +# How many DCOM iterations. +# +# +# +# +# Maximum number of atoms per molecular ion. +# +# +# +# +# Configuration of a paraprobe-nanochem tool run in atom probe microscopy. +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to +# UTC information included when this configuration file was created. +# +# +# +# +# How many individual analyses should the tool execute as part of the analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The tool enables to inject a previously computed triangle soup or +# triangulated surface mesh representing a model (of the surface) of +# the edge of the dataset. This model can be used to detect and control +# various sources of bias in the analyses. +# +# +# +# +# Name of the HDF5 file which contains vertex coordinates and facet +# indices to describe the desired set of triangles which represents +# the edge of the dataset. +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# Absolute path to the HDF5 dataset in the respectively specified HDF5 +# file under filename which details the array of vertex positions. +# +# +# +# +# Absolute path to the HDF5 dataset in the respective specified HDF5 +# file under filename which details the array of facet indices. +# +# +# +# +# +# The tool enables to inject precomputed distance information for each +# point/ion which can be used for further post-processing and analysis. +# +# +# +# +# Name of an HDF5 file which contains the ion distances. +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# Absolute HDF5 path to the dataset with distance values for each ion. +# +# +# +# +# +# +# +# Discretization of the ion point cloud on a three-dimensional grid. +# +# +# +# Delocalization in the field of atom probe microscopy is the process +# of discretizing a point cloud. By default the tool computes a full +# kernel density estimation of decomposed ions to create one discretized +# field for each element. +# +# Although, this uses an efficient multithreaded algorithm, +# the computation is costly. Therefore, it can be advantageous for users +# to load an already computed delocalization. This can be achieved with +# the load_existent option. +# When using this option the user is responsible to assure that the +# settings which were used for computing this already existent delocalization +# are specified in the same manner as they were. +# +# +# +# +# +# +# +# +# +# +# Matrix of isotope vectors representing iontypes. +# The filter specifies a matrix of isotope_vectors which is the most +# general approach to define if and how many times an ion is counted. +# Currently, paraprobe_nanochem performs a so-called atomic decomposition +# of all iontypes. Specifically, the tool interprets of how many +# elements/atoms a molecular ion is composed; and thus determines the +# atoms multiplicity with respect to the iontype. +# +# Let's take the hydroxonium H3O+ molecular ion as an example: +# It contains hydrogen and oxygen as atoms. The multiplicity of hydrogen +# is three whereas that of oxygen is one. Therefore in an atomic +# decomposition computation of the iso-surface each H3O+ ion adds +# three hydrogen counts. This is a practical solution which accepts +# the situation that during an atom probe experiment not each bond +# of each ion/a group of neighboring atoms is broken but molecular +# ions get detected. The exact ab-initio details depend on the local +# field conditions and thus also the detailed spatial arrangement +# of the atoms and their own electronic state and that of the neighbors +# before and upon launch. +# Being able to measure the information for such sites only as +# molecular ions causes an inherent information loss with respect to the +# detailed spatial arrangement. This information loss is more relevant +# for local electrode atom probe than for field ion microscopy setting +# how precisely the atomic positions can be reconstructed. +# Accounting for multiplicities assures that at least the +# compositional information is analyzed. +# +# +# +# +# +# +# +# +# List of individual grid resolutions to analyse. +# Paraprobe discretizes on a cuboidal 3D grid with cubic cells, with +# an edge length of values in gridresolutions. +# +# +# +# +# +# Half the width of a :math:`{(2 \cdot n + 1)}^3` cubic kernel of voxel +# beyond which the Gaussian Ansatz function will be truncated. +# Intensity beyond the kernel is refactored into the kernel via +# a normalization procedure. +# +# +# +# +# Variance of the Gaussian Ansatz kernel :math:`\sigma_x = \sigma_y = 2 \cdot +# \sigma_z`. +# +# +# +# +# +# How should the results of the kernel-density estimation be computed +# into quantities. By default the tool computes the total number +# (intensity) of ions or elements. Alternatively the tool can compute +# the total intensity, the composition, or the concentration of the +# ions/elements specified by the white list of elements in each voxel. +# +# +# +# +# +# +# +# +# +# +# Specifies if the tool should report the delocalization 3D field values. +# +# +# +# +# +# +# Optional computation of iso-surfaces after each computed delocalization +# to identify for instance objects in the microstructure +# (line features, interfaces, precipitates). +# +# +# +# As it is detailed in M. Kühbach et al. 2022 npj Comp. Mat., +# the handling of triangles at the edge of the dataset requires +# special attention. Especially for composition-normalized +# delocalization it is possible that the composition increases +# towards the edge of the dataset because the quotient of two numbers +# which are both smaller than one is larger instead of smaller than +# the counter. By default, the tool uses a modified marching cubes +# algorithm of Lewiner et al. which detects if voxels face such a +# situation. In this case, no triangles are generated for such voxels. +# Alternatively, (via setting keep_edge_triangles) the user can +# instruct the tool to not remove these triangles at the cost of bias. +# +# Specifically, in this case the user should understand that all +# objects/microstructural features in contact with the edge of the +# dataset get usually artificial enlarged and their surface mesh +# often closed during the marching. This closure however is artificial! +# It can result in biased shape analyses for those objects. +# The reason why this should in general be avoided is a similar +# argument as when one analyzes grain shapes in orientation microscopy +# via e.g. SEM/EBSD. Namely, these grains, here the objects at the +# edge of the dataset, were not fully captured during e.g. limited +# field of view. +# Therefore, it is questionable if one would like to make +# substantiated quantitative statements about them. +# +# Thanks to collaboration with the V. V. Rielli and S. Primig, though, +# paraprobe-nanochem implements a complete pipeline to +# process even these objects at the edge of the dataset. Specifically, +# the objects are replaced by so-called proxies, i.e. replacement +# objects whose holes on the surface mesh have been closed if possible +# via iterative mesh and hole-filling procedures with fairing operations. +# In the results of each paraprobe-nanochem run, these proxy objects +# are listed separately to allow users to quantify and analyze in +# detail the differences when accounting for these objects or not. +# Especially this is relevant in atom probe microscopy as objects +# can contain a few dozen atoms only. +# Users should be aware that results from fairing operations should +# be compared to results from analyses where all objects at the edge +# of the dataset have been removed. +# +# Also users should be careful with overestimating the statistical +# significance of their dataset especially when using atom probe +# to compare multiple descriptors: Even though a dataset may give +# statistically significant results for compositions, this does not +# necessarily mean it will yield also statistically significant +# and unbiased results for three-dimensional object analyses. +# Being able to quantify these effects and making atom probers +# aware of these subtleties was one of the main reasons why the +# paraprobe-nanochem tool was implemented. +# +# +# +# +# +# +# +# +# The ion-to-edge-distance that is used in the analyses of objects +# (and proxies) to identify whether these are inside the dataset or +# close to the edge of the dataset. If an object has at least one ion +# with an ion-to-edge-distance below this threshold, the object is +# considered as one which lies close to the edge of the dataset. +# This implements essentially a distance-based approach to solve +# the in general complicated and involved treatment of computing +# volumetric intersections between not-necessarily convex +# closed 2-manifolds. In fact, such computational geometry analyses +# can face numerical robustness issues as a consequence of which a +# mesh can be detected as lying completely inside a dataset although +# in reality it is epsilon-close only, i.e. almost touching only +# the edge (e.g. from inside). +# Practically, humans would state in such case that the object is +# close to the edge of the dataset; however mathematically the object +# is indeed completely inside. +# In short, a distance-based approach is rigorous and more flexible. +# +# +# +# +# +# Array of iso-contour values. For each value the tool computes +# an iso-surface and performs subsequent analyses. +# The unit depends on the choice for the normalization of the +# accumulated ion intensity values per voxel: +# +# * total, total number of ions, irrespective their iontype +# * candidates, total number of ions with type in the isotope_whitelist. +# * composition, candidates but normalized by composition, i.e. at.-% +# * concentration, candidates but normalized by voxel volume, i.e. ions/nm^3 +# +# +# +# +# +# Specifies if the tool should report the triangle soup which represents +# each triangle of the iso-surface complex. +# Each triangle is reported with an ID specifying to which triangle +# cluster (with IDs starting at zero) the triangle belongs. +# The clustering is performed with a modified DBScan algorithm. +# +# +# +# +# Specifies if the tool should analyze for each cluster of triangles +# how they can be combinatorially processed to describe a closed +# polyhedron. Such a closed polyhedron (not-necessarily convex!) +# can be used to describe objects with relevance in the microstructure. +# Users should be aware that the resulting mesh does not necessarily +# represent the original precipitate. In fact, inaccuracies in the +# reconstructed positions cause inaccuracies in all downstream +# processing operations. Especially the effect on one-dimensional +# spatial statistics like nearest neighbor correlation functions these +# effects were discussed in the literature +# `B. Gault et al. <https://doi.org/10.1017/S1431927621012952>`_ +# In continuation of these thoughts this applies also to reconstructed +# objects. A well-known example is the discussion of shape deviations +# of Al3Sc precipitates in aluminium alloys which in reconstructions +# can appear as ellipsoids although they should be almost spherical, +# depending on their size. +# +# +# +# +# Specifies if the tool should report a triangulated surface mesh +# for each identified closed polyhedron. It is common that a +# marching cubes algorithm creates iso-surfaces with a fraction of very +# small sub-complexes (e.g. small isolated tetrahedra). +# +# These can be for instance be small tetrahedra/polyhedra about the +# center of a voxel of the support grid on which marching cubes operates. +# When these objects are small, it is possible that they contain no ion; +# especially when considering that delocalization procedures smoothen +# the positions of the ions. Although these small objects are interesting +# from a numerical point of view, scientists may argue they are not worth +# to be reported: +# Physically a microstructural feature should contain at least a few +# atoms to become relevant. Therefore, paraprobe-nanochem by default +# does not report closed objects which bound not at least one ion. +# +# +# +# +# Specifies if the tool should report properties of each closed +# polyhedron, such as volume and other details. +# +# +# +# +# Specifies if the tool should report for each closed polyhedron an +# approximately optimal bounding box fitted to all triangles of the +# surface mesh of the object and ion positions inside or on the +# surface of the mesh. +# This bounding box informs about the closed object's shape +# (aspect ratios). +# +# +# +# +# +# Specifies if the tool should report for each closed polyhedron +# all evaporation IDs of those ions which lie inside or on the +# boundary of the polyhedron. This information can be used e.g. +# in the paraprobe-intersector tool to infer if two objects share +# common ions, which can be interpreted as an argument to assume +# that the two objects intersect. +# +# Users should be aware that two arbitrarily closed polyhedra +# in three-dimensional space can intersect but not share a common ion. +# In fact, the volume bounded by the polyhedron has sharp edges. +# When taking two objects, an edge of one object may for instance +# pierce into the surface of another object. In this case the +# objects partially overlap / intersect volumetrically; +# however this piercing might be so small or happening in the volume +# between two ion positions and thus sharing ions is a sufficient +# but not a necessary condition for object intersections. +# +# Paraprobe-intersector implements a rigorous alternative to handle +# such intersections using a tetrahedralization of closed objects. +# However, in many practical cases, we found through examples that there +# are polyhedra (especially when they are non-convex and have almost +# point-like) connected channels, where tetrahedralization libraries +# have challenges dealing with. In this case checking intersections +# via shared_ions is a more practical alternative. +# +# +# +# +# Specifies if the tool should report if a (closed) object has +# contact with the edge of the dataset. For this the tool currently +# inspects if the shortest distance between the set of triangles of the +# surface mesh and the triangles of the edge model is larger than the +# edge_threshold. If this is the case, the object is assumed to be +# deeply embedded in the interior of the dataset. Otherwise, the object +# is considered to have an edge contact, i.e. it is likely affected +# by the fact that the dataset is finite. +# +# +# +# +# +# Specifies if the tool should analyze a doppelganger/proxy mesh for +# each cluster of triangles whose combinatorial analysis according +# to has_object showed that the object is not a closed polyhedron. +# Such proxies are closed via iterative hole-filling, mesh refinement, +# and fairing operations. +# Users should be aware that the resulting mesh does not necessarily +# represent the original precipitate. In most cases objects, +# like precipitates in atom probe end up as open objects because +# they have been clipped by the edge of the dataset. Using a proxy is +# then a strategy to still be able to account for these objects. +# Nevertheless users should make themselves familiar with the +# potential consequences and biases which this can introduce +# into the analysis. +# +# +# +# +# Like has_object_geometry but for the proxies. +# +# +# +# +# Like has_object_properties but for the proxies. +# +# +# +# +# Like has_object_obb but for the proxies. +# +# +# +# +# Like has_object_ions but for the proxies. +# +# +# +# +# Like has_object_edge_contact but for the proxies. +# +# +# +# +# Specifies if the tool should report for each closed object a +# (cylindrical) region of interest placed, centered, and align +# with the local normal for each triangle of the object. +# +# +# +# +# Specifies if the tool should report for each ROI that was placed +# at a triangle of each object if this ROI intersects the edge of +# the dataset. Currently paraprobe-nanochem supports cylindrical +# ROIs. A possible intersection of these with the edge of the +# dataset, i.e. the triangulated surface mesh model for the edge +# is performed. This test checks if the cylinder intersects with +# a triangle of the surface mesh. If this is the case, the ROI is +# assumed to make edge contact, else, the ROI is assumed to have +# no edge contact. +# +# This approach does not work if the ROI would be completely +# outside the dataset. Also in this case there would be +# no intersection. For atom probe this case is practically +# irrelevant because for such a ROI there would also be no ion +# laying inside the ROI. Clearly it has thus to be assumed that +# the edge model culls the entire dataset. Instead, if one would +# cut a portion of the dataset, compute an edge model for this +# point cloud, it might make sense to place a ROI but in this +# case the edge contact detection is not expected to work properly. +# +# +# +# +# +# +# Analyses of interfacial excess. +# +# +# +# Interfacial excess computations are performed for local regions-of-interests +# (ROIs) at selected facets or interface patch. +# For instance many scientist compute the interfacial excess for +# selected triangle facets of a created iso-surface. In this case, +# computed iso-surfaces of paraprobe could be used. An example are triangle +# facet sets about closed polyhedra, for instance to compute interfacial +# excess related to phase boundaries of second-phase precipitates. +# +# Another example are free-standing triangle patches of the iso- +# surfaces which paraprobe creates. These could be characterized +# for interfacial excess. The sub-routines during iso-surface +# computations already include a procedure to automatically align +# local triangle normals based on the gradients of e.g. composition +# fields. In this case, these triangulated surface patches +# could also be used as a source for computing interfacial +# excess. +# +# Often scientists face situations, though, in which there is no +# immediately evident composition gradient across the interface +# (grain or phase boundary) and orientation information about the +# adjoining crystal is neither available nor reliable enough. +# +# In this case `P. Felfer et al. <https://doi.org/10.1016/j.ultramic.2015.06.002>`_ proposed a method +# to manually place control points and run an automated tessellation-based +# algorithm to create a triangulated surface patch, i.e. a model of the +# location of the interface. In a post-processing step this triangle +# set can then be used to compute again interfacial excess in an +# automated manner by placing ROIs and aligning them with +# consistently precomputed triangle normals. +# +# A similar use case is conceptually the one proposed by `X. Zhou et al. <https://doi.org/10.1016/j.actamat.2022.117633>`_ +# They used first a deep-learning method to locate planar triangulated +# grain boundary patches. These are eventually processed further +# with manual editing of the mesh via tools like Blender. +# Once the user is satisfied with the mesh, the computations of interfacial +# excess reduce again to an automated placing of ROIs, computations +# of the distributing of ions to respective ROIs and +# reporting the findings via plotting. +# +# Yet another approach for constructing an triangulated surface patch +# of an interface is to use point cloud processing methods which have +# been proposed in the laser-scanning, geoinformatics, and CAD community. +# Different computational geometry methods are available for fitting +# a parameterized surface to a set of points, using e.g. non-uniform +# rational B-splines (NURBS) and triangulating these according +# to prescribed mesh quality demands. +# +# The advantage of these methods is that they can be automated and +# pick up curved interface segments. The disadvantage is their often +# strong sensitivity to parameterization. As a result also such methods +# can be post-processed to yield a triangulated surface patch, +# and thus enable to run again automated ROI placement methods. +# For example like these which were explored for the use case of +# iso-surfaces with closed objects and free-standing +# surface patches that delineate regions of the dataset with a +# pronounced composition gradient normal to the interface. +# +# This summary of the situations which atom probers can face when +# requesting for interfacial excess computations, substantiates there +# exists a common set of settings which can describe all of these methods +# and, specifically, as here exemplified, the automated placing +# and alignment functionalities for ROIs that is an important +# step all these workflows. +# +# Specifically, paraprobe-nanochem operates on an already existent +# triangle set. +# +# +# +# +# +# +# +# +# +# The interface model is the result of a previous (set of) processing +# steps as a result of which the user has created a triangulated +# surface mesh (or a set of, eventually connected such meshes). +# These interface models are useful, if not required, in cases when +# there is no other independent approach to locate an interface. +# +# These are cases when insufficient crystallographic latent +# information is available and also no consistent concentration +# gradient detectable across the interface. It is then the users' +# responsibility to deliver a triangle mesh of the interface model. +# +# +# +# Filename to HDF5 file which contain vertex coordinates, facet indices, +# facet unit normals. The user is responsible for the triangle +# and winding order to be consistent. +# Input is expected as a matrix of the coordinates for all disjoint +# vertices, a (Nvertices, 3)-shaped array of NX_FLOAT. +# Input is expected to include also a matrix of facet indices +# referring to these disjoint vertices. This matrix should be a +# (Nfacets, 3)-shaped array of NX_UINT. Further required input +# is a (Nfacets, 3)-shaped array of NX_FLOAT signed facet unit +# normals and a (Nvertices, 3)-shaped array of NX_FLOAT signed +# vertex unit normals. Vertex indices need to start at zero and +# must not exceed Nvertices - 1, i.e. the identifier_offset is 0 +# and facet indices are indexed implicitly, i.e. [0, Nvertices-1]. +# +# +# +# Version identifier of the file such as a secure hash which +# documents the binary state of the file to add an additional +# layer of reproducibility from which file specifically +# contains these data. +# +# +# +# +# +# Absolute HDF5 path to the dataset which specifies the +# array of vertex positions. +# +# +# +# +# Absolute HDF5 path to the dataset which specifies the +# array of facet indices. +# +# +# +# +# Absolute HDF5 path to the dataset which specifies the +# array of facet signed unit normals. +# +# +# +# +# Absolute HDF5 path to the dataset which specifies the +# array of vertex signed unit normals. +# +# Users should be aware that triangulated surface meshes are +# only approximations to a given complex, eventually curved shape. +# Consequently, computations of normals show differences between +# the vertex and facet normals. Vertex normals have to be +# interpolated from normals of neighboring facets. Consequently, +# these normals are affected by the underlying parameterization +# and curvature estimation algorithms, irrespective of how +# contributions from neighboring facets are weighted. By contrast, +# facet normals are clearly defined by the associated triangle. +# Their disadvantage is that they the normal field has discontinuities +# at the edges. In general the coarser an object is triangulated +# the more significant the difference becomes between computations +# based on facet or vertex normals. +# Paraprobe-nanochem works with facet normals as it can use +# parts of the numerical performance gained by using cutting +# edge libraries to work rather with finer meshes. +# +# +# +# +# +# +# +# Create a simple principle component analysis (PCA) to mesh a +# free-standing interface patch through a point cloud of decorating solutes. +# These models can be useful for quantification of Gibbsian +# interfacial excess for interfaces where iso-surface based methods +# may fail or closed objects from iso-surfaces are not desired or +# when e.g. there are no substantial or consistently oriented +# concentration gradients across the interface patch. +# +# The interface_meshing functionality of paraprobe-nanochem can be useful +# when there is also insufficient latent crystallographic information +# available that could otherwise support modelling the interface, +# via e.g. ion density traces in field-desorption maps, as were used and +# discussed by `Y. Wei et al. <https://doi.org/10.1371/journal.pone.0225041>`_ +# or are discussed by `A. Breen et al. <https://github.com/breen-aj/detector>`_ +# +# It is noteworthy that the method here used is conceptually very similar +# in implementation to the work by `Z. Peng et al. <https://doi.org/10.1017/S1431927618016112>`_ +# Noteworthy, her team uses the DCOM approach originally proposed by P. Felfer et al. +# However, both of these previous works neither discuss in detail +# nor implement inspection functionalities which enable a detection of +# potential geometric inconsistencies or self-interactions of the +# resulting DCOM mesh. This is what paraprobe-nanochem implements +# via the Computational Geometry Algorithms Library. +# +# +# +# Method how to initialize the PCA: +# +# * default, means based on segregated solutes in the ROI +# * control_point_file, means based on reading an external list of +# control points, currently coming from the Leoben APT_Analyzer. +# +# The control_point_file is currently expected with a specific format. +# The Leoben group lead by L. Romaner has developed a GUI tool `A. Reichmann et al. <https://github.com/areichm/APT_analyzer>`_ +# to create a control_point_file which can be parsed by paraprobe-parmsetup +# to match the here required formatting in control_points. +# +# +# +# +# +# +# +# +# The name of the control point file to use. +# +# +# +# Version identifier of the file such as a secure hash which +# documents the binary state of the file to add an additional +# layer of reproducibility from which file specifically +# contains these data. +# +# +# +# +# +# X, Y, Z coordinates of disjoint control point read from +# an HDF5 file named according to control_point_file. +# +# +# +# +# +# +# +# +# +# Method used for identifying and refining the location of the +# interface. Currently, paraprobe-nanochem implements a PCA followed +# by an iterative loop of isotropic mesh refinement and DCOM step(s), +# paired with self-intersection detection in a more robust +# implementation. +# +# +# +# +# +# +# +# Specify the types of those ions which decorate the interface and +# can thus be assumed as markers for locating the interface and +# refining its local curvature. +# +# +# +# Array of iontypes to filter. The list is interpreted as a whitelist, +# i.e. ions of these types are considered the decorating species (solutes). +# +# +# +# +# +# +# +# +# How many times should the DCOM and mesh refinement be applied? +# +# +# +# +# Array of decreasing positive not smaller than one nanometer real values +# which specify how the initial triangles of the mesh should be iteratively +# refined by edge splitting and related mesh refinement operations. +# +# +# +# +# +# +# +# +# Array of decreasing positive not smaller than one nanometer real values +# which specify the radius of the spherical region of interest within +# which the DCOM algorithm decides for each vertex how the vertex will +# be eventually relocated. The larger the DCOM radius is relative to +# the target_edge_length the more likely it is that vertices will be +# relocated so substantially that eventually triangle self-intersections +# can occur. If the code detects these it warns and stops in a +# controlled manner so that the user can repeat the analyses +# with a smaller value. +# +# +# +# +# +# +# +# +# Array of integers which specify for each DCOM step how many times +# the mesh should be iteratively smoothened. +# +# Users should be aware the three array target_edge_length, +# target_dcom_radius, and target_smoothing_step are interpreted in the +# same sequence, i.e. the zeroth entry of each array specifies the +# values to be used in the first DCOM iteration. The first entry of +# each array those for the second DCOM iteration and so on and so forth. +# +# +# +# +# +# +# +# +# Functionalities for placing regions-of-interest (ROIs) in the dataset +# or at specific microstructural features to characterize composition +# profiles and cumulated profiles for quantification of interfacial excess. +# Paraprobe-nanochem currently places cylindrical ROIs. ROIs are probed +# across the triangulated surface of a user-defined mesh. +# ROIs are placed at the barycenter of the triangular facet. +# +# The tool can be instructed to orient the profile for each ROIs with +# the positive normal of the triangle facet normals. Profiles are +# computed for each ROI and facet triangle. The code will test which +# ROIs are completely embedded in the dataset. +# Specifically, in this test the tool evaluates if the ROI cuts at least +# one triangle of the triangulated surface mesh of the edge of the dataset. +# If this is the case the ROI will be considered close to the edge +# (of the dataset) and not analyzed further; else the ROI will be +# processed further. +# Users should be aware that the latter intersection analysis is strictly +# speaking not a volumetric intersection analysis as such one is much +# more involved because the edge model can be a closed non-convex polyhedron +# in which case one would have to test robustly if the cylinder pierces +# or is laying completely inside the polyhedron. For this the polyhedron has +# to be tessellated into convex polyhedra as otherwise tests like the +# Gilbert-Johnson-Keerthi algorithm would not be applicable. +# +# Specifically, the tool computes atomically decomposed profiles. +# This means molecular ions are split into atoms/isotopes with respective +# multiplicity. As an example an H3O+ molecular ion contains three +# hydrogen and one oxygen atom respectively. The tool then evaluates +# how many ions are located inside the ROI or on the surface of the +# ROI respectively. All atom types and the unranged ions are distinguished. +# As a result, the analyses yield for each ROI a set of sorted lists of +# signed distance values. Currently, the distance is the projected +# distance of the ion position to the barycenter of the triangle +# and triangle plane. +# +# This will return a one-dimensional profile. Post-processing the set +# of atom-type-specific profiles into cumulated profiles enable the +# classical Krakauer/Seidman-style interfacial excess analyses. +# Furthermore, the tool can be instructed to compute for each +# (or a selected sub-set of facet) a set of differently oriented profiles. +# +# +# +# +# The feature mesh enables the injection of previously computed triangle +# soup or mesh data. Such a mesh can be the model for a grain- or phase +# boundary patch (from e.g. interface_meshing) jobs. +# +# +# +# Name of the HDF5 file which contains vertex coordinates and facet +# indices to describe the desired set of triangles which represents +# the feature. +# +# +# +# Version identifier of the file such as a secure hash which documents +# the binary state of the file to add an additional layer of +# reproducibility from which file specifically contains these data. +# +# +# +# +# +# Absolute path to the HDF5 dataset in the respectively specified HDF5 +# file under filename which details the array of vertex positions. +# +# +# +# +# Absolute path to the HDF5 dataset in the respective specified HDF5 +# file under filename which details the array of facet indices. +# +# +# +# +# Absolute path to the HDF5 dataset in the respective specified HDF5 +# file under filename which details consistently oriented facet +# normals of the facets. +# +# +# +# +# +# +# +# +# +# +# The tool enables to inject precomputed distance information for each +# point which can be used for further post-processing and analysis. +# +# +# +# +# Name of an HDF5 file which contains ion distances. +# +# +# +# Version identifier of the file such as a secure hash which +# documents the binary state of the file to add an additional +# layer of reproducibility from which file specifically contains +# these data. +# +# +# +# +# +# Absolute HDF5 path to the dataset with distance values for each ion. +# +# +# +# +# +# Which type of distance should be reported for the profile. +# +# +# +# +# +# +# +# +# In which directions should the tool probe for each ROI. +# +# +# +# +# +# +# +# +# For each ROI, how high (projected on the cylinder axis) +# should the cylindrical ROI be. +# +# +# +# +# +# For each ROI, how wide (radius) should the cylindrical ROI be. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_ranger.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_ranger.yaml new file mode 100644 index 0000000000..cbc879b5c8 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_ranger.yaml @@ -0,0 +1,531 @@ +category: application +doc: | + Configuration of a paraprobe-ranger tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_isotopes: | + The number of isotopes to consider as building blocks for searching molecular + ions. + n_composition: | + The number of compositions to consider for molecular ion search tasks. +type: group +NXapm_paraprobe_config_ranger(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_ranger] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many task to perform? + (NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + apply_existent_ranging(NXprocess): + exists: ['min', '0', 'max', '1'] + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + hit_multiplicity_filter(NXmatch_filter): + exists: optional + molecular_ion_search(NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + assumed_composition_isotopes(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + A list of pairs of number of protons and either the value 0 (per row) + or the mass number for all those isotopes which are assumed present + in a virtual specimen. + The purpose of this field is to compute also composition-weighted + products to yield a simple estimation which could potentially help + scientists to judge if certain molecular ions are to be expected. + The corresponding setting store_composition_weighted_product should be + activated. + dimensions: + rank: 2 + dim: [[1, n_composition], [2, 2]] + + # assumed_composition_value(NX_FLOAT): + # doc: | + # A list of atomic (at.-%) ! percent values for the composition of each + # isotope in the virtual specimen following the sequence of + # assumed_composition_isotopes. + # unit: NX_DIMENSIONLESS + # dimensions: + # rank: 1 + # dim: [[1, n_compositions]] + isotope_whitelist(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of pairs of number of protons and mass number for all isotopes + to consider that can be composed into (molecular) ions, during the + recursive molecular_ion_search. + dimensions: + rank: 2 + dim: [[1, n_isotopes], [2, 2]] + mass_to_charge_interval(NX_FLOAT): + unit: NX_ANY + doc: | + The mass-to-charge-state ratio interval in which + all molecular ions are searched. + dimensions: + rank: 1 + dim: [[1, 2]] + maximum_charge(NX_UINT): + unit: NX_UNITLESS + doc: | + The maximum charge that a molecular ion should have. + maximum_number_of_isotopes(NX_UINT): + unit: NX_UNITLESS + doc: | + The maximum number of isotopes of which the molecular ion + should be composed. Currently this must not be larger than 32. + + Users should be warned that the larger the maximum_charge and + especially the larger the maximum_number_of_isotopes is chosen, + the eventually orders of magnitude more costly the search becomes. + + This is because paraprobe-ranger computes really all (at least) + theoretically possible combinations that would have likely a + mass-to-charge-state ratio in the specified mass_to_charge_interval. + It is the challenge in atom probe to judge which of these (molecular) + ions are feasible and also practically possible. This tool does not + answer this question. + + Namely, which specific molecular ion will evaporate, remain stable + during flight and becomes detected is a complicated and in many cases + not yet in detail understood phenomenon. The ab-initio conditions + before and during launch, the local environment, arrangement and field + as well as the flight phase in an evacuated but not analysis chamber + with a complex electrical field, eventual laser pulsing in place, + temperature and remaining atoms or molecules all can have an effect + which iontypes are really physically evaporating and detected. + store_atomic_mass_sum(NX_BOOLEAN): + doc: | + Report the accumulated atomic mass from each isotope building the ion. + Accounts for each identified ion. + Relatistic effects are not accounted for. + store_natural_abundance_product(NX_BOOLEAN): + doc: | + Report the product of the natural abundances from each isotope building + the ion. Accounts for each identified ion. + + The value zero indicates it is not possible to build such molecular ion + from nuclids which are all observationally stable. + Very small values can give an idea/about how likely such a molecular ion + is expected to form assuming equal probabilities. + + However in atom probe experiments this product has to be modified + by the (spatially-correlated) local composition in the region from + which the ions launch because the formation of a molecular ion depends + as summarized under maximum_number_of_isotopes on the specific + quantum-mechanical configuration and field state upon launch + or/and (early state) of flight respectively. + We are aware that this modified product can have a substantially + different value than the natural_abundance_product. + + Natural abundancies folded with the estimated compositions of the + specimen can differ by orders of magnitude. + + # add assumed composition of the specimen + # store_composition_weighted_product(NX_BOOLEAN): + # doc: | + # Report the product of the composition from each isotope building the + # ion. This sets strong constraints on the molecular ions which are + # expected to have at all a noteworthy product value. + # It should not be forgotten though the computation relies on assumptions: + # * The composition is homogeneous within the virtual specimen. + # * It is a priori know which nuclids the specimen is build of. + store_charge_state(NX_BOOLEAN): + doc: | + Report the charge state of the ions. + store_disjoint_isotopes(NX_BOOLEAN): + doc: | + Report if identified ions should be characterized + wrt to their number of disjoint isotopes. + check_existent_ranging(NXprocess): + exists: ['min', '0', 'max', '1'] + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e680aa3be81d3132fa6dbff9ae4d44ae7ca8a610b8660af51c3b67c207961ea0 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The number of isotopes to consider as building blocks for searching molecular +# ions. +# +# +# +# +# The number of compositions to consider for molecular ion search tasks. +# +# +# +# +# Configuration of a paraprobe-ranger tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# How many task to perform? +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A list of pairs of number of protons and either the value 0 (per row) +# or the mass number for all those isotopes which are assumed present +# in a virtual specimen. +# The purpose of this field is to compute also composition-weighted +# products to yield a simple estimation which could potentially help +# scientists to judge if certain molecular ions are to be expected. +# The corresponding setting store_composition_weighted_product should be +# activated. +# +# +# +# +# +# +# +# +# +# A list of pairs of number of protons and mass number for all isotopes +# to consider that can be composed into (molecular) ions, during the +# recursive molecular_ion_search. +# +# +# +# +# +# +# +# +# The mass-to-charge-state ratio interval in which +# all molecular ions are searched. +# +# +# +# +# +# +# +# The maximum charge that a molecular ion should have. +# +# +# +# +# The maximum number of isotopes of which the molecular ion +# should be composed. Currently this must not be larger than 32. +# +# Users should be warned that the larger the maximum_charge and +# especially the larger the maximum_number_of_isotopes is chosen, +# the eventually orders of magnitude more costly the search becomes. +# +# This is because paraprobe-ranger computes really all (at least) +# theoretically possible combinations that would have likely a +# mass-to-charge-state ratio in the specified mass_to_charge_interval. +# It is the challenge in atom probe to judge which of these (molecular) +# ions are feasible and also practically possible. This tool does not +# answer this question. +# +# Namely, which specific molecular ion will evaporate, remain stable +# during flight and becomes detected is a complicated and in many cases +# not yet in detail understood phenomenon. The ab-initio conditions +# before and during launch, the local environment, arrangement and field +# as well as the flight phase in an evacuated but not analysis chamber +# with a complex electrical field, eventual laser pulsing in place, +# temperature and remaining atoms or molecules all can have an effect +# which iontypes are really physically evaporating and detected. +# +# +# +# +# Report the accumulated atomic mass from each isotope building the ion. +# Accounts for each identified ion. +# Relatistic effects are not accounted for. +# +# +# +# +# Report the product of the natural abundances from each isotope building +# the ion. Accounts for each identified ion. +# +# The value zero indicates it is not possible to build such molecular ion +# from nuclids which are all observationally stable. +# Very small values can give an idea/about how likely such a molecular ion +# is expected to form assuming equal probabilities. +# +# However in atom probe experiments this product has to be modified +# by the (spatially-correlated) local composition in the region from +# which the ions launch because the formation of a molecular ion depends +# as summarized under maximum_number_of_isotopes on the specific +# quantum-mechanical configuration and field state upon launch +# or/and (early state) of flight respectively. +# We are aware that this modified product can have a substantially +# different value than the natural_abundance_product. +# +# Natural abundancies folded with the estimated compositions of the +# specimen can differ by orders of magnitude. +# +# +# +# +# +# Report the charge state of the ions. +# +# +# +# +# Report if identified ions should be characterized +# wrt to their number of disjoint isotopes. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_selector.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_selector.yaml new file mode 100644 index 0000000000..d5c9ac4ed4 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_selector.yaml @@ -0,0 +1,240 @@ +category: application +doc: | + Configuration of a paraprobe-selector tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXapm_paraprobe_config_selector(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_selector] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many roi_selection processes should the tool execute. + roi_selection(NXprocess): + exists: ['min', '1', 'max', '1'] + doc: | + This process identifies which of the points/ions in the datasets are + inside or on the surface of geometric primitives and meet optionally + specific other filtering constraints. + A typical use case of a roi_selection is to restrict analyses to + specific regions of the dataset, eventually regions with a complicated + shape. + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + cardinality(NX_POSINT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + + # orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + cardinality(NX_POSINT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + cardinality(NX_POSINT): + hexahedra(NXcg_face_list_data_structure): + vertices(NX_FLOAT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + linear_range_min_incr_max(NX_UINT): + iontype_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + hit_multiplicity_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a75891867e7d1bca2385b3439e5cdca146d2036d6ee76fb381c3fac3f0579ecf +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Configuration of a paraprobe-selector tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# How many roi_selection processes should the tool execute. +# +# +# +# +# This process identifies which of the points/ions in the datasets are +# inside or on the surface of geometric primitives and meet optionally +# specific other filtering constraints. +# A typical use case of a roi_selection is to restrict analyses to +# specific regions of the dataset, eventually regions with a complicated +# shape. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_spatstat.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_spatstat.yaml new file mode 100644 index 0000000000..9bcba92551 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_spatstat.yaml @@ -0,0 +1,662 @@ +category: application +doc: | + Configuration of a paraprobe-spatstat tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ivecmax: | + Maximum number of atoms per molecular ion. Should be 32 for paraprobe. + n_ion_source: | + Number of different sources iontypes to distinguish. + n_ion_target: | + Number of different target iontypes to distinguish. +type: group +NXapm_paraprobe_config_spatstat(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_spatstat] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many range_with_existent_iontypes processes should + the tool execute as part of the analysis. + (NXprocess): + exists: ['min', '1', 'max', '1'] + spatial_statistics(NXprocess): + exists: ['min', '0', 'max', '1'] + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + hit_multiplicity_filter(NXmatch_filter): + exists: optional + ion_to_edge_distances(NXprocess): + exists: optional + doc: | + The tool enables to inject precomputed distances of each ion to a + representation of the edge of the dataset which can be used to + control and substantially reduce edge effects when computing + spatial statistics. + filename: + doc: | + Name of an HDF5 file which contains ion-to-edge distances. + dataset_name_distances: + doc: | + Absolute HDF5 path to the dataset with the + ion-to-edge distance values for each ion. + The shape of the distance values has to match the length + of the ion positions array in dataset/dataset_name_reconstruction + and dataset_name_mass_to_charge respectively. + edge_distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Threshold to define how large an ion has to lay at least far away + from the edge of the dataset so that the ion can act as a source, + i.e. that an ROI is placed at the location of the ion and its + neighbors are analyzed how they contribute to the computed statistics. + + The ion_to_edge_distances threshold can be combined with a threshold + for the ion_to_feature_distances. + Specifically, if ion_to_feature_distances are loaded an ion only + acts as a source if both threshold criteria are met. + + The threshold is useful to process the dataset such that ROIs do + not protrude out of the dataset as this would add bias. + ion_to_feature_distances(NXprocess): + exists: optional + doc: | + In addition to spatial filtering, and considering how far ions lie + to the edge of the dataset, it is possible to restrict the analyses + to a sub-set of ions within a distance not farther away to a feature than + a threshold value. + filename: + doc: | + Name of an HDF5 file which contains ion-to-feature distances. + dataset_name_distances: + doc: | + Absolute HDF5 path to the dataset with the + ion-to-feature distance values for each ion. + threshold(NX_FLOAT): + unit: NX_LENGTH + doc: | + Threshold to define how close an ion has to lay to a feature so that + the ion can at all qualify as a source, i.e. that an ROI is placed + at the location of the ion and its neighbors are then analyzed + how they contribute to the computed statistics. + + Recall that the ion_to_feature_distances threshold is combined + with the ion_to_edge_distances threshold. + + ##MK::think about an inversion ruleset for the filter, i.e. + # like discussed in Haley/Stephenson's paper where ions only far enough + # from a feature AND deeply embedded enough in the dataset are chosen. + randomize_ion_types(NX_BOOLEAN): + doc: | + Specifies if the iontypes are randomized for the point cloud or not. + Internally paraprobe uses a sequentially executed deterministic MT19987 + (MersenneTwister) pseudo-random number generator to shuffle the + iontype labels randomly across the entire set of ions. + random_number_generator(NXcs_prng): + exists: recommended + type: + seed(NX_NUMBER): + warmup(NX_NUMBER): + ion_query_type_source: + doc: | + How should the iontype be interpreted on the source-side, i.e. + all these ion positions where a regions-of-interest (ROI) around + so-called source ions will be placed. Different options exist + how iontypes are interpreted given an iontype represents + in general a (molecular) ion with different isotopes that have + individually different multiplicity. + + The value resolve_all will set an ion active in the analysis regardless + of which iontype it is. Each active ion is accounted for once. + + The value resolve_unknown will set an ion active when the ion is + of the UNKNOWNTYPE type. Each active ion is accounted for once. + + The value resolve_ion will set an ion active if it is of the specific + iontype, irregardless of its elemental or isotopic details. + Each active ion is counted once. + + The value resolve_element will set an ion active, and most importantly, + account for each as many times as the (molecular) ion contains + atoms of elements in the whitelist ion_query_isotope_vector. + + The value resolve_isotope will set an ion active, and most importantly, + account for each as many times as the (molecular) ion contains + isotopes in the whitelist ion_query_isotope_vector. + + In effect, ion_query_isotope_vector acts as a whitelist to filter + which ions are considered as source ions of the correlation statistics + and how the multiplicity of each ion will be factorized, i.e. how + often it is accounted for. + enumeration: [resolve_all, resolve_unknown, resolve_ion, resolve_element, resolve_isotope] + ion_query_isotope_vector_source(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of isotope vectors, as many as rows as different candidates + for iontypes should be distinguished as possible source iontypes. + In the simplest case, the matrix contains only the proton number + of the element in the row, all other values set to zero. + Combined with ion_query_type_source set to resolve_element this will + recover usual spatial correlation statistics like the 1NN C-C + spatial statistics. + dimensions: + rank: 2 + dim: [[1, n_ion_source], [2, n_ivecmax]] + ion_query_type_target: + doc: | + Similarly as ion_query_type_source how should iontypes be interpreted + on the target-side, i.e. how many counts will be bookkept for ions + which are neighbors of source ions within or on the surface of each + inspection/ROI about each source ion. + Source ion in the center of the ROI are not accounted for during + counting the summary statistics. + For details about the resolve values consider the explanations in + ion_query_type_source. These account for ion_query_type_target as well. + enumeration: [resolve_all, resolve_unknown, resolve_ion, resolve_element, resolve_isotope] + + # NEW ISSUE: conditionally required only when resolve_isotope + ion_query_isotope_vector_target(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of isotope vectors, as many as rows as different candidates for + iontypes to distinguish as possible targets. See additional comments + under ion_query_isotope_vector_source. + dimensions: + rank: 2 + dim: [[1, n_ion_target], [2, n_ivecmax]] + statistics(NXprocess): + doc: | + Specifies which spatial statistics to compute. + knn(NXprocess): + exists: optional + doc: | + Compute k-th nearest neighbour statistics. + nth(NX_UINT): + unit: NX_UNITLESS + doc: | + Order k. + histogram_min_incr_max(NX_FLOAT): + unit: NX_LENGTH + doc: | + Minimum value, increment, and maximum value of the histogram binning. + + # \@units: nm + dimensions: + rank: 1 + dim: [[1, 3]] + rdf(NXprocess): + exists: optional + doc: | + Compute radial distribution function. + histogram_min_incr_max(NX_FLOAT): + unit: NX_LENGTH + doc: | + Minimum value, increment, and maximum value of the histogram binning. + + # \@units: nm + dimensions: + rank: 1 + dim: [[1, 3]] + + # NEW ISSUE: ripleyk(NXcollection): + # NEW ISSUE: two_point(NXcollection): + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 58f42334f6d43a13494f1bd0adfd0cac7d533a84f47f47fdd0ba75026a098e1b +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Maximum number of atoms per molecular ion. Should be 32 for paraprobe. +# +# +# +# +# Number of different sources iontypes to distinguish. +# +# +# +# +# Number of different target iontypes to distinguish. +# +# +# +# +# Configuration of a paraprobe-spatstat tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# How many range_with_existent_iontypes processes should +# the tool execute as part of the analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The tool enables to inject precomputed distances of each ion to a +# representation of the edge of the dataset which can be used to +# control and substantially reduce edge effects when computing +# spatial statistics. +# +# +# +# Name of an HDF5 file which contains ion-to-edge distances. +# +# +# +# +# Absolute HDF5 path to the dataset with the +# ion-to-edge distance values for each ion. +# The shape of the distance values has to match the length +# of the ion positions array in dataset/dataset_name_reconstruction +# and dataset_name_mass_to_charge respectively. +# +# +# +# +# Threshold to define how large an ion has to lay at least far away +# from the edge of the dataset so that the ion can act as a source, +# i.e. that an ROI is placed at the location of the ion and its +# neighbors are analyzed how they contribute to the computed statistics. +# +# The ion_to_edge_distances threshold can be combined with a threshold +# for the ion_to_feature_distances. +# Specifically, if ion_to_feature_distances are loaded an ion only +# acts as a source if both threshold criteria are met. +# +# The threshold is useful to process the dataset such that ROIs do +# not protrude out of the dataset as this would add bias. +# +# +# +# +# +# In addition to spatial filtering, and considering how far ions lie +# to the edge of the dataset, it is possible to restrict the analyses +# to a sub-set of ions within a distance not farther away to a feature than +# a threshold value. +# +# +# +# Name of an HDF5 file which contains ion-to-feature distances. +# +# +# +# +# Absolute HDF5 path to the dataset with the +# ion-to-feature distance values for each ion. +# +# +# +# +# Threshold to define how close an ion has to lay to a feature so that +# the ion can at all qualify as a source, i.e. that an ROI is placed +# at the location of the ion and its neighbors are then analyzed +# how they contribute to the computed statistics. +# +# Recall that the ion_to_feature_distances threshold is combined +# with the ion_to_edge_distances threshold. +# +# +# +# +# +# +# Specifies if the iontypes are randomized for the point cloud or not. +# Internally paraprobe uses a sequentially executed deterministic MT19987 +# (MersenneTwister) pseudo-random number generator to shuffle the +# iontype labels randomly across the entire set of ions. +# +# +# +# +# +# +# +# +# +# How should the iontype be interpreted on the source-side, i.e. +# all these ion positions where a regions-of-interest (ROI) around +# so-called source ions will be placed. Different options exist +# how iontypes are interpreted given an iontype represents +# in general a (molecular) ion with different isotopes that have +# individually different multiplicity. +# +# The value resolve_all will set an ion active in the analysis regardless +# of which iontype it is. Each active ion is accounted for once. +# +# The value resolve_unknown will set an ion active when the ion is +# of the UNKNOWNTYPE type. Each active ion is accounted for once. +# +# The value resolve_ion will set an ion active if it is of the specific +# iontype, irregardless of its elemental or isotopic details. +# Each active ion is counted once. +# +# The value resolve_element will set an ion active, and most importantly, +# account for each as many times as the (molecular) ion contains +# atoms of elements in the whitelist ion_query_isotope_vector. +# +# The value resolve_isotope will set an ion active, and most importantly, +# account for each as many times as the (molecular) ion contains +# isotopes in the whitelist ion_query_isotope_vector. +# +# In effect, ion_query_isotope_vector acts as a whitelist to filter +# which ions are considered as source ions of the correlation statistics +# and how the multiplicity of each ion will be factorized, i.e. how +# often it is accounted for. +# +# +# +# +# +# +# +# +# +# +# +# Matrix of isotope vectors, as many as rows as different candidates +# for iontypes should be distinguished as possible source iontypes. +# In the simplest case, the matrix contains only the proton number +# of the element in the row, all other values set to zero. +# Combined with ion_query_type_source set to resolve_element this will +# recover usual spatial correlation statistics like the 1NN C-C +# spatial statistics. +# +# +# +# +# +# +# +# +# Similarly as ion_query_type_source how should iontypes be interpreted +# on the target-side, i.e. how many counts will be bookkept for ions +# which are neighbors of source ions within or on the surface of each +# inspection/ROI about each source ion. +# Source ion in the center of the ROI are not accounted for during +# counting the summary statistics. +# For details about the resolve values consider the explanations in +# ion_query_type_source. These account for ion_query_type_target as well. +# +# +# +# +# +# +# +# +# +# +# +# +# Matrix of isotope vectors, as many as rows as different candidates for +# iontypes to distinguish as possible targets. See additional comments +# under ion_query_isotope_vector_source. +# +# +# +# +# +# +# +# +# Specifies which spatial statistics to compute. +# +# +# +# Compute k-th nearest neighbour statistics. +# +# +# +# Order k. +# +# +# +# +# Minimum value, increment, and maximum value of the histogram binning. +# +# +# +# +# +# +# +# +# +# Compute radial distribution function. +# +# +# +# Minimum value, increment, and maximum value of the histogram binning. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_surfacer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_surfacer.yaml new file mode 100644 index 0000000000..16c2e5a93b --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_surfacer.yaml @@ -0,0 +1,509 @@ +category: application +doc: | + Configuration of a paraprobe-surfacer tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_alpha_values: | + Number of alpha values (and offset values) to probe. + n_values: | + How many different match values does the filter specify. +type: group +NXapm_paraprobe_config_surfacer(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_surfacer] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + For now a support field for the tool to identify how many individual + analyses the tool should executed as part of the analysis. + (NXprocess): + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + + ##MK::ion_id_filter(NXcs_filter_boolean_mask): + evaporation_id_filter(NXsubsampling_filter): + exists: optional + linear_range_min_incr_max(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, 3]] + iontype_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, n_values]] + hit_multiplicity_filter(NXmatch_filter): + exists: optional + method: + match(NX_NUMBER): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, n_values]] + surface_meshing(NXprocess): + preprocessing_method: + doc: | + Specifies the method that is used to preprocess the point cloud. + The main purpose of this setting is to specify whether the point + cloud should be segmented or not during the preprocessing + to identify which points are more likely lying close to the edge + of the point cloud. These points could be more relevant than the + interior points for certain alpha-shape constructions. + + By default no such filtering is used during pre-processing. + By contrast, the option kuehbach activates a preprocessing + during which a Hoshen-Kopelman percolation analysis is used + to identify which points are closer to the edge of the dataset. + This can reduce the number of points in the alpha-shape + computation and thus improve performance substantially. + Details about the methods are reported in + `M. Kühbach et al. `_. + enumeration: [default, kuehbach] + preprocessing_kernel_width(NX_UINT): + unit: NX_UNITLESS + + # the exists is dependant on the value for preprocessing_method + doc: | + When using the kuehbach preprocessing, this is the width of the + kernel for identifying which ions are in voxels close to the + edge of the point cloud. + alpha_value_choice: + doc: | + Specifies which method to use to define the alpha value. + The value convex_hull_naive is the default. This instructs the tool + to use a fast specialized algorithm for computing only the convex + hull. The resulting triangles can be skinny. + + The value convex_hull_refine computes first also a convex_hull_naive + but refines the mesh by triangle flipping and splitting to improve + the quality of the mesh. + + The value smallest_solid instructs the CGAL library to choose a + value which realizes an alpha-shape that is the smallest solid. + + The value cgal_optimal instructs the library to choose a value + which the library considers as an optimal value. Details are + define in the respective section of the CGAL library on 3D alpha + shapes. + + The value set_of_values instructs to compute a list of + alpha-shapes for the specified alpha-values. + + The value set_of_alpha_wrappings instructs the library to generate + a set of so-called alpha wrappings. These are a method + which is similar to alpha shapes but provide additional guarantees + though such as watertightness and proximity constraints on the + resulting wrapping. + + # NEW ISSUE: further details CGAL documentation + enumeration: [convex_hull_naive, convex_hull_refine, smallest_solid, cgal_optimal, set_of_values, set_of_alpha_wrappings] + alpha_values(NX_FLOAT): + unit: NX_ANY + doc: | + Array of alpha values to use when alpha_value_choice is set_of_values + or when alpha_value_choice is set_of_alpha_wrappings. + + # \@units: nm^2 + dimensions: + rank: 1 + dim: [[1, n_alpha_values]] + offset_values(NX_FLOAT): + unit: NX_LENGTH + doc: | + Array of offset values to use when alpha_value_choice is + set_of_alpha_wrappings. The array of alpha_values and offset_values + define a sequence of (alpha and offset value). + + # \@units: nm + dimensions: + rank: 1 + dim: [[1, n_alpha_values]] + has_exterior_facets(NX_BOOLEAN): + doc: | + Specifies if the tool should compute the set of exterior triangle + facets for each alpha complex (for convex hull, alpha shapes, and wrappings) + has_closure(NX_BOOLEAN): + doc: | + Specifies if the tool should check if the alpha complex of exterior + triangular facets is a closed polyhedron. + has_interior_tetrahedra(NX_BOOLEAN): + doc: | + Specifies if the tool should compute all interior tetrahedra + of the alpha complex (currently only for alpha shapes). + + # NEW ISSUE: has_facet_appearance(NX_BOOLEAN): + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5a9a515d28f8231740dc213b3a0aa41a35e3121275b016be1d7065eb8c0429ec +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of alpha values (and offset values) to probe. +# +# +# +# +# How many different match values does the filter specify. +# +# +# +# +# Configuration of a paraprobe-surfacer tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# For now a support field for the tool to identify how many individual +# analyses the tool should executed as part of the analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specifies the method that is used to preprocess the point cloud. +# The main purpose of this setting is to specify whether the point +# cloud should be segmented or not during the preprocessing +# to identify which points are more likely lying close to the edge +# of the point cloud. These points could be more relevant than the +# interior points for certain alpha-shape constructions. +# +# By default no such filtering is used during pre-processing. +# By contrast, the option kuehbach activates a preprocessing +# during which a Hoshen-Kopelman percolation analysis is used +# to identify which points are closer to the edge of the dataset. +# This can reduce the number of points in the alpha-shape +# computation and thus improve performance substantially. +# Details about the methods are reported in +# `M. Kühbach et al. <https://doi.org/10.1038/s41524-020-00486-1>`_. +# +# +# +# +# +# +# +# +# +# When using the kuehbach preprocessing, this is the width of the +# kernel for identifying which ions are in voxels close to the +# edge of the point cloud. +# +# +# +# +# Specifies which method to use to define the alpha value. +# The value convex_hull_naive is the default. This instructs the tool +# to use a fast specialized algorithm for computing only the convex +# hull. The resulting triangles can be skinny. +# +# The value convex_hull_refine computes first also a convex_hull_naive +# but refines the mesh by triangle flipping and splitting to improve +# the quality of the mesh. +# +# The value smallest_solid instructs the CGAL library to choose a +# value which realizes an alpha-shape that is the smallest solid. +# +# The value cgal_optimal instructs the library to choose a value +# which the library considers as an optimal value. Details are +# define in the respective section of the CGAL library on 3D alpha +# shapes. +# +# The value set_of_values instructs to compute a list of +# alpha-shapes for the specified alpha-values. +# +# The value set_of_alpha_wrappings instructs the library to generate +# a set of so-called alpha wrappings. These are a method +# which is similar to alpha shapes but provide additional guarantees +# though such as watertightness and proximity constraints on the +# resulting wrapping. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of alpha values to use when alpha_value_choice is set_of_values +# or when alpha_value_choice is set_of_alpha_wrappings. +# +# +# +# +# +# +# +# +# Array of offset values to use when alpha_value_choice is +# set_of_alpha_wrappings. The array of alpha_values and offset_values +# define a sequence of (alpha and offset value). +# +# +# +# +# +# +# +# +# Specifies if the tool should compute the set of exterior triangle +# facets for each alpha complex (for convex hull, alpha shapes, and wrappings) +# +# +# +# +# Specifies if the tool should check if the alpha complex of exterior +# triangular facets is a closed polyhedron. +# +# +# +# +# Specifies if the tool should compute all interior tetrahedra +# of the alpha complex (currently only for alpha shapes). +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_tessellator.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_tessellator.yaml new file mode 100644 index 0000000000..659f5f1894 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_tessellator.yaml @@ -0,0 +1,449 @@ +category: application +doc: | + Configuration of a paraprobe-tessellator tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + +# n_control_points: The number of control points for tessellating regions instead of tessellating the volume about ion positions. +type: group +NXapm_paraprobe_config_tessellator(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_tessellator] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + number_of_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + How many individual analyses should the tool execute. + (NXprocess): + dataset(NXapm_input_reconstruction): + filename: + \@version: + dataset_name_reconstruction: + dataset_name_mass_to_charge: + iontypes(NXapm_input_ranging): + filename: + \@version: + group_name_iontypes: + spatial_filter(NXspatial_filter): + exists: optional + windowing_method: + (NXcg_ellipsoid_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + half_axes_radii(NX_NUMBER): + orientation(NX_NUMBER): + (NXcg_cylinder_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + center(NX_NUMBER): + height(NX_NUMBER): + radii(NX_NUMBER): + (NXcg_hexahedron_set): + exists: optional + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + identifier_offset(NX_INT): + hexahedra(NXcg_face_list_data_structure): + (NXcs_filter_boolean_mask): + exists: optional + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + identifier(NX_UINT): + + # a perfect example for limited conditions in NeXus + # if windowing_method is entire_dataset: no constraint on existence of NXcg and NXcs instances + # if windowing_method is union_of_primitives: sum of cardinality of NXcg >= 0 + # if windowing_method is bitmasked_points: sum cardinality of NXcg := 0 and cardinality of NXcs_filter_boolean_mask == 1 + evaporation_id_filter(NXsubsampling_filter): + exists: optional + iontype_filter(NXmatch_filter): + exists: optional + hit_multiplicity_filter(NXmatch_filter): + exists: optional + ion_to_edge_distances(NXprocess): + exists: optional + doc: | + The tool enables to inject precomputed distance information for + each point which can be used for further post-processing and analysis. + filename: + doc: | + Name of an HDF5 file which contains the ion distances. + Users are responsible this file and referred to dataset under + dataset_name have an ion_distance value for each ion. + \@version: + doc: | + Version identifier of the file such as a secure hash which + documents the binary state of the file to add an additional layer of + reproducibility. + dataset_name: + doc: | + Absolute HDF5 path to the dataset with distance values for each ion. + tessellating(NXprocess): + method: + doc: | + Specifies for which points the tool will compute the tessellation. + By default, a Voronoi tessellation is computed for all ions in the + filtered point cloud. + + # The value control_points will compute the tessellation for the + # provided overlay_control_points irregardless of the ion point cloud. + # This enables for instance computations as proposed by P. Felfer and + # coworkers where, for the purpose of e.g. interfacial excess quantification, + # a tessellation of the dataset into regions about manually-specified + # control points is needed. + # For this option, the overlay_control points. + enumeration: [default] + + # overlay_control_points(NXprocess): + # doc: | + # Overlaying an additional set of control points onto the reconstruction + # can be used as a first step to construct a tessellation of the dataset + # into regions to segment the dataset or construct a model for internal + # structural features in the dataset. Such an approach was suggested + # e.g. by P. Felfer et al. which use a control points to locate + # interfaces (grain/phase boundaries) in atom probe data to perform + # e.g. interfacial excess computations. The control points can be + # imported for example from some manual preprocessing of a dataset + # where the user figured these control points could be of relevance + # for the analysis. + # NEW ISSUE: dislocation lines + # exists: optional + # filename: + # doc: | + # Name of an HDF5 file which contains control point coordinates. + # \@version: + # doc: | + # Version identifier of the file such as a secure hash which + # documents the binary state of the file to add an additional + # layer of reproducibility. + # dataset_name: + # doc: | + # Absolute HDF5 path to the dataset which contains the array of + # control points. This has to be an array of shape + # (n_control_points, 3). + has_cell_volume(NX_BOOLEAN): + doc: | + Specifies if the tool should report the volume of each cell. + has_cell_neighbors(NX_BOOLEAN): + doc: | + Specifies if the tool should report the first-order neighbors of each cell. + has_cell_geometry(NX_BOOLEAN): + doc: | + Specifies if the tool should report the facets and vertices of each cell. + has_cell_edge_detection(NX_BOOLEAN): + doc: | + Specifies if the tool should report if the cell makes contact with + the tight axis-aligned bounding box about the point cloud. + This can be used to identify if the shape of the cell is affected + by the edge of the dataset or if cells are deeply enough embedded + into the point cloud so that the shape of their cells are not affected + by the presence of the boundary. + + # erosion_distance(NX_FLOAT): + # doc: | + # Maximum distance for which cells are eroded. + # unit: NX_LENGTH + # \@units: nm + # minValue: EPSILON + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7865be535bda4bc76ce207bee2d62dff19d30dcf9c5bb661e5eb5304b271cdfa +# +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Configuration of a paraprobe-tessellator tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# How many individual analyses should the tool execute. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The tool enables to inject precomputed distance information for +# each point which can be used for further post-processing and analysis. +# +# +# +# Name of an HDF5 file which contains the ion distances. +# Users are responsible this file and referred to dataset under +# dataset_name have an ion_distance value for each ion. +# +# +# +# Version identifier of the file such as a secure hash which +# documents the binary state of the file to add an additional layer of +# reproducibility. +# +# +# +# +# +# Absolute HDF5 path to the dataset with distance values for each ion. +# +# +# +# +# +# +# Specifies for which points the tool will compute the tessellation. +# By default, a Voronoi tessellation is computed for all ions in the +# filtered point cloud. +# +# +# +# +# +# +# +# +# +# Specifies if the tool should report the volume of each cell. +# +# +# +# +# Specifies if the tool should report the first-order neighbors of each cell. +# +# +# +# +# Specifies if the tool should report the facets and vertices of each cell. +# +# +# +# +# Specifies if the tool should report if the cell makes contact with +# the tight axis-aligned bounding box about the point cloud. +# This can be used to identify if the shape of the cell is affected +# by the edge of the dataset or if cells are deeply enough embedded +# into the point cloud so that the shape of their cells are not affected +# by the presence of the boundary. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_config_transcoder.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_config_transcoder.yaml new file mode 100644 index 0000000000..54d60db881 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_config_transcoder.yaml @@ -0,0 +1,194 @@ +category: application +doc: | + Configurations of a paraprobe-transcoder tool run in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXapm_paraprobe_config_transcoder(NXobject): + (NXentry): + exists: ['min', '1', 'max', '1'] + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_config_transcoder] + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ideally an ever persistent resource where the source code of the + program and build instructions can be found so that the program can be + configured ideally in such a manner that the result of this computational + process is recreatable deterministically. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + (NXprocess): + + # NXapm_input base classes are specialized here because + # paraprobe-transcoder is the entry point for community data + # which are not necessarily NeXus + dataset(NXapm_input_reconstruction): + filename: + doc: | + The path and name of the file (technology partner or community format) + from which to read the reconstructed ion positions. Currently, POS, + ePOS, APT files from APSuite, and NXS, i.e. NeXus/HDF5 files + are supported. + \@version: + iontypes(NXapm_input_ranging): + filename: + doc: | + The path and name of the file (technology partner or community format + from which to read the ranging definitions, i.e. how to map mass-to- + charge-state ratios on iontypes. Currently, RRNG, RNG, and NXS, i.e. + NeXus/HDF5 files are supported. + \@version: + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a6bb541ba6bb20a2561dada516be874b81ae4ac0ce0d78d69658da4fe7270f70 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Configurations of a paraprobe-transcoder tool run in atom probe microscopy. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ideally an ever persistent resource where the source code of the +# program and build instructions can be found so that the program can be +# configured ideally in such a manner that the result of this computational +# process is recreatable deterministically. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# +# +# +# The path and name of the file (technology partner or community format) +# from which to read the reconstructed ion positions. Currently, POS, +# ePOS, APT files from APSuite, and NXS, i.e. NeXus/HDF5 files +# are supported. +# +# +# +# +# +# +# +# The path and name of the file (technology partner or community format +# from which to read the ranging definitions, i.e. how to map mass-to- +# charge-state ratios on iontypes. Currently, RRNG, RNG, and NXS, i.e. +# NeXus/HDF5 files are supported. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_clusterer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_clusterer.yaml new file mode 100644 index 0000000000..08186843e9 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_clusterer.yaml @@ -0,0 +1,960 @@ +category: application +doc: | + Results of a paraprobe-clusterer tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_dict: | + The total number of entries in the restricted_identifier dictionary. +type: group +NXapm_paraprobe_results_clusterer(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_clusterer] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must no longer compute analyses. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases, it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: optional + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + If nothing else is specified we assume that there + has to be at least one set of NXtransformations named + paraprobe defined, which specifies the coordinate system. + In which all positions are defined. + + ##MK::define also reconstruction coordinate system and + ##MK::map between the two + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed during this process. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used, padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe-toolbox executable. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth (padding). + dimensions: + rank: 1 + dim: [[1, n_ions]] + cluster_analysis(NXprocess): + exists: optional + doc: | + The result of a cluster analyses. These include typically the label for + each ion/point documenting to which feature (if any) an ion is assigned. + Typically, each analysis/run yields only a single cluster. + In cases of fuzzy clustering it can be possible that an ion is assigned + to multiple cluster (eventually with different) weight/probability. + dbscanID(NXsimilarity_grouping): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Results of a DBScan clustering analysis. + eps(NX_FLOAT): + unit: NX_LENGTH + doc: | + The epsilon (eps) parameter. + min_pts(NX_UINT): + unit: NX_UNITLESS + doc: | + The minimum points (min_pts) parameter. + cardinality(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of members in the set which is partitioned into features. + Specifically, this is the total number of targets filtered from the + dataset. Cardinality here is not the total number of ions in the + dataset. + + # number_of_numeric_labels(NX_UINT): + # doc: | + # How many numerical labels does each feature have. + # unit: NX_UNITLESS + # number_of_categorical_labels(NX_UINT): + # doc: | + # How many categorical labels does each feature have. + # unit: NX_UNITLESS + # features: + # doc: | + # Reference to a set of features investigated in a cluster analysis. + # Features need to have disjoint numeric identifier. + identifier_offset(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + Numerical identifier have to be strictly increasing. + + # dimensions: + # rank: 1 + # dim: [[1, n_lbl_num]] + # reserved_identifier_keyword(NX_UINT): + # doc: | + # By default we assume that cluster identifier 0 is reserved to + # mark that ions are not assigned to a cluster and identifier 1 is + # noise. The reserved_identifier_keyword and reserved_identifier_value + # can be used as a dictionary though to define that users + # which to overwrite this default and define own specific categories. + # In every case though cluster_identifier have to be positive integer + # and be consecutive on $[0, maximum_value]$. + # unit: NX_UNITLESS + # dimensions: + # rank: 1 + # dim: [[1, n_dict]] + # reserved_identifier_value: + # doc: | + # The corresponding value of the reserved_identifier dictionary. + # This can give a free-text description what a specific reserved + # ID specifies e.g. ignored, noise. + # unit: NX_UNITLESS + # dimensions: + # rank: 1 + # dim: [[1, n_dict]] + targets(NX_UINT): + unit: NX_UNITLESS + doc: | + The evaporation sequence identifier to figure out which ions + from the reconstruction were considered targets. + dimensions: + rank: 1 + dim: [[1, c]] + + # quantities for debugging purposes + model_labels(NX_INT): + unit: NX_UNITLESS + doc: | + The raw labels from the DBScan clustering backend process. + dimensions: + rank: 1 + dim: [[1, c]] + core_sample_indices(NX_INT): + unit: NX_UNITLESS + doc: | + The raw array of core sample indices which specify which of the + targets are core points. + dimensions: + rank: 1 + dim: [[1, n]] + + # quantities to which these debugging quantities should be transformed + numerical_label(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of numerical label for each member in the set. + For classical clustering algorithms this can for instance + encode the cluster_identifier. + dimensions: + rank: 1 + dim: [[1, c]] + + # categorical_label: + # doc: | + # Matrix of categorical attribute data for each member in the set. + # dimensions: + # rank: 2 + # dim: [[1, c], [2, n_lbl_cat]] + weight(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + The array of weight which specifies how surely/likely the + cluster is associated/assigned to a specific identifier as + is specified in the cluster_identifier array. + For the DBScan and atom probe tomography the multiplicity + of each ion with respect to the cluster. That is how many times + should the position of the ion be accounted for because the ion + is e.g. a molecular ion with several elements or isotope of + requested type. + dimensions: + rank: 1 + dim: [[1, c]] + is_noise(NX_BOOLEAN): + exists: optional + doc: | + Optional bitmask encoding if members of the set are assigned to as noise or not. + dimensions: + rank: 1 + dim: [[1, c]] + is_core(NX_BOOLEAN): + exists: optional + doc: | + Optional bitmask encoding if member of the set are a core point. + For details to which feature/cluster an ion/point is a core point + consider numerical_label. + dimensions: + rank: 1 + dim: [[1, c]] + statistics(NXprocess): + doc: | + In addition to the detailed storage which members was grouped to + which feature/group summary statistics are stored under this group. + + # at the level of the set + # number_of_unassigned_members(NX_UINT): + # doc: | + # Total number of members in the set which are categorized as unassigned. + # unit: NX_UNITLESS + # dimensions: + # rank: 1 + # dim: [[1, n_lbl_num]] + number_of_noise(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of members in the set which are categorized as noise. + + # dimensions: + # rank: 1 + # dim: [[1, n_lbl_num]] + number_of_core(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of members in the set which are categorized as a core point. + + # dimensions: + # rank: 1 + # dim: [[1, n_lbl_num]] + # at the level of the feature set + number_of_features(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of clusters (excluding noise and unassigned). + feature_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of numerical identifier of each feature (cluster). + dimensions: + rank: 1 + dim: [[1, n_features]] + feature_member_count(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of number of members for each feature. + dimensions: + rank: 1 + dim: [[1, n_features]] + + # ADD FURTHER RESULTS along the same pattern for e.g. OPTICS and HDBSCAN + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b3a37df81b97bc33a6f0f18e802898a70c94977a92b2e598360ceb871ee5cd9c +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# The total number of entries in the restricted_identifier dictionary. +# +# +# +# +# Results of a paraprobe-clusterer tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must no longer compute analyses. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases, it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# If nothing else is specified we assume that there +# has to be at least one set of NXtransformations named +# paraprobe defined, which specifies the coordinate system. +# In which all positions are defined. +# +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed during this process. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used, padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe-toolbox executable. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth (padding). +# +# +# +# +# +# +# +# +# The result of a cluster analyses. These include typically the label for +# each ion/point documenting to which feature (if any) an ion is assigned. +# Typically, each analysis/run yields only a single cluster. +# In cases of fuzzy clustering it can be possible that an ion is assigned +# to multiple cluster (eventually with different) weight/probability. +# +# +# +# Results of a DBScan clustering analysis. +# +# +# +# The epsilon (eps) parameter. +# +# +# +# +# The minimum points (min_pts) parameter. +# +# +# +# +# Number of members in the set which is partitioned into features. +# Specifically, this is the total number of targets filtered from the +# dataset. Cardinality here is not the total number of ions in the +# dataset. +# +# +# +# +# +# Which identifier is the first to be used to label a cluster. +# +# The value should be chosen in such a way that special values can be resolved: +# * identifier_offset-1 indicates an object belongs to no cluster. +# * identifier_offset-2 indicates an object belongs to the noise category. +# Setting for instance identifier_offset to 1 recovers the commonly used +# case that objects of the noise category get values to -1 and unassigned points to 0. +# Numerical identifier have to be strictly increasing. +# +# +# +# +# +# The evaporation sequence identifier to figure out which ions +# from the reconstruction were considered targets. +# +# +# +# +# +# +# +# +# The raw labels from the DBScan clustering backend process. +# +# +# +# +# +# +# +# The raw array of core sample indices which specify which of the +# targets are core points. +# +# +# +# +# +# +# +# +# Matrix of numerical label for each member in the set. +# For classical clustering algorithms this can for instance +# encode the cluster_identifier. +# +# +# +# +# +# +# +# +# The array of weight which specifies how surely/likely the +# cluster is associated/assigned to a specific identifier as +# is specified in the cluster_identifier array. +# For the DBScan and atom probe tomography the multiplicity +# of each ion with respect to the cluster. That is how many times +# should the position of the ion be accounted for because the ion +# is e.g. a molecular ion with several elements or isotope of +# requested type. +# +# +# +# +# +# +# +# Optional bitmask encoding if members of the set are assigned to as noise or not. +# +# +# +# +# +# +# +# Optional bitmask encoding if member of the set are a core point. +# For details to which feature/cluster an ion/point is a core point +# consider numerical_label. +# +# +# +# +# +# +# +# In addition to the detailed storage which members was grouped to +# which feature/group summary statistics are stored under this group. +# +# +# +# +# Total number of members in the set which are categorized as noise. +# +# +# +# +# +# Total number of members in the set which are categorized as a core point. +# +# +# +# +# +# Total number of clusters (excluding noise and unassigned). +# +# +# +# +# Array of numerical identifier of each feature (cluster). +# +# +# +# +# +# +# +# Array of number of members for each feature. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_distancer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_distancer.yaml new file mode 100644 index 0000000000..3ca5378087 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_distancer.yaml @@ -0,0 +1,730 @@ +category: application +doc: | + Results of a paraprobe-distancer tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_tris: | + The total number of triangles in the set. +type: group +NXapm_paraprobe_results_distancer(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_distancer] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + point_to_triangle_set(NXprocess): + doc: | + The tool can be used to compute the analytical distance of each ion + to a set of triangles. + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + window_triangles(NXcs_filter_boolean_mask): + exists: optional + doc: | + A bitmask which identifies which of the triangles in the set + were considered. Usually these are all but sometimes users may + wish to filter certain portions of the triangles out. + If window_triangles is not provided it means that + all triangles were taken. + number_of_triangles(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of triangles covered by the mask. + The mask value for most may be 0. + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_triangles]] + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + The closest analytical distance of the ions to their respectively + closest triangle from the triangle set. + dimensions: + rank: 1 + dim: [[1, i]] + sign_valid(NXcs_filter_boolean_mask): + exists: optional + doc: | + A bitmask which identifies which of the distance values + can be assumed to have a consistent sign because the closest + triangle had a consistent outer unit normal defined. + For points whose bit is set 0 the distance is correct but the + sign is not reliable. + number_of_points(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of triangles covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. + dimensions: + rank: 1 + dim: [[1, i]] + triangle_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The identifier of the triangle that is closest for each ion. + dimensions: + rank: 1 + dim: [[1, i]] + xdmf_ion_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + A support field to visualize each ion and with this the distance + informations using XDMF and e.g. Paraview. + dimensions: + rank: 1 + dim: [[1, i]] + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# db9beb02a1f399f796e0d37bfa5d97ad75aba6c4ba62980e392a3e9b517c1442 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# The total number of triangles in the set. +# +# +# +# +# Results of a paraprobe-distancer tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# The tool can be used to compute the analytical distance of each ion +# to a set of triangles. +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of the triangles in the set +# were considered. Usually these are all but sometimes users may +# wish to filter certain portions of the triangles out. +# If window_triangles is not provided it means that +# all triangles were taken. +# +# +# +# Number of triangles covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# The closest analytical distance of the ions to their respectively +# closest triangle from the triangle set. +# +# +# +# +# +# +# +# A bitmask which identifies which of the distance values +# can be assumed to have a consistent sign because the closest +# triangle had a consistent outer unit normal defined. +# For points whose bit is set 0 the distance is correct but the +# sign is not reliable. +# +# +# +# Number of triangles covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. +# +# +# +# +# +# +# +# +# The identifier of the triangle that is closest for each ion. +# +# +# +# +# +# +# +# A support field to visualize each ion and with this the distance +# informations using XDMF and e.g. Paraview. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_intersector.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_intersector.yaml new file mode 100644 index 0000000000..7d93939ffe --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_intersector.yaml @@ -0,0 +1,736 @@ +category: application +doc: | + Results of a paraprobe-intersector tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_c2n: | + The total number of links pointing from current to next. + n_n2c: | + The total number of links pointing from next to current. + n_features_curr: | + The total number of members in the current_set. + n_features_next: | + The total number of members in the next_set. + n_cluster: | + The total number of cluster found for coprecipitation analysis. + n_total: | + The number of rows in the table/matrix for coprecipitation stats. +type: group +NXapm_paraprobe_results_intersector(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_intersector] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + exists: optional + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + VOLUME_VOLUME_SPATIAL_CORRELATION(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + The results of an overlap/intersection analysis. + current_to_next_link(NX_UINT): + unit: NX_UNITLESS + doc: | + A matrix of feature_identifier which specifies which named features + from the current set have directed link(s) pointing to which named + feature(s) from the next set. + dimensions: + rank: 2 + dim: [[1, n_c2n], [2, 2]] + current_to_next_link_type(NX_UINT): + unit: NX_UNITLESS + doc: | + For each link/pair in current_to_next a characterization + whether the link is due to a volumetric overlap (0x00 == 0), + proximity (0x01 == 1), or something else unknown (0xFF == 255). + dimensions: + rank: 1 + dim: [[1, n_c2n]] + next_to_current_link(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + A matrix of feature_identifier which specifies which named feature(s) + from the next set have directed link(s) pointing to which named + feature(s) from the current set. Only if the mapping whereby the + links is symmetric next_to_current maps the links in current_to_next + in the opposite direction. + dimensions: + rank: 2 + dim: [[1, n2c], [2, 2]] + next_to_current_link_type(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + For each link/pair in next_to_current a characterization + whether the link is due to a volumetric overlap (0x00 == 0), + proximity (0x01 == 1), or something else unknown (0xFF == 255). + dimensions: + rank: 1 + dim: [[1, n_n2c]] + intersection_volume(NX_FLOAT): + exists: optional + unit: NX_VOLUME + doc: | + For each pair of links in current_to_next the volume of the + intersection, i.e. how much volume do the two features share. + If features do not intersect the volume is zero. + dimensions: + rank: 1 + dim: [[1, c2n]] + coprecipitation_analysis(NXprocess): + exists: optional + doc: | + During coprecipitation analysis the current and next set are analyzed + for links in a special way. Three set comparisons are made. Members + of the set in each comparison are analyzed for overlap and proximity: + + The first comparison is the current_set against the current_set. + The second comparison is the next_set against the next_set. + The third comparison is the current_set against the next_set. + + Once the (forward) links for these comparisons are ready the + pair relations are analyzed with respect to which feature identifier + cluster in identifier space. Thereby a logical connection (link) is + established between the features in the current_set and next_set. + Recall that these two set typically represent different features + within an observed system for otherwise the same parameterization. + Examples include two sets of e.g. precipitates with differing + chemical composition that were characterized in the same material + volume representing a snapshot of an e.g. microstructure at the same + point in time. Researchers may have performed two analyses, one to + characterize precipitates A and another one to characterize percipitates + B. Coprecipitation analysis now logically connects these independent + characterization results to establish spatial correlations of e.g. + precipitates spatial arrangement. + current_set_feature_to_cluster(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of feature_identifier and cluster_identifier pairs which + encodes the cluster to which each feature_identifier was assigned. + Here for features of the current_set. + dimensions: + rank: 2 + dim: [[1, n_features_curr], [2, 2]] + next_set_feature_to_cluster(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of feature_identifier and cluster_identifier pairs which + encodes the cluster to which each feature_identifier was assigned. + Here for features of the next_set. + dimensions: + rank: 2 + dim: [[1, n_features_next], [2, 2]] + cluster_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + The identifier (names) of the cluster. + dimensions: + rank: 1 + dim: [[1, n_cluster]] + cluster_composition(NX_UINT): + unit: NX_UNITLESS + doc: | + Pivot table as a matrix. The first column encodes how many + members from the current_set are in each cluster, one row per cluster. + The second column encodes how many members from the next_set are + in each cluster, in the same row per cluster respectively. + The last column encodes the total number of members in the cluster. + dimensions: + rank: 2 + dim: [[1, n_cluster], [2, 3]] + cluster_statistics(NX_UINT): + unit: NX_UNITLESS + doc: | + Pivot table as a matrix. The first column encodes the different + types of clusters based on their number of members in the sub-graph. + The second column encodes how many clusters with as many members + exist. + dimensions: + rank: 2 + dim: [[1, n_total], [2, 2]] + + ##MK::add results from NXapm_paraprobe_results_clusterer + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d2a7c5a6492bf8b6d6196f0b993c4ecefd16301afc3d9924fd1614c05671488d +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of links pointing from current to next. +# +# +# +# +# The total number of links pointing from next to current. +# +# +# +# +# The total number of members in the current_set. +# +# +# +# +# The total number of members in the next_set. +# +# +# +# +# The total number of cluster found for coprecipitation analysis. +# +# +# +# +# The number of rows in the table/matrix for coprecipitation stats. +# +# +# +# +# Results of a paraprobe-intersector tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# The results of an overlap/intersection analysis. +# +# +# +# A matrix of feature_identifier which specifies which named features +# from the current set have directed link(s) pointing to which named +# feature(s) from the next set. +# +# +# +# +# +# +# +# +# For each link/pair in current_to_next a characterization +# whether the link is due to a volumetric overlap (0x00 == 0), +# proximity (0x01 == 1), or something else unknown (0xFF == 255). +# +# +# +# +# +# +# +# A matrix of feature_identifier which specifies which named feature(s) +# from the next set have directed link(s) pointing to which named +# feature(s) from the current set. Only if the mapping whereby the +# links is symmetric next_to_current maps the links in current_to_next +# in the opposite direction. +# +# +# +# +# +# +# +# +# For each link/pair in next_to_current a characterization +# whether the link is due to a volumetric overlap (0x00 == 0), +# proximity (0x01 == 1), or something else unknown (0xFF == 255). +# +# +# +# +# +# +# +# For each pair of links in current_to_next the volume of the +# intersection, i.e. how much volume do the two features share. +# If features do not intersect the volume is zero. +# +# +# +# +# +# +# +# During coprecipitation analysis the current and next set are analyzed +# for links in a special way. Three set comparisons are made. Members +# of the set in each comparison are analyzed for overlap and proximity: +# +# The first comparison is the current_set against the current_set. +# The second comparison is the next_set against the next_set. +# The third comparison is the current_set against the next_set. +# +# Once the (forward) links for these comparisons are ready the +# pair relations are analyzed with respect to which feature identifier +# cluster in identifier space. Thereby a logical connection (link) is +# established between the features in the current_set and next_set. +# Recall that these two set typically represent different features +# within an observed system for otherwise the same parameterization. +# Examples include two sets of e.g. precipitates with differing +# chemical composition that were characterized in the same material +# volume representing a snapshot of an e.g. microstructure at the same +# point in time. Researchers may have performed two analyses, one to +# characterize precipitates A and another one to characterize percipitates +# B. Coprecipitation analysis now logically connects these independent +# characterization results to establish spatial correlations of e.g. +# precipitates spatial arrangement. +# +# +# +# Matrix of feature_identifier and cluster_identifier pairs which +# encodes the cluster to which each feature_identifier was assigned. +# Here for features of the current_set. +# +# +# +# +# +# +# +# +# Matrix of feature_identifier and cluster_identifier pairs which +# encodes the cluster to which each feature_identifier was assigned. +# Here for features of the next_set. +# +# +# +# +# +# +# +# +# The identifier (names) of the cluster. +# +# +# +# +# +# +# +# Pivot table as a matrix. The first column encodes how many +# members from the current_set are in each cluster, one row per cluster. +# The second column encodes how many members from the next_set are +# in each cluster, in the same row per cluster respectively. +# The last column encodes the total number of members in the cluster. +# +# +# +# +# +# +# +# +# Pivot table as a matrix. The first column encodes the different +# types of clusters based on their number of members in the sub-graph. +# The second column encodes how many clusters with as many members +# exist. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_nanochem.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_nanochem.yaml new file mode 100644 index 0000000000..e04a5c6434 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_nanochem.yaml @@ -0,0 +1,3752 @@ +category: application +doc: | + Results of a paraprobe-nanochem tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_atomic: | + The total number of atoms in the atomic_decomposition match filter. + n_isotopic: | + The total number of isotopes in the isotopic_decomposition match filter. + d: | + The dimensionality of the delocalization grid. + c: | + The cardinality/total number of cells/grid points in the delocalization grid. + + # c_tri_soup: | + # The cardinality/total number of triangles in the triangle soup. + n_f_tri_xdmf: | + The total number of XDMF values to represent all faces of triangles via XDMF. + n_feature_dict: | + The total number of entries in a feature dictionary. + n_speci: | + The total number of member distinguished when reporting composition. +type: group +NXapm_paraprobe_results_nanochem(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_nanochem] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must no longer compute analyses. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases, it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: optional + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + If nothing else is specified we assume that there + has to be at least one set of NXtransformations named + paraprobe defined, which specifies the coordinate system. + In which all positions are defined. + + ##MK::define also reconstruction coordinate system and + ##MK::map between the two + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed during this process. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used, padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe-toolbox executable. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth (padding). + dimensions: + rank: 1 + dim: [[1, n_ions]] + iso_surface_analysis(NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + DELOCALIZATION(NXdelocalization): + weighting_model: + doc: | + The weighting model specifies how mark data are mapped to a weight + per point/ion. For atom probe microscopy (APM) mark data are e.g. + which iontype an ion has. As an example, different models are used + which account differently for the multiplicity of a point/ion + during delocalization: + + * unity, all points/ions get the same weight 1. + * atomic_decomposition, points get as much weight as they + have atoms of a type in atomic_decomposition_rule, + * isotope_decomposition, points get as much weight as they have + isotopes of a type in isotopic_decomposition_rule. + enumeration: [unity, atomic_decomposition, isotopic_decomposition] + + # if weighting_model == atomic_decomposition needs atomic_decomposition_rule + # if weighting_model == isotopic_decomposition needs isotopic_decomposition_rule + atomic_decomposition_rule(NXmatch_filter): + exists: optional + doc: | + A list of elements (via proton number) to consider for the + atomic_decomposition weighting model. + Elements must exist in the periodic table of elements and be + specified by their number of protons. + Values in match are isotope hash values using the following + hashing rule $H = Z + 256*N$ with $Z$ the number of protons + and $N$ the number of neutrons of the isotope. + In the case of elements this hashing rule has the advantage + that for elements the proton number is their hash value because + N is zero. + method: + doc: | + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + enumeration: [whitelist, blacklist] + match(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of values to filter according to method. For example, + if the filter specifies [1, 5, 6] and method is whitelist, + only entries with values matching 1, 5 or 6 will be processed. + All other entries will be filtered out/not considered. + dimensions: + rank: 1 + dim: [[1, n_atomic]] + isotopic_decomposition_rule(NXmatch_filter): + exists: optional + doc: | + A list of isotopes (via proton and neutron number) to consider + for the isotopic_decomposition weighting model. + Isotopes must exist in the nuclid table. + Values in match are isotope hash values using the following + hashing rule $H = Z + 256*N$ with $Z$ the number of protons + and $N$ the number of neutrons of the isotope. + method: + doc: | + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + enumeration: [whitelist, blacklist] + match(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of values to filter according to method. For example, + if the filter specifies [1, 5, 6] and method is whitelist, + only entries with values matching 1, 5 or 6 will be processed. + All other entries will be filtered out/not considered. + dimensions: + rank: 1 + dim: [[1, n_isotopic]] + normalization: + doc: | + How results of the kernel-density estimation were computed + into quantities. By default the tool computes the total number + (intensity) of ions or elements. Alternatively the tool can compute + the total intensity, the composition, or the concentration of the + ions/elements specified by the white list of elements in each voxel. + enumeration: [total, candidates, composition, concentration] + weight(NX_NUMBER): + exists: optional + unit: NX_DIMENSIONLESS + doc: | + Weighting factor, in atom probe, often termed multiplicity. + The weighting factor is the multiplier with which the integrated + intensity contribution from the point/ion gets multiplied. + The delocalization computes the integrated intensity for each + grid cell. Effectively, this is an explicitly evaluated kernel + method where each specific position of an ion is replaced by a + smoothing kernel. For atom probe weights are positive and integer + specifically the multiplicity of the ion, in accordance with the + respective rulesets as defined by weighting_model. + dimensions: + rank: 1 + dim: [[1, n_ions]] + grid(NXcg_grid): + doc: | + The discretized domain/grid on which the delocalization is applied. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + enumeration: [1, 2, 3] + cardinality(NX_POSINT): + unit: NX_UNITLESS + doc: | + The total number of cells/voxels of the grid. + origin(NX_NUMBER): + dimensions: + rank: 1 + dim: [[1, d]] + symmetry: + doc: | + The symmetry of the lattice defining the shape of the unit cell. + enumeration: [cubic] + cell_dimensions(NX_NUMBER): + unit: NX_LENGTH + doc: | + The unit cell dimensions according to the coordinate system + defined under coordinate_system. + dimensions: + rank: 1 + dim: [[1, d]] + extent(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of unit cells along each of the d unit vectors. + The total number of cells, or grid points has to be the cardinality. + If the grid has an irregular number of grid positions in each direction, + as it could be for instance the case of a grid where all grid points + outside some masking primitive are removed, this extent field should + not be used. Instead use the coordinate field. + dimensions: + rank: 1 + dim: [[1, d]] + + # (NXtransformations): + coordinate_system: + exists: optional + doc: | + Reference to or definition of a coordinate system with + which the positions and directions are interpretable. + If the coordinate system is not specified the paraprobe + coordinate system is used. + + # should constraints on the grid be place here or not + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for + distinguishing identifiers for cells. Identifiers are defined + either implicitly or explicitly. For implicit indexing the + identifiers are defined on the interval + [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + bounding_box(NXcg_hexahedron_set): + doc: | + A tight axis-aligned bounding box about the grid. + is_axis_aligned(NX_BOOLEAN): + unit: NX_UNITLESS + doc: | + For atom probe should be set to true. + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + hexahedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + hexahedron(NXcg_face_list_data_structure): + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + identifiers for vertices. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + identifiers for faces. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + vertices(NX_NUMBER): + unit: NX_LENGTH + doc: | + Positions of the vertices. + + Users are encouraged to reduce the vertices to unique set of positions + and vertices as this supports a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. + Naively here means that one for example stores each vertex of a triangle + mesh even though many vertices are shared between triangles and thus + the positions of these vertices do not have to be duplicated. + dimensions: + rank: 2 + dim: [[1, 8], [2, 3]] + faces(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of identifiers from vertices which describe each face. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + dimensions: + rank: 2 + dim: [[1, 6], [2, 4]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + Six equally formatted sextets chained together. For each + sextett the first entry is an XDMF primitive topology + key (here 5 for polygon), the second entry the XDMF primitive + count value (here 4 because each face is a quad). + The remaining four values are the vertex indices. + dimensions: + rank: 1 + dim: [[1, 36]] + number_of_boundaries(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + How many distinct boundaries are distinguished? + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + boundaries: + exists: optional + doc: | + Name of the boundaries. E.g. left, right, front, back, bottom, top, + The field must have as many entries as there are number_of_boundaries. + dimensions: + rank: 1 + dim: [[1, 6]] + boundary_conditions(NX_INT): + exists: optional + unit: NX_UNITLESS + doc: | + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + dimensions: + rank: 1 + dim: [[1, 6]] + + ##MK::how to avoid storing it for once in NeXus for H5Web and + # for XDMF in ParaView ? + scalar_field_magnitude(NXdata): + doc: | + The result of the delocalization based on which subsequent + iso-surfaces will be computed. In commercial software so far + there is not a possibility to export such grid. + + ##MK::math notation + \@long_name: + exists: optional + \@signal: + \@axes: + \@xpos_indices: + \@ypos_indices: + \@zpos_indices: + intensity(NX_FLOAT): + dimensions: + rank: 3 + dim: [[1, n_z], [2, n_y], [3, n_x]] + xpos(NX_FLOAT): + doc: | + Cell center of mass positions along x. + dimensions: + rank: 1 + dim: [[1, n_x]] + + ##MK::how to relate back that this x is paraprobe x? + ypos(NX_FLOAT): + doc: | + Cell center of mass positions along y. + dimensions: + rank: 1 + dim: [[1, n_y]] + zpos(NX_FLOAT): + doc: | + Cell center of mass positions along z. + dimensions: + rank: 1 + dim: [[1, n_z]] + xdmf_intensity(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Intensity of the field at given point + dimensions: + rank: 1 + dim: [[1, n_xyz]] + xdmf_xyz(NX_FLOAT): + exists: optional + unit: NX_UNITLESS + doc: | + Center of mass positions of each voxel for + rendering the scalar field via XDMF in e.g. + Paraview. + dimensions: + rank: 2 + dim: [[1, n_xyz], [2, 3]] + xdmf_topology(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + XDMF topology for rendering in combination with + xdmf_xyz the scalar field via XDFM in e.g. Paraview. + dimensions: + rank: 1 + dim: [[1, 3*n_xyz]] + scalar_field_gradient(NXdata): + doc: | + The three-dimensional gradient nabla operator applied to + scalar_field_magnitude. + + ##MK::boundary conditions which type of accuracy + ##MK::math notation + \@signal: + \@axes: + + ##MK::vector_indices, # ##MK: 3 + \@xpos_indices: + \@ypos_indices: + \@zpos_indices: + \@long_name: + exists: optional + intensity(NX_FLOAT): + dimensions: + rank: 4 + dim: [[1, n_z], [2, n_y], [3, n_x], [4, 3]] + xpos(NX_FLOAT): + doc: | + Cell center of mass positions along x. + dimensions: + rank: 1 + dim: [[1, n_x]] + + ##MK::how to relate back that this x is paraprobe x? + ypos(NX_FLOAT): + doc: | + Cell center of mass positions along y. + dimensions: + rank: 1 + dim: [[1, n_y]] + zpos(NX_FLOAT): + doc: | + Cell center of mass positions along z. + dimensions: + rank: 1 + dim: [[1, n_z]] + xdmf_gradient(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + The gradient vector. + dimensions: + rank: 2 + dim: [[1, n_xyz], [2, 3]] + xdmf_xyz(NX_FLOAT): + exists: optional + unit: NX_UNITLESS + doc: | + Center of mass positions of each voxel for + rendering the scalar field via XDMF in e.g. + Paraview. + dimensions: + rank: 2 + dim: [[1, n_xyz], [2, 3]] + xdmf_topology(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + XDMF topology for rendering in combination with + xdmf_xyz the scalar field via XDFM in e.g. Paraview. + dimensions: + rank: 1 + dim: [[1, 3*n_xyz]] + kernel_size(NX_POSINT): + unit: NX_DIMENSIONLESS + doc: | + Halfwidth of the kernel about the central voxel. + The shape of the kernel is that of a cuboid + of extent 2*kernel_extent[i] + 1 in each dimension i. + + # \@units: pixel + dimensions: + rank: 1 + dim: [[1, 3]] + + # kernel_type: + # doc: | + # Functional form of the kernel (Ansatz function). + kernel_sigma(NX_FLOAT): + unit: NX_LENGTH + doc: | + Sigma of the kernel in each dimension in the paraprobe + coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. + dimensions: + rank: 1 + dim: [[1, 3]] + kernel_mu(NX_FLOAT): + unit: NX_LENGTH + doc: | + Expectation value of the kernel in each dimension in the paraprobe + coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. + dimensions: + rank: 1 + dim: [[1, 3]] + + ##MK:: + iso_surface(NXisocontour): + exists: optional + doc: | + An iso-surface is the boundary between two regions across which + the magnitude of a scalar field falls below/exceeds a threshold + magnitude phi. + For applications in atom probe microscopy the location and shape + of such a boundary (set) is typically approximated by + discretization. + This yields a complex of not necessarily connected geometric + primitives. Paraprobe-nanochem approximates this complex with + a soup of triangles. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + isovalue(NX_NUMBER): + unit: NX_ANY + doc: | + The threshold or iso-contour value. + marching_cubes(NXcg_marching_cubes): + doc: | + Details about the specific marching cubes algorithm + which was taken to compute the iso-surface. + The grid is the delocalization grid. + implementation: + doc: | + Reference to the specific implementation of marching cubes used. + The value placed here should be a DOI. If there are no specific + DOI or details write not_further_specified, or give at least a + free-text description. The program and version used is the + specific paraprobe-nanochem. + triangle_soup(NXcg_triangle_set): + exists: optional + doc: | + The resulting triangle soup computed via marching cubes. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for + distinguishing triangles. Identifiers are defined either + implicitly or explicitly. For implicit indexing the + identifiers are defined on the interval + [identifier_offset, identifier_offset+c-1]. + triangles(NXcg_face_list_data_structure): + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of vertices. + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of faces. + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + identifiers for vertices. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + identifiers for faces. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + vertices(NX_NUMBER): + unit: NX_LENGTH + doc: | + Positions of the vertices. + + Users are encouraged to reduce the vertices to unique set of positions + and vertices as this supports a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. + Naively here means that one for example stores each vertex of a triangle + mesh even though many vertices are shared between triangles and thus + the positions of these vertices do not have to be duplicated. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + faces(NX_INT): + unit: NX_UNITLESS + doc: | + Array of identifiers from vertices which describe each face. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + dimensions: + rank: 1 + dim: [[1, j]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tri * (1+1+3). + dimensions: + rank: 1 + dim: [[1, n_f_tri_xdmf]] + vertex_normal(NXcg_unit_normal_set): + exists: optional + normals(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Direction of each normal. + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + orientation(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its + primitive each normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, j]] + + # edge_normal(NXcg_unit_normal_set): + # exists: optional + face_normal(NXcg_unit_normal_set): + exists: optional + normals(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Direction of each normal. + dimensions: + rank: 2 + dim: [[1, k], [2, 3]] + orientation(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its + primitive each normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, k]] + gradient_guide_magnitude(NX_FLOAT): + unit: NX_ANY + doc: | + Triangle normals are oriented in the direction of the + gradient vector of the local delocalized scalar field. + :math:`\sum_{x, y, z} {\nabla{c}_i}^2`. + dimensions: + rank: 1 + dim: [[1, k]] + + # gradient_guide_quality(NX_FLOAT): + # doc: | + # Triangle normals are oriented in the direction of the + # gradient vector of the local delocalized scalar field. + # Sum of squared values of cross product of triangle normal + # construction. + # unit: NX_ANY + # dimensions: + # rank: 1 + # dim: [[1, k]] + gradient_guide_projection(NX_FLOAT): + unit: NX_ANY + doc: | + Triangle normals are oriented in the direction of the + gradient vector of the local delocalized scalar field. + The projection variable here describes the cosine of the + angle between the gradient direction and the normal + direction vector. + This is a descriptor of how parallel the projection is + that is especially useful to document those triangles + for whose projection is almost perpendicular. + dimensions: + rank: 1 + dim: [[1, k]] + area(NX_NUMBER): + exists: optional + unit: NX_AREA + dimensions: + rank: 1 + dim: [[1, j]] + edge_length(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + Array of edge length values. For each triangle the edge length + is reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, k], [2, 3]] + interior_angle(NX_NUMBER): + exists: optional + unit: NX_ANGLE + doc: | + Array of interior angle values. For each triangle the angle + is reported for the angle opposite to the edges which are + traversed according to the sequence in which vertices + are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, j], [2, 4]] + center(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + The center of mass of each triangle. + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + volumetric_feature(NXprocess): + exists: optional + doc: | + Iso-surfaces of arbitrary scalar three-dimensional fields + can show a complicated topology. Paraprobe-nanochem can run + a DBScan-like clustering algorithm which performs a + connectivity analysis on the triangle soup. This yields a + set of connected features with their surfaces discretized + by triangles. Currently, the tool distinguishes at most + three types of features: + + 1. So-called objects, i.e. necessarily watertight features + represented polyhedra. + 2. So-called proxies, i.e. features that were replaced by a + proxy mesh and made watertight. + 3. Remaining triangle surface meshes of arbitrary shape and + cardinality. + + These features can be interpreted as microstructural features. + Some of them may be precipitates, some of them may be poles, + some of them may be segments of dislocation lines or other + crystal defects which are decorated (or not) with solutes. + + # Each type of feature needs to be registered in the feature_type + # dictionary. Type identifiers (keywords are integer), values + # are human-readable names like object, proxy, undefined + # NEW ISSUE: refactor using instances of NXms_feature_set + triangle_cluster_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + The identifier which the triangle_soup connectivity analysis + returned, which constitutes the first step of the + volumetric_feature identification process. + dimensions: + rank: 1 + dim: [[1, k]] + feature_type_dict_keyword(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The array of keywords of feature_type dictionary. + dimensions: + rank: 1 + dim: [[1, n_feature_dict]] + feature_type_dict_value: + exists: optional + doc: | + The array of values for each keyword of the + feature_type dictionary. + dimensions: + rank: 1 + dim: [[1, n_feature_dict]] + feature_type(NX_UINT): + unit: NX_ANY + doc: | + The array of controlled keywords, need to be from + feature_type_dict_keyword, which specify which type + each feature triangle cluster belongs to. + Keep in mind that not each feature is an object or proxy. + dimensions: + rank: 1 + dim: [[1, j]] + feature_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + The explicit identifier of features. + dimensions: + rank: 1 + dim: [[1, j]] + + ##MK::a nice example why we need group-overarching symbols + # a symbol for triangles would not work as the analysis can + # hold multiple instances of iso_surface each with a different + # number of triangles and/or features! + # details about specific features + objects(NXprocess): + exists: optional + doc: | + Details for features which are (closed) objects. + Identifier have to exist in feature_identifier. + + ##MK::constraints! + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + obb(NXcg_hexahedron_set): + exists: optional + doc: | + An oriented bounding box (OBB) to each object. + size(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Edge length of the oriented bounding box from largest + to smallest value. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + + ##MK::which is which + aspect(NX_FLOAT): + exists: optional + unit: NX_DIMENSIONLESS + doc: | + Oriented bounding box aspect ratio. YX versus ZY. + dimensions: + rank: 2 + dim: [[1, i], [2, 2]] + center(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + Position of the geometric center, which often is but + not necessarily has to be the center_of_mass of the + hexahedrally-shaped sample/sample part. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + hexahedra(NXcg_face_list_data_structure): + + # exists: [min, 0, max, 1] + doc: | + A simple approach to describe the entire set of hexahedra + when the main intention is to store the shape of the + hexahedra for visualization. + + ##MK::more details needed here + vertices(NX_NUMBER): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, k], [2, 3]] + + ##MK::again we have no effective way to pinpoint the n_rows + ##MK::namely k != i each OBB has eight vertices + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + xdmf_feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + objects_close_to_edge(NXprocess): + exists: optional + doc: | + Details for all those objects close to edge, i.e. those which + have at least one ion which lays closer to a modelled edge + of the dataset than threshold. + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + composition(NXchemical_composition): + exists: optional + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total (count) relevant for normalization. + dimensions: + rank: 1 + dim: [[1, i]] + ION(NXion): + exists: ['min', '0', 'max', 'unbounded'] + charge(NX_INT): + isotope_vector(NX_UINT): + nuclid_list(NX_UINT): + count(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total, + yields the composition of this element, isotope, + molecule or ion. + dimensions: + rank: 1 + dim: [[1, i]] + objectID(NXcg_polyhedron_set): + exists: ['min', '0', 'max', 'unbounded'] + polyhedron(NXcg_face_list_data_structure): + + # number_of_vertices(NX_POSINT): + # number_of_faces(NX_POSINT): + # vertex_identifier_offset(NX_UINT): + # face_identifier_offset(NX_UINT): + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + + # face_normals(NXcg_unit_normal_set): + face_normals(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + xdmf_feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + ion_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + dimensions: + rank: 1 + dim: [[1, i]] + objects_far_from_edge(NXprocess): + exists: optional + doc: | + Details for all those objects far from edge, i.e. those + whose ions lay all at least threshold distant from a + modelled edge of the dataset. + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + composition(NXchemical_composition): + exists: optional + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total (count) relevant for normalization. + dimensions: + rank: 1 + dim: [[1, i]] + ION(NXion): + exists: ['min', '0', 'max', 'unbounded'] + charge(NX_INT): + isotope_vector(NX_UINT): + nuclid_list(NX_UINT): + count(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + dimensions: + rank: 1 + dim: [[1, i]] + objectID(NXcg_polyhedron_set): + exists: ['min', '0', 'max', 'unbounded'] + polyhedron(NXcg_face_list_data_structure): + + # number_of_vertices(NX_POSINT): + # number_of_faces(NX_POSINT): + # vertex_identifier_offset(NX_UINT): + # face_identifier_offset(NX_UINT): + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + + # face_normals(NXcg_unit_normal_set): + face_normals(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + xdmf_feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + ion_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + dimensions: + rank: 1 + dim: [[1, i]] + + # linear_feature_identification(NXprocess): + # these would be polylines etc + proxies(NXprocess): + exists: optional + doc: | + Details for features which are so-called proxies, i.e. objects + which have been reconstructed and combinatorially closed with + processing their partial triangulated_surface_mesh + (hole filling, refinement). + Identifier have to exist in feature_identifier. + + ##MK::constraints feature_identifier are a subset of the parent! + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + + # obb ? + proxies_close_to_edge(NXprocess): + exists: optional + doc: | + Details for those proxies close to edge, i.e. those which + have at least one ion which lays closer to a modelled edge + of the dataset than threshold. + Identifier have to exist in feature_identifier. + + ##MK::constraints! + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + composition(NXchemical_composition): + exists: optional + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total (count) relevant for normalization. + dimensions: + rank: 1 + dim: [[1, i]] + ION(NXion): + exists: ['min', '0', 'max', 'unbounded'] + + # charge(NX_INT): + # isotope_vector(NX_UINT): + count(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + dimensions: + rank: 1 + dim: [[1, i]] + objectID(NXcg_polyhedron_set): + exists: ['min', '0', 'max', 'unbounded'] + polyhedron(NXcg_face_list_data_structure): + + # number_of_vertices(NX_POSINT): + # number_of_faces(NX_POSINT): + # vertex_identifier_offset(NX_UINT): + # face_identifier_offset(NX_UINT): + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + + # face_normals(NXcg_unit_normal_set): + face_normals(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + xdmf_feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + ion_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + dimensions: + rank: 1 + dim: [[1, i]] + proxies_far_from_edge(NXprocess): + exists: optional + doc: | + Details for those proxies far from edge, i.e. those whose + ions lay all at least threshold distant from a + modelled edge of the dataset. + feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + volume(NX_FLOAT): + unit: NX_VOLUME + dimensions: + rank: 1 + dim: [[1, i]] + composition(NXchemical_composition): + exists: optional + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total (count) relevant for normalization. + dimensions: + rank: 1 + dim: [[1, i]] + ION(NXion): + exists: ['min', '0', 'max', 'unbounded'] + + # charge(NX_INT): + # isotope_vector(NX_UINT): + count(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total + yields the composition of this element, isotope, + molecule or ion. + dimensions: + rank: 1 + dim: [[1, i]] + objectID(NXcg_polyhedron_set): + exists: ['min', '0', 'max', 'unbounded'] + polyhedron(NXcg_face_list_data_structure): + + # number_of_vertices(NX_POSINT): + # number_of_faces(NX_POSINT): + # vertex_identifier_offset(NX_UINT): + # face_identifier_offset(NX_UINT): + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + + # face_normals(NXcg_unit_normal_set): + face_normals(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_f], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + xdmf_feature_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + ion_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Array of evaporation_identifier / ion_identifier which + specify ions laying inside or on the surface of the feature. + dimensions: + rank: 1 + dim: [[1, i]] + interface_modelling(NXprocess): + exists: optional + ion_multiplicity(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The multiplicity whereby the ion position is accounted for + irrespective whether the ion is considered as a decorator + of the interface or not. + As an example, with atom probe it is typically not possible + to resolve the positions of the atoms which arrive at the detector + as molecular ions. Therefore, an exemplar molecular ion of two carbon + atoms can be considered to have a multiplicity of two to account that + this molecular ion contributes two carbon atoms at the reconstructed + location considering that the spatial resolution of atom probe + experiments is limited. + dimensions: + rank: 1 + dim: [[1, n_ions]] + decorator_multiplicity(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The multiplicity whereby the ion position is accounted for when + the ion is considered one which is a decorator of the interface. + dimensions: + rank: 1 + dim: [[1, n_ions]] + initial_interface(NXprocess): + exists: optional + doc: | + The equation of the plane that is fitted initially. + point_normal_form(NX_FLOAT): + unit: NX_LENGTH + doc: | + The four parameter :math:`ax + by + cz + d = 0` which define the plane. + dimensions: + rank: 1 + dim: [[1, 4]] + MESH_CURR_PRE_DCOM_STEP(NXcg_triangle_set): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + The triangle surface mesh representing the interface model. + Exported at some iteration before the next DCOM step. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + identifier_offset(NX_INT): + unit: NX_UNITLESS + triangles(NXcg_face_list_data_structure): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + edge_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, j]] + vertices(NX_NUMBER): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + + ##MK::vertex_normal(NXcg_unit_normal_set): + face_normal(NXcg_unit_normal_set): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + normals(NX_FLOAT): + unit: NX_LENGTH + doc: | + Direction of each normal + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + orientation(NX_UINT): + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, j]] + vertex_normal(NXcg_unit_normal_set): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + normals(NX_FLOAT): + unit: NX_LENGTH + doc: | + Direction of each normal + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + orientation(NX_UINT): + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, j]] + area(NX_NUMBER): + unit: NX_AREA + dimensions: + rank: 1 + dim: [[1, c]] + edge_length(NX_NUMBER): + unit: NX_LENGTH + doc: | + Array of edge length values. For each triangle the edge length is + reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, c], [2, 3]] + interior_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Array of interior angle values. For each triangle the angle is + reported for the angle opposite to the edges which are traversed + according to the sequence in which vertices are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, c], [2, 4]] + MESH_CURR_POST_DCOM_STEP(NXcg_triangle_set): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + The triangle surface mesh representing the interface model. + Exported at some iteration after the next DCOM step. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + identifier_offset(NX_INT): + unit: NX_UNITLESS + triangles(NXcg_face_list_data_structure): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, j]] + vertices(NX_NUMBER): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, k]] + + ##MK::vertex_normal(NXcg_unit_normal_set): + face_normal(NXcg_unit_normal_set): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + normals(NX_FLOAT): + unit: NX_LENGTH + doc: | + Direction of each normal + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + orientation(NX_UINT): + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, j]] + vertex_normal(NXcg_unit_normal_set): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + normals(NX_FLOAT): + unit: NX_LENGTH + doc: | + Direction of each normal + dimensions: + rank: 2 + dim: [[1, j], [2, 3]] + orientation(NX_UINT): + unit: NX_UNITLESS + doc: | + Qualifier how which specifically oriented normal to its primitive each + normal represents. + + * 0 - undefined + * 1 - outer + * 2 - inner + dimensions: + rank: 1 + dim: [[1, j]] + area(NX_NUMBER): + unit: NX_AREA + dimensions: + rank: 1 + dim: [[1, c]] + edge_length(NX_NUMBER): + unit: NX_LENGTH + doc: | + Array of edge length values. For each triangle the edge length is + reported for the edges traversed according to the sequence + in which vertices are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, c], [2, 3]] + interior_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Array of interior angle values. For each triangle the angle is + reported for the angle opposite to the edges which are traversed + according to the sequence in which vertices are indexed in triangles. + dimensions: + rank: 2 + dim: [[1, c], [2, 4]] + composition_analysis(NXprocess): + exists: optional + xdmf_cylinder(NXcg_polyhedron_set): + doc: | + The ROIs are defined as cylinders for the computations. + To visualize these though we discretize them into regular n-gons. + Using for instance a 360-gon, i.e. a regular n-gon with 360 + edges resolves the lateral surface of each cylinder very finely + so that they are rendered smoothly in visualization software. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + cardinality(NX_POSINT): + unit: NX_UNITLESS + center(NX_NUMBER): + unit: NX_LENGTH + doc: | + Position of the geometric center, which often is but not + necessarily has to be the center_of_mass of the polyhedra. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + roi_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + ROI cylinder. Identifiers are defined explicitly. + dimensions: + rank: 1 + dim: [[1, i]] + polyhedra(NXcg_face_list_data_structure): + exists: ['min', '0', 'max', '1'] + edge_contact(NX_UINT): + exists: optional + unit: NX_UNITLESS + dimensions: + rank: 1 + dim: [[1, i]] + + ##MK::decomposed? + number_of_atoms(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The number of atoms in each ROI. + dimensions: + rank: 1 + dim: [[1, i]] + number_of_ions(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + The number of ions in each ROI. + dimensions: + rank: 1 + dim: [[1, i]] + orientation(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + The orientation of the ROI defined via a vector which points along + the cylinder axis and whose length is the height of the cylinder. + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + ROI(NXcollection): + exists: ['min', '0', 'max', 'unbounded'] + signed_distance(NX_FLOAT): + doc: | + In the direction of the ROI. + isotope(NX_UINT): + doc: | + Hashvalue + + ##MK::#define MYCHM_DATA_ISRF_TSKS_TSCL_OBJ_ROICYL_ROIID "RoiCylinderID" + ##MK::#define MYCHM_DATA_ISRF_TSKS_TSCL_OBJ_ROICYL_OBJID "RoiCylinderObjectID" + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5c784d761ed7d02effea4621da7b23889984c1486546a5e95e76ac3ec9e1bc68 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# The total number of atoms in the atomic_decomposition match filter. +# +# +# +# +# The total number of isotopes in the isotopic_decomposition match filter. +# +# +# +# +# The dimensionality of the delocalization grid. +# +# +# +# +# The cardinality/total number of cells/grid points in the delocalization grid. +# +# +# +# +# +# The total number of XDMF values to represent all faces of triangles via XDMF. +# +# +# +# +# The total number of entries in a feature dictionary. +# +# +# +# +# The total number of member distinguished when reporting composition. +# +# +# +# +# Results of a paraprobe-nanochem tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must no longer compute analyses. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases, it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# If nothing else is specified we assume that there +# has to be at least one set of NXtransformations named +# paraprobe defined, which specifies the coordinate system. +# In which all positions are defined. +# +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed during this process. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used, padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe-toolbox executable. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth (padding). +# +# +# +# +# +# +# +# +# +# +# The weighting model specifies how mark data are mapped to a weight +# per point/ion. For atom probe microscopy (APM) mark data are e.g. +# which iontype an ion has. As an example, different models are used +# which account differently for the multiplicity of a point/ion +# during delocalization: +# +# * unity, all points/ions get the same weight 1. +# * atomic_decomposition, points get as much weight as they +# have atoms of a type in atomic_decomposition_rule, +# * isotope_decomposition, points get as much weight as they have +# isotopes of a type in isotopic_decomposition_rule. +# +# +# +# +# +# +# +# +# +# +# A list of elements (via proton number) to consider for the +# atomic_decomposition weighting model. +# Elements must exist in the periodic table of elements and be +# specified by their number of protons. +# Values in match are isotope hash values using the following +# hashing rule $H = Z + 256*N$ with $Z$ the number of protons +# and $N$ the number of neutrons of the isotope. +# In the case of elements this hashing rule has the advantage +# that for elements the proton number is their hash value because +# N is zero. +# +# +# +# Meaning of the filter: +# Whitelist specifies which entries with said value to include. +# Entries with all other values will be filtered out. +# +# Blacklist specifies which entries with said value to exclude. +# Entries with all other values will be included. +# +# +# +# +# +# +# +# +# Array of values to filter according to method. For example, +# if the filter specifies [1, 5, 6] and method is whitelist, +# only entries with values matching 1, 5 or 6 will be processed. +# All other entries will be filtered out/not considered. +# +# +# +# +# +# +# +# +# A list of isotopes (via proton and neutron number) to consider +# for the isotopic_decomposition weighting model. +# Isotopes must exist in the nuclid table. +# Values in match are isotope hash values using the following +# hashing rule $H = Z + 256*N$ with $Z$ the number of protons +# and $N$ the number of neutrons of the isotope. +# +# +# +# Meaning of the filter: +# Whitelist specifies which entries with said value to include. +# Entries with all other values will be filtered out. +# +# Blacklist specifies which entries with said value to exclude. +# Entries with all other values will be included. +# +# +# +# +# +# +# +# +# Array of values to filter according to method. For example, +# if the filter specifies [1, 5, 6] and method is whitelist, +# only entries with values matching 1, 5 or 6 will be processed. +# All other entries will be filtered out/not considered. +# +# +# +# +# +# +# +# +# How results of the kernel-density estimation were computed +# into quantities. By default the tool computes the total number +# (intensity) of ions or elements. Alternatively the tool can compute +# the total intensity, the composition, or the concentration of the +# ions/elements specified by the white list of elements in each voxel. +# +# +# +# +# +# +# +# +# +# +# Weighting factor, in atom probe, often termed multiplicity. +# The weighting factor is the multiplier with which the integrated +# intensity contribution from the point/ion gets multiplied. +# The delocalization computes the integrated intensity for each +# grid cell. Effectively, this is an explicitly evaluated kernel +# method where each specific position of an ion is replaced by a +# smoothing kernel. For atom probe weights are positive and integer +# specifically the multiplicity of the ion, in accordance with the +# respective rulesets as defined by weighting_model. +# +# +# +# +# +# +# +# The discretized domain/grid on which the delocalization is applied. +# +# +# +# +# +# +# +# +# +# +# The total number of cells/voxels of the grid. +# +# +# +# +# +# +# +# +# +# The symmetry of the lattice defining the shape of the unit cell. +# +# +# +# +# +# +# +# The unit cell dimensions according to the coordinate system +# defined under coordinate_system. +# +# +# +# +# +# +# +# Number of unit cells along each of the d unit vectors. +# The total number of cells, or grid points has to be the cardinality. +# If the grid has an irregular number of grid positions in each direction, +# as it could be for instance the case of a grid where all grid points +# outside some masking primitive are removed, this extent field should +# not be used. Instead use the coordinate field. +# +# +# +# +# +# +# +# +# Reference to or definition of a coordinate system with +# which the positions and directions are interpretable. +# If the coordinate system is not specified the paraprobe +# coordinate system is used. +# +# +# +# +# +# Integer which specifies the first index to be used for +# distinguishing identifiers for cells. Identifiers are defined +# either implicitly or explicitly. For implicit indexing the +# identifiers are defined on the interval +# [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# A tight axis-aligned bounding box about the grid. +# +# +# +# For atom probe should be set to true. +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# hexahedra. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# identifiers for vertices. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# identifiers for faces. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# Positions of the vertices. +# +# Users are encouraged to reduce the vertices to unique set of positions +# and vertices as this supports a more efficient storage of the geometry data. +# It is also possible though to store the vertex positions naively in which +# case vertices_are_unique is likely False. +# Naively here means that one for example stores each vertex of a triangle +# mesh even though many vertices are shared between triangles and thus +# the positions of these vertices do not have to be duplicated. +# +# +# +# +# +# +# +# +# Array of identifiers from vertices which describe each face. +# +# The first entry is the identifier of the start vertex of the first face, +# followed by the second vertex of the first face, until the last vertex +# of the first face. Thereafter, the start vertex of the second face, the +# second vertex of the second face, and so on and so forth. +# +# Therefore, summating over the number_of_vertices, allows to extract +# the vertex identifiers for the i-th face on the following index interval +# of the faces array: [$\sum_i = 0}^{i = n-1}$, $\sum_{i=0}^{i = n}$]. +# +# +# +# +# +# +# +# +# Six equally formatted sextets chained together. For each +# sextett the first entry is an XDMF primitive topology +# key (here 5 for polygon), the second entry the XDMF primitive +# count value (here 4 because each face is a quad). +# The remaining four values are the vertex indices. +# +# +# +# +# +# +# +# How many distinct boundaries are distinguished? +# Most grids discretize a cubic or cuboidal region. In this case +# six sides can be distinguished, each making an own boundary. +# +# +# +# +# +# Name of the boundaries. E.g. left, right, front, back, bottom, top, +# The field must have as many entries as there are number_of_boundaries. +# +# +# +# +# +# +# +# The boundary conditions for each boundary: +# +# 0 - undefined +# 1 - open +# 2 - periodic +# 3 - mirror +# 4 - von Neumann +# 5 - Dirichlet +# +# +# +# +# +# +# +# +# +# The result of the delocalization based on which subsequent +# iso-surfaces will be computed. In commercial software so far +# there is not a possibility to export such grid. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Cell center of mass positions along x. +# +# +# +# +# +# +# +# +# Cell center of mass positions along y. +# +# +# +# +# +# +# +# Cell center of mass positions along z. +# +# +# +# +# +# +# +# Intensity of the field at given point +# +# +# +# +# +# +# +# Center of mass positions of each voxel for +# rendering the scalar field via XDMF in e.g. +# Paraview. +# +# +# +# +# +# +# +# +# XDMF topology for rendering in combination with +# xdmf_xyz the scalar field via XDFM in e.g. Paraview. +# +# +# +# +# +# +# +# +# The three-dimensional gradient nabla operator applied to +# scalar_field_magnitude. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Cell center of mass positions along x. +# +# +# +# +# +# +# +# +# Cell center of mass positions along y. +# +# +# +# +# +# +# +# Cell center of mass positions along z. +# +# +# +# +# +# +# +# The gradient vector. +# +# +# +# +# +# +# +# +# Center of mass positions of each voxel for +# rendering the scalar field via XDMF in e.g. +# Paraview. +# +# +# +# +# +# +# +# +# XDMF topology for rendering in combination with +# xdmf_xyz the scalar field via XDFM in e.g. Paraview. +# +# +# +# +# +# +# +# +# Halfwidth of the kernel about the central voxel. +# The shape of the kernel is that of a cuboid +# of extent 2*kernel_extent[i] + 1 in each dimension i. +# +# +# +# +# +# +# +# +# +# Sigma of the kernel in each dimension in the paraprobe +# coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. +# +# +# +# +# +# +# +# Expectation value of the kernel in each dimension in the paraprobe +# coordinate_system with i = 0 is x, i = 1 is y, i = 2 is z. +# +# +# +# +# +# +# +# +# +# An iso-surface is the boundary between two regions across which +# the magnitude of a scalar field falls below/exceeds a threshold +# magnitude phi. +# For applications in atom probe microscopy the location and shape +# of such a boundary (set) is typically approximated by +# discretization. +# This yields a complex of not necessarily connected geometric +# primitives. Paraprobe-nanochem approximates this complex with +# a soup of triangles. +# +# +# +# +# The threshold or iso-contour value. +# +# +# +# +# Details about the specific marching cubes algorithm +# which was taken to compute the iso-surface. +# The grid is the delocalization grid. +# +# +# +# Reference to the specific implementation of marching cubes used. +# The value placed here should be a DOI. If there are no specific +# DOI or details write not_further_specified, or give at least a +# free-text description. The program and version used is the +# specific paraprobe-nanochem. +# +# +# +# +# +# The resulting triangle soup computed via marching cubes. +# +# +# +# +# +# Integer which specifies the first index to be used for +# distinguishing triangles. Identifiers are defined either +# implicitly or explicitly. For implicit indexing the +# identifiers are defined on the interval +# [identifier_offset, identifier_offset+c-1]. +# +# +# +# +# +# Number of vertices. +# +# +# +# +# Number of faces. +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# identifiers for vertices. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# identifiers for faces. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# +# +# +# +# Positions of the vertices. +# +# Users are encouraged to reduce the vertices to unique set of positions +# and vertices as this supports a more efficient storage of the geometry data. +# It is also possible though to store the vertex positions naively in which +# case vertices_are_unique is likely False. +# Naively here means that one for example stores each vertex of a triangle +# mesh even though many vertices are shared between triangles and thus +# the positions of these vertices do not have to be duplicated. +# +# +# +# +# +# +# +# +# Array of identifiers from vertices which describe each face. +# +# The first entry is the identifier of the start vertex of the first face, +# followed by the second vertex of the first face, until the last vertex +# of the first face. Thereafter, the start vertex of the second face, the +# second vertex of the second face, and so on and so forth. +# +# Therefore, summating over the number_of_vertices, allows to extract +# the vertex identifiers for the i-th face on the following index interval +# of the faces array: [$\sum_i = 0}^{i = n-1}$, $\sum_{i=0}^{i = n}$]. +# +# +# +# +# +# +# +# A list of as many tuples of XDMF topology key, XDMF number +# of vertices and a triple of vertex indices specifying each +# triangle. The total number of entries is n_f_tri * (1+1+3). +# +# +# +# +# +# +# +# +# Direction of each normal. +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its +# primitive each normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# +# +# +# Direction of each normal. +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its +# primitive each normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# Triangle normals are oriented in the direction of the +# gradient vector of the local delocalized scalar field. +# :math:`\sum_{x, y, z} {\nabla{c}_i}^2`. +# +# +# +# +# +# +# +# +# Triangle normals are oriented in the direction of the +# gradient vector of the local delocalized scalar field. +# The projection variable here describes the cosine of the +# angle between the gradient direction and the normal +# direction vector. +# This is a descriptor of how parallel the projection is +# that is especially useful to document those triangles +# for whose projection is almost perpendicular. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of edge length values. For each triangle the edge length +# is reported for the edges traversed according to the sequence +# in which vertices are indexed in triangles. +# +# +# +# +# +# +# +# +# Array of interior angle values. For each triangle the angle +# is reported for the angle opposite to the edges which are +# traversed according to the sequence in which vertices +# are indexed in triangles. +# +# +# +# +# +# +# +# +# The center of mass of each triangle. +# +# +# +# +# +# +# +# +# +# Iso-surfaces of arbitrary scalar three-dimensional fields +# can show a complicated topology. Paraprobe-nanochem can run +# a DBScan-like clustering algorithm which performs a +# connectivity analysis on the triangle soup. This yields a +# set of connected features with their surfaces discretized +# by triangles. Currently, the tool distinguishes at most +# three types of features: +# +# 1. So-called objects, i.e. necessarily watertight features +# represented polyhedra. +# 2. So-called proxies, i.e. features that were replaced by a +# proxy mesh and made watertight. +# 3. Remaining triangle surface meshes of arbitrary shape and +# cardinality. +# +# These features can be interpreted as microstructural features. +# Some of them may be precipitates, some of them may be poles, +# some of them may be segments of dislocation lines or other +# crystal defects which are decorated (or not) with solutes. +# +# +# +# +# The identifier which the triangle_soup connectivity analysis +# returned, which constitutes the first step of the +# volumetric_feature identification process. +# +# +# +# +# +# +# +# The array of keywords of feature_type dictionary. +# +# +# +# +# +# +# +# The array of values for each keyword of the +# feature_type dictionary. +# +# +# +# +# +# +# +# The array of controlled keywords, need to be from +# feature_type_dict_keyword, which specify which type +# each feature triangle cluster belongs to. +# Keep in mind that not each feature is an object or proxy. +# +# +# +# +# +# +# +# The explicit identifier of features. +# +# +# +# +# +# +# +# +# Details for features which are (closed) objects. +# Identifier have to exist in feature_identifier. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# An oriented bounding box (OBB) to each object. +# +# +# +# Edge length of the oriented bounding box from largest +# to smallest value. +# +# +# +# +# +# +# +# +# +# Oriented bounding box aspect ratio. YX versus ZY. +# +# +# +# +# +# +# +# +# Position of the geometric center, which often is but +# not necessarily has to be the center_of_mass of the +# hexahedrally-shaped sample/sample part. +# +# +# +# +# +# +# +# +# +# A simple approach to describe the entire set of hexahedra +# when the main intention is to store the shape of the +# hexahedra for visualization. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details for all those objects close to edge, i.e. those which +# have at least one ion which lays closer to a modelled edge +# of the dataset than threshold. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total (count) relevant for normalization. +# +# +# +# +# +# +# +# +# +# +# +# Count or weight which, when divided by total, +# yields the composition of this element, isotope, +# molecule or ion. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of evaporation_identifier / ion_identifier which +# specify ions laying inside or on the surface of the feature. +# +# +# +# +# +# +# +# +# +# +# Details for all those objects far from edge, i.e. those +# whose ions lay all at least threshold distant from a +# modelled edge of the dataset. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total (count) relevant for normalization. +# +# +# +# +# +# +# +# +# +# +# +# Count or weight which, when divided by total +# yields the composition of this element, isotope, +# molecule or ion. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of evaporation_identifier / ion_identifier which +# specify ions laying inside or on the surface of the feature. +# +# +# +# +# +# +# +# +# +# +# +# +# Details for features which are so-called proxies, i.e. objects +# which have been reconstructed and combinatorially closed with +# processing their partial triangulated_surface_mesh +# (hole filling, refinement). +# Identifier have to exist in feature_identifier. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details for those proxies close to edge, i.e. those which +# have at least one ion which lays closer to a modelled edge +# of the dataset than threshold. +# Identifier have to exist in feature_identifier. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total (count) relevant for normalization. +# +# +# +# +# +# +# +# +# +# Count or weight which, when divided by total +# yields the composition of this element, isotope, +# molecule or ion. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of evaporation_identifier / ion_identifier which +# specify ions laying inside or on the surface of the feature. +# +# +# +# +# +# +# +# +# +# +# Details for those proxies far from edge, i.e. those whose +# ions lay all at least threshold distant from a +# modelled edge of the dataset. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Total (count) relevant for normalization. +# +# +# +# +# +# +# +# +# +# Count or weight which, when divided by total +# yields the composition of this element, isotope, +# molecule or ion. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of evaporation_identifier / ion_identifier which +# specify ions laying inside or on the surface of the feature. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The multiplicity whereby the ion position is accounted for +# irrespective whether the ion is considered as a decorator +# of the interface or not. +# As an example, with atom probe it is typically not possible +# to resolve the positions of the atoms which arrive at the detector +# as molecular ions. Therefore, an exemplar molecular ion of two carbon +# atoms can be considered to have a multiplicity of two to account that +# this molecular ion contributes two carbon atoms at the reconstructed +# location considering that the spatial resolution of atom probe +# experiments is limited. +# +# +# +# +# +# +# +# The multiplicity whereby the ion position is accounted for when +# the ion is considered one which is a decorator of the interface. +# +# +# +# +# +# +# +# The equation of the plane that is fitted initially. +# +# +# +# The four parameter :math:`ax + by + cz + d = 0` which define the plane. +# +# +# +# +# +# +# +# +# The triangle surface mesh representing the interface model. +# Exported at some iteration before the next DCOM step. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Direction of each normal +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its primitive each +# normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# +# +# +# +# Direction of each normal +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its primitive each +# normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of edge length values. For each triangle the edge length is +# reported for the edges traversed according to the sequence +# in which vertices are indexed in triangles. +# +# +# +# +# +# +# +# +# Array of interior angle values. For each triangle the angle is +# reported for the angle opposite to the edges which are traversed +# according to the sequence in which vertices are indexed in triangles. +# +# +# +# +# +# +# +# +# +# The triangle surface mesh representing the interface model. +# Exported at some iteration after the next DCOM step. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Direction of each normal +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its primitive each +# normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# +# +# +# +# Direction of each normal +# +# +# +# +# +# +# +# +# Qualifier how which specifically oriented normal to its primitive each +# normal represents. +# +# * 0 - undefined +# * 1 - outer +# * 2 - inner +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of edge length values. For each triangle the edge length is +# reported for the edges traversed according to the sequence +# in which vertices are indexed in triangles. +# +# +# +# +# +# +# +# +# Array of interior angle values. For each triangle the angle is +# reported for the angle opposite to the edges which are traversed +# according to the sequence in which vertices are indexed in triangles. +# +# +# +# +# +# +# +# +# +# +# +# The ROIs are defined as cylinders for the computations. +# To visualize these though we discretize them into regular n-gons. +# Using for instance a 360-gon, i.e. a regular n-gon with 360 +# edges resolves the lateral surface of each cylinder very finely +# so that they are rendered smoothly in visualization software. +# +# +# +# +# +# Position of the geometric center, which often is but not +# necessarily has to be the center_of_mass of the polyhedra. +# +# +# +# +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# ROI cylinder. Identifiers are defined explicitly. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The number of atoms in each ROI. +# +# +# +# +# +# +# +# The number of ions in each ROI. +# +# +# +# +# +# +# +# The orientation of the ROI defined via a vector which points along +# the cylinder axis and whose length is the height of the cylinder. +# +# +# +# +# +# +# +# +# +# In the direction of the ROI. +# +# +# +# +# Hashvalue +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_ranger.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_ranger.yaml new file mode 100644 index 0000000000..d953ae989d --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_ranger.yaml @@ -0,0 +1,809 @@ +category: application +doc: | + Results of a paraprobe-ranger tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_ivec_max: | + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. +type: group +NXapm_paraprobe_results_ranger(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_ranger] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + exists: optional + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + apply_existent_ranging(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Paraprobe-ranger loads the iontypes and evaluates for each + ion on which iontype it matches. If it matches on none, the + ion is considered of the default unknown type with a 0 as its + respective value in the iontypes array. + + ##MK::number_of_ion_types(NX_POSINT): + maximum_number_of_atoms_per_molecular_ion(NX_POSINT): + unit: NX_UNITLESS + doc: | + The length of the isotope_vector used to describe molecular ions. + ION(NXion): + exists: ['min', '1', 'max', '256'] + isotope_vector(NX_UINT): + nuclid_list(NX_UINT): + exists: recommended + charge_state(NX_INT): + mass_to_charge_range(NX_FLOAT): + iontypes(NX_UINT): + unit: NX_UNITLESS + doc: | + The iontype ID for each ion that was best matching, stored in the + order of the evaporation sequence ID. The here computed iontypes + do not take into account the charge state of the ion which is + equivalent to interpreting a RNG and RRNG range files for each + ion in such a way that only the elements of which a (molecular) ion + is build are considered. By contrast, charged_iontypes takes + into account also the charge state. + dimensions: + rank: 1 + dim: [[1, n_ions]] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies exactly all those ions ranged irrespective + the type they ended up with. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + molecular_ion_search(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Paraprobe-ranger performs a combinatorial search over + all possible or a reduced set of nuclids to identify + into which ions these can be composed. + isotope_vector_matrix(NX_UINT): + unit: NX_UNITLESS + doc: | + The main result is the list of molecular ions, here formatted + according to the definitions of a set of isotope_vectors + as detailed in :ref:`NXion`. + dimensions: + rank: 2 + dim: [[1, i], [2, 32]] + mass_to_charge_state_ratio(NX_FLOAT): + unit: NX_ANY + doc: | + The mass-to-charge-state ratio of each molecular ion + without considering relativistic or quantum effects. + dimensions: + rank: 1 + dim: [[1, i]] + mass(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + The mass of each molecular ion without + considering relativistic or quantum effects. + + # \@units: amu + dimensions: + rank: 1 + dim: [[1, i]] + charge_state(NX_UINT): + unit: NX_CHARGE + doc: | + The charge_state of each molecular ion. + dimensions: + rank: 1 + dim: [[1, i]] + natural_abundance_product(NX_FLOAT): + exists: optional + unit: NX_DIMENSIONLESS + doc: | + The product of the natural abundance of the isotopes building + each molecular ion. Further details are available in + :ref:`NXapm_paraprobe_config_ranger`. + dimensions: + rank: 1 + dim: [[1, i]] + composition_product(NX_FLOAT): + exists: optional + unit: NX_DIMENSIONLESS + doc: | + The product of the natural abundance of the isotopes building + each molecular ion. Further details are available in + :ref:`NXapm_paraprobe_config_ranger`. + dimensions: + rank: 1 + dim: [[1, i]] + number_of_disjoint_nuclids(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + The number of disjoint nuclids for each molecular ion. + dimensions: + rank: 1 + dim: [[1, i]] + number_of_nuclids(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + The number of nuclids for each molecular ion. + dimensions: + rank: 1 + dim: [[1, i]] + check_existent_ranging(NXprocess): + exists: ['min', '0', 'max', '1'] + doc: | + Paraprobe-ranger loads iontypes and evaluates for each ion on which + iontype it matches. If it matches on none, the ion is considered of + the default unknown type with a 0 as its respective value in the + iontypes array. In contrast to use_existent_ranging this process + does neither needs measured ion position nor mass-to-charge-state + ratio values. + + ##MK::number_of_ion_types(NX_POSINT): + maximum_number_of_atoms_per_molecular_ion(NX_POSINT): + unit: NX_UNITLESS + doc: | + The length of the isotope_vector used to describe molecular ions. + charged_ION(NXion): + exists: ['min', '1', 'max', '256'] + isotope_vector(NX_UINT): + nuclid_list(NX_UINT): + exists: recommended + charge_state(NX_INT): + mass_to_charge_range(NX_FLOAT): + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d12fb5165f6decda506bf81f54410afba9e54f22e83c0682ba82fe68d7ddbeee +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# Maximum number of allowed atoms per (molecular) ion (fragment). +# Needs to match maximum_number_of_atoms_per_molecular_ion. +# +# +# +# +# Results of a paraprobe-ranger tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# Paraprobe-ranger loads the iontypes and evaluates for each +# ion on which iontype it matches. If it matches on none, the +# ion is considered of the default unknown type with a 0 as its +# respective value in the iontypes array. +# +# +# +# +# The length of the isotope_vector used to describe molecular ions. +# +# +# +# +# +# +# +# +# +# +# The iontype ID for each ion that was best matching, stored in the +# order of the evaporation sequence ID. The here computed iontypes +# do not take into account the charge state of the ion which is +# equivalent to interpreting a RNG and RRNG range files for each +# ion in such a way that only the elements of which a (molecular) ion +# is build are considered. By contrast, charged_iontypes takes +# into account also the charge state. +# +# +# +# +# +# +# +# A bitmask which identifies exactly all those ions ranged irrespective +# the type they ended up with. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# +# Paraprobe-ranger performs a combinatorial search over +# all possible or a reduced set of nuclids to identify +# into which ions these can be composed. +# +# +# +# The main result is the list of molecular ions, here formatted +# according to the definitions of a set of isotope_vectors +# as detailed in :ref:`NXion`. +# +# +# +# +# +# +# +# +# The mass-to-charge-state ratio of each molecular ion +# without considering relativistic or quantum effects. +# +# +# +# +# +# +# +# The mass of each molecular ion without +# considering relativistic or quantum effects. +# +# +# +# +# +# +# +# +# The charge_state of each molecular ion. +# +# +# +# +# +# +# +# The product of the natural abundance of the isotopes building +# each molecular ion. Further details are available in +# :ref:`NXapm_paraprobe_config_ranger`. +# +# +# +# +# +# +# +# The product of the natural abundance of the isotopes building +# each molecular ion. Further details are available in +# :ref:`NXapm_paraprobe_config_ranger`. +# +# +# +# +# +# +# +# The number of disjoint nuclids for each molecular ion. +# +# +# +# +# +# +# +# The number of nuclids for each molecular ion. +# +# +# +# +# +# +# +# +# Paraprobe-ranger loads iontypes and evaluates for each ion on which +# iontype it matches. If it matches on none, the ion is considered of +# the default unknown type with a 0 as its respective value in the +# iontypes array. In contrast to use_existent_ranging this process +# does neither needs measured ion position nor mass-to-charge-state +# ratio values. +# +# +# +# +# The length of the isotope_vector used to describe molecular ions. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_selector.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_selector.yaml new file mode 100644 index 0000000000..01e5d7073c --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_selector.yaml @@ -0,0 +1,517 @@ +category: application +doc: | + Results of a paraprobe-selector tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. +type: group +NXapm_paraprobe_results_selector(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_selector] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + exists: optional + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset + were selected to become included in the region-of-interest (ROI). + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 2e31b6b35f88d64a75b245dc46eb1d9fb155c7d641a927710b53367d6395394e +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# Results of a paraprobe-selector tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# A bitmask which identifies which of the ions in the dataset +# were selected to become included in the region-of-interest (ROI). +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_spatstat.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_spatstat.yaml new file mode 100644 index 0000000000..5a8d6e697b --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_spatstat.yaml @@ -0,0 +1,687 @@ +category: application +doc: | + Results of a paraprobe-spatstat tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. +type: group +NXapm_paraprobe_results_spatstat(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_spatstat] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + exists: optional + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + iontypes_randomized(NX_UINT): + unit: NX_UNITLESS + doc: | + The iontype ID for each ion that was assigned to each ion during + the randomization of the ionlabels. Iontype labels are just permuted + but the total number of values for each iontype stay the same. + + The order matches the iontypes array from a given ranging results + as is specified in the configuration settings inside the specific + config_filename that was used for this spatstat analysis. + dimensions: + rank: 1 + dim: [[1, n_ions]] + knn(NXprocess): + exists: optional + doc: | + K-nearest neighbor statistics. + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Right boundary of the binning. + dimensions: + rank: 1 + dim: [[1, i]] + probability_mass(NX_FLOAT): + unit: NX_DIMENSIONLESS + dimensions: + rank: 1 + dim: [[1, i]] + cumulated(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Cumulated + dimensions: + rank: 1 + dim: [[1, i]] + cumulated_normalized(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Cumulated and normalized by total counts + dimensions: + rank: 1 + dim: [[1, i]] + rdf(NXprocess): + exists: optional + doc: | + Radial distribution statistics. + distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Right boundary of the binning. + dimensions: + rank: 1 + dim: [[1, i]] + probability_mass(NX_FLOAT): + unit: NX_DIMENSIONLESS + dimensions: + rank: 1 + dim: [[1, i]] + cumulated(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Cumulated + dimensions: + rank: 1 + dim: [[1, i]] + cumulated_normalized(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Cumulated and normalized by total counts + dimensions: + rank: 1 + dim: [[1, i]] + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 224c4d79678a47bb6e07b21f6ad8592f7f0cd10f4daac6ccd71127d064185b13 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# Results of a paraprobe-spatstat tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# The iontype ID for each ion that was assigned to each ion during +# the randomization of the ionlabels. Iontype labels are just permuted +# but the total number of values for each iontype stay the same. +# +# The order matches the iontypes array from a given ranging results +# as is specified in the configuration settings inside the specific +# config_filename that was used for this spatstat analysis. +# +# +# +# +# +# +# +# K-nearest neighbor statistics. +# +# +# +# Right boundary of the binning. +# +# +# +# +# +# +# +# +# +# +# +# +# Cumulated +# +# +# +# +# +# +# +# Cumulated and normalized by total counts +# +# +# +# +# +# +# +# +# Radial distribution statistics. +# +# +# +# Right boundary of the binning. +# +# +# +# +# +# +# +# +# +# +# +# +# Cumulated +# +# +# +# +# +# +# +# Cumulated and normalized by total counts +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_surfacer.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_surfacer.yaml new file mode 100644 index 0000000000..f865daed53 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_surfacer.yaml @@ -0,0 +1,935 @@ +category: application +doc: | + Results of a paraprobe-surfacer tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_v_tri: | + The number of vertices of the alpha complex. + n_f_tri: | + The number of faces of the alpha complex. + n_f_tri_xdmf: | + The total number of XDMF values to represent all faces of triangles via XDMF. + n_f_tet_xdmf: | + The total number of XDMF values to represent all faces of tetrahedra via XDMF. +type: group +NXapm_paraprobe_results_surfacer(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_surfacer] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed. Computations of alpha complexes may have filtered this + ion set further but this process is deterministic. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. The mask may be 0 for most. + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + POINT_SET_WRAPPING(NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Paraprobe-surfacer can be used to load a ROI that is the entire or a + sub-set of the ion point cloud. In the point_cloud_wrapping process + the tool computes a triangulated surface mesh which encloses the + ROI/point cloud. This mesh can be seen as a model for the edge of + the dataset. + Different algorithms can be used with paraprobe-surfacer to create + this mesh such as convex hulls, alpha-shapes as their generalization, + or alpha wrappings. + Ideally, the resulting mesh should be a watertight polyhedron. + This polyhedron is not necessarily convex. For some algorithms there + is no guarantee that the resulting mesh yields a watertight mesh. + + # (NXcg_grid): currently we do not store the underlying grid + # for eventually performed preprocessing + alpha_complex(NXcg_alpha_complex): + exists: ['min', '0', 'max', 'unbounded'] + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies exactly all those ions whose positions + were considered when defining the filtered point set from which + the alpha complex was then in fact computed. This window + can be different to the entire window as irrelevant ions might + have been filtered out to reduce the computational costs of the + alpha complex analysis. + + # filtered in addition to the ROI or again the entire dataset + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + dimensionality(NX_UINT): + unit: NX_UNITLESS + enumeration: [2, 3] + type: + enumeration: [convex_hull, alpha_shape, alpha_wrapping, other, undefined] + mode: + enumeration: [general, regularized] + alpha(NX_NUMBER): + unit: NX_LENGTH + offset(NX_NUMBER): + exists: optional + unit: NX_LENGTH + triangle_set(NXcg_triangle_set): + exists: optional + doc: | + The set of triangles in the coordinate system paraprobe + which discretizes the exterior surface of the alpha complex. + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + triangles. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + triangles(NXcg_face_list_data_structure): + dimensionality(NX_POSINT): + unit: NX_UNITLESS + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of vertices. + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of faces. + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v_tri], [2, 3]] + faces(NX_UINT): + unit: NX_UNITLESS + dimensions: + rank: 2 + dim: [[1, n_f_tri], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tri * (1+1+3). + dimensions: + rank: 1 + dim: [[1, n_f_tri_xdmf]] + is_watertight(NX_BOOLEAN): + exists: optional + doc: | + Do the triangles define a triangulated surface mesh which + is watertight? + volume(NX_FLOAT): + exists: optional + unit: NX_VOLUME + doc: | + The volume which the triangulated surface mesh encloses + provided that the mesh is watertight. + interior_tetrahedra(NXcg_tetrahedron_set): + exists: optional + doc: | + The set of tetrahedra which represent the interior volume of the + complex if that is a closed 2-manifold. + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distin- + guishing tetrahedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined + on the interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + volume(NX_FLOAT): + exists: optional + unit: NX_VOLUME + doc: | + The accumulated volume of all interior tetrahedra. + tetrahedra(NXcg_face_list_data_structure): + exists: optional + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of vertices. + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of faces. + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, n_v_tet], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of as many tuples of XDMF topology key, XDMF number + of vertices and a triple of vertex indices specifying each + triangle. The total number of entries is n_f_tet * (1+1+4). + dimensions: + rank: 1 + dim: [[1, n_f_tet_xdmf]] + TRIANGLE_SET_WRAPPING(NXprocess): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + In the future we may want to wrap other primitives + like triangles or polylines. + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9d0676f28ebba35d9a70595e9c692a6506d83179dc6cf2b8bb5d9dba669ce196 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# The number of vertices of the alpha complex. +# +# +# +# +# The number of faces of the alpha complex. +# +# +# +# +# The total number of XDMF values to represent all faces of triangles via XDMF. +# +# +# +# +# The total number of XDMF values to represent all faces of tetrahedra via XDMF. +# +# +# +# +# Results of a paraprobe-surfacer tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed. Computations of alpha complexes may have filtered this +# ion set further but this process is deterministic. +# +# +# +# Number of ions covered by the mask. The mask may be 0 for most. +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# Paraprobe-surfacer can be used to load a ROI that is the entire or a +# sub-set of the ion point cloud. In the point_cloud_wrapping process +# the tool computes a triangulated surface mesh which encloses the +# ROI/point cloud. This mesh can be seen as a model for the edge of +# the dataset. +# Different algorithms can be used with paraprobe-surfacer to create +# this mesh such as convex hulls, alpha-shapes as their generalization, +# or alpha wrappings. +# Ideally, the resulting mesh should be a watertight polyhedron. +# This polyhedron is not necessarily convex. For some algorithms there +# is no guarantee that the resulting mesh yields a watertight mesh. +# +# +# +# +# +# A bitmask which identifies exactly all those ions whose positions +# were considered when defining the filtered point set from which +# the alpha complex was then in fact computed. This window +# can be different to the entire window as irrelevant ions might +# have been filtered out to reduce the computational costs of the +# alpha complex analysis. +# +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The set of triangles in the coordinate system paraprobe +# which discretizes the exterior surface of the alpha complex. +# +# +# +# Integer which specifies the first index to be used for distinguishing +# triangles. Identifiers are defined either implicitly or explicitly. +# For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# +# +# +# +# +# +# Number of vertices. +# +# +# +# +# Number of faces. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A list of as many tuples of XDMF topology key, XDMF number +# of vertices and a triple of vertex indices specifying each +# triangle. The total number of entries is n_f_tri * (1+1+3). +# +# +# +# +# +# +# +# +# Do the triangles define a triangulated surface mesh which +# is watertight? +# +# +# +# +# The volume which the triangulated surface mesh encloses +# provided that the mesh is watertight. +# +# +# +# +# +# The set of tetrahedra which represent the interior volume of the +# complex if that is a closed 2-manifold. +# +# +# +# Integer which specifies the first index to be used for distin- +# guishing tetrahedra. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined +# on the interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# The accumulated volume of all interior tetrahedra. +# +# +# +# +# +# Number of vertices. +# +# +# +# +# Number of faces. +# +# +# +# +# +# +# +# +# +# +# +# +# A list of as many tuples of XDMF topology key, XDMF number +# of vertices and a triple of vertex indices specifying each +# triangle. The total number of entries is n_f_tet * (1+1+4). +# +# +# +# +# +# +# +# +# +# +# +# In the future we may want to wrap other primitives +# like triangles or polylines. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_tessellator.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_tessellator.yaml new file mode 100644 index 0000000000..351fd374a5 --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_tessellator.yaml @@ -0,0 +1,1284 @@ +category: application +doc: | + Results of a paraprobe-tessellator tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_f_xdmf: | + The total number of facets/polygons defining the tessellation. +type: group +NXapm_paraprobe_results_tessellator(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_tessellator] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + (NXprocess): + exists: ['min', '0', 'max', '1'] + voronoi_tessellation(NXprocess): + doc: | + The tool can be used to compute a Voronoi tessellation the entire + or a sub-set of the reconstruction. The point cloud in the ROI is + wrapped into a tight axis-aligned bounding box. The tool detects if + Voronoi cells make contact with the walls of this bounding box. + The tessellation is computed without periodic boundary conditions. + window(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of the ions in the dataset were + analyzed. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of ions covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, n_ions]] + wall_contact_global(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by the global axis-aligned bounding box, i.e. boundaries + of the threads are ignored. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + + ##MK::optional documenting of touching on thread-local boundaries + wall_contact_left(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the negative x axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + wall_contact_right(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The right wall has the positive x axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + wall_contact_front(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The front wall has the negative y axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + wall_contact_rear(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The rear wall has the positive y axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + wall_contact_bottom(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the negative z axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + wall_contact_top(NXcs_filter_boolean_mask): + doc: | + A bitmask which identifies which of points have Voronoi cells that + are truncated by a specific wall of the axis-aligned bounding box. + The left wall has the positive z axis of the paraprobe coordinate + system as the outer unit normal. + number_of_ions(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of points covered by the mask. + The mask value for most may be 0. + + # which does paraprobe use + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The unsigned integer array representing the content of the mask. + If padding is used the padded bits are set to 0. The mask is for + convenience always as large as the entire dataset as it will + be stored compressed anyway. The convenience feature with this + is that then the mask can be decoded with numpy and mirrored + against the evaporation_id array and one immediately can filter + out all points that were used by the paraprobe. + The length of the array adds to the next unsigned integer + if the number of ions in the dataset is not an integer + multiple of the bitdepth. + dimensions: + rank: 1 + dim: [[1, i]] + voronoi_cells(NXcg_polyhedron_set): + exists: optional + dimensionality(NX_POSINT): + unit: NX_UNITLESS + enumeration: [3] + cardinality(NX_POSINT): + unit: NX_UNITLESS + volume(NX_NUMBER): + unit: NX_VOLUME + doc: | + Interior volume + dimensions: + rank: 1 + dim: [[1, i]] + process_identifier(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + By which MPI process was the Voronoi cell computed. + dimensions: + rank: 1 + dim: [[1, i]] + thread_identifier(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + By which OpenMP thread was the Voronoi cell computed. + dimensions: + rank: 1 + dim: [[1, i]] + number_of_faces(NX_POSINT): + exists: optional + unit: NX_UNITLESS + doc: | + The number of faces for each polyhedron. Faces of adjoining polyhedra + are counted for each polyhedron. This field can be used to interpret + the array/field with the individual area values for each face. + dimensions: + rank: 1 + dim: [[1, i]] + + # (NXtransformations): + # exists: optional + # doc: | + # Reference to or definition of a coordinate system with + # which the qualifiers and mesh data are interpretable. + # substantially more detailed descriptors of the shape, the mesh + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + polyhedra. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + identifier(NX_INT): + exists: optional + unit: NX_UNITLESS + doc: | + Integer used to distinguish polyhedra for explicit indexing. + dimensions: + rank: 1 + dim: [[1, i]] + polyhedra(NXcg_face_list_data_structure): + exists: ['min', '0', 'max', '1'] + doc: | + A simple approach to describe the entire set of polyhedra when + the main intention is to store the shape of the polyhedra for + visualization. + dimensionality(NX_POSINT): + unit: NX_UNITLESS + number_of_vertices(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of vertices. + number_of_faces(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of faces. + vertex_identifier_offset(NX_INT): + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + unit: NX_UNITLESS + vertices(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, i], [2, 3]] + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + A sequence of always first an XDMF topology type key, followed + by the XDMF number of vertices of the polygon, followed by + the vertex identifier which define the facet polygon. First + we store the polygon of the first facet of the first cell, then + the second facet of the first cell, until the last facet of the + first cell, followed by the first facet of the second cell, + and so on and so forth. + dimensions: + rank: 1 + dim: [[1, j]] + xdmf_cell_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + A sequence of cell identifier so that each facet is associated + with its cell because of which it is then possible to segment + out cells three-dimensionally based on cell i.e. evaporation_id. + dimensions: + rank: 1 + dim: [[1, n_f_xdmf]] + + ##MK::end of the tool-specific section + performance(NXcs_profiling): + exists: recommended + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8ec5c3b4cc5fa3566c8de12c5be7e9e8690840d962a5ee897b491e67196f1ea0 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# The total number of facets/polygons defining the tessellation. +# +# +# +# +# Results of a paraprobe-tessellator tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# The tool can be used to compute a Voronoi tessellation the entire +# or a sub-set of the reconstruction. The point cloud in the ROI is +# wrapped into a tight axis-aligned bounding box. The tool detects if +# Voronoi cells make contact with the walls of this bounding box. +# The tessellation is computed without periodic boundary conditions. +# +# +# +# A bitmask which identifies which of the ions in the dataset were +# analyzed. +# +# +# +# Number of ions covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by the global axis-aligned bounding box, i.e. boundaries +# of the threads are ignored. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The left wall has the negative x axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The right wall has the positive x axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The front wall has the negative y axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The rear wall has the positive y axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The left wall has the negative z axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# A bitmask which identifies which of points have Voronoi cells that +# are truncated by a specific wall of the axis-aligned bounding box. +# The left wall has the positive z axis of the paraprobe coordinate +# system as the outer unit normal. +# +# +# +# Number of points covered by the mask. +# The mask value for most may be 0. +# +# +# +# +# +# Number of bits assumed matching on a default datatype. +# (e.g. 8 bits for a C-style uint8). +# +# +# +# +# The unsigned integer array representing the content of the mask. +# If padding is used the padded bits are set to 0. The mask is for +# convenience always as large as the entire dataset as it will +# be stored compressed anyway. The convenience feature with this +# is that then the mask can be decoded with numpy and mirrored +# against the evaporation_id array and one immediately can filter +# out all points that were used by the paraprobe. +# The length of the array adds to the next unsigned integer +# if the number of ions in the dataset is not an integer +# multiple of the bitdepth. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Interior volume +# +# +# +# +# +# +# +# By which MPI process was the Voronoi cell computed. +# +# +# +# +# +# +# +# By which OpenMP thread was the Voronoi cell computed. +# +# +# +# +# +# +# +# The number of faces for each polyhedron. Faces of adjoining polyhedra +# are counted for each polyhedron. This field can be used to interpret +# the array/field with the individual area values for each face. +# +# +# +# +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# polyhedra. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# +# +# +# Integer used to distinguish polyhedra for explicit indexing. +# +# +# +# +# +# +# +# A simple approach to describe the entire set of polyhedra when +# the main intention is to store the shape of the polyhedra for +# visualization. +# +# +# +# +# Number of vertices. +# +# +# +# +# Number of faces. +# +# +# +# +# +# +# +# +# +# +# +# +# A sequence of always first an XDMF topology type key, followed +# by the XDMF number of vertices of the polygon, followed by +# the vertex identifier which define the facet polygon. First +# we store the polygon of the first facet of the first cell, then +# the second facet of the first cell, until the last facet of the +# first cell, followed by the first facet of the second cell, +# and so on and so forth. +# +# +# +# +# +# +# +# A sequence of cell identifier so that each facet is associated +# with its cell because of which it is then possible to segment +# out cells three-dimensionally based on cell i.e. evaporation_id. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXapm_paraprobe_results_transcoder.yaml b/contributed_definitions/nyaml/NXapm_paraprobe_results_transcoder.yaml new file mode 100644 index 0000000000..00b4211f2a --- /dev/null +++ b/contributed_definitions/nyaml/NXapm_paraprobe_results_transcoder.yaml @@ -0,0 +1,1080 @@ +category: application +doc: | + Results of a paraprobe-transcoder tool run. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + The total number of ions in the reconstruction. + n_ivec_max: | + Maximum number of allowed atoms per (molecular) ion (fragment). + Needs to match maximum_number_of_atoms_per_molecular_ion. + n_ranges: | + Number of mass-to-charge-state-ratio intervals mapped on this ion type. + n_topology: | + Total number of integers in the supplementary XDMF topology array. + n_combinatorics: | + Number of ions probed in the combinatorial analysis of the charge states + +# be careful n_comb can vary for every instance of (NXion) ! +type: group +NXapm_paraprobe_results_transcoder(NXobject): + + # by default for appdefs the value of the exists keyword is required + # unless it is explicitly specified differently + (NXentry): + exists: ['min', '1', 'max', '1'] + \@version: + doc: | + Version specifier of this application definition. + + ##MK::begin of the tool-specific section + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXapm_paraprobe_results_transcoder] + + ##MK::end of the tool-specific section + program: + doc: | + Given name of the program/software/tool with which this NeXus + (configuration) file was generated. + \@version: + doc: | + Ideally program version plus build number, or commit hash or description + of ever persistent resources where the source code of the program and + build instructions can be found so that the program can be configured + ideally in such a manner that the result of this computational process + is recreatable in the same deterministic manner. + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + was started, i.e. the paraprobe-tool executable started as a process. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when the analysis behind this results file + were completed and the paraprobe-tool executable exited as a process. + config_filename: + doc: | + The absolute path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the paraprobe-tool executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + (NXuser): + exists: recommended + doc: | + If used, contact information and eventually details + of at least the person who performed this analysis. + name: + affiliation: + exists: recommended + address: + exists: optional + email: + exists: recommended + orcid: + exists: recommended + orcid_platform: + exists: recommended + telephone_number: + exists: optional + role: + exists: recommended + social_media_name: + exists: optional + social_media_platform: + exists: optional + (NXcoordinate_system_set): + doc: | + Details about the coordinate system conventions used. + (NXtransformations): + exists: ['min', '1', 'max', 'unbounded'] + doc: | + The individual coordinate systems which should be used. + Field names should be prefixed with the following controlled terms + indicating which individual coordinate system is described: + + * paraprobe + * lab + * specimen + * laser + * leap + * detector + * recon + + ##MK::begin of the tool-specific section + visualization(NXprocess): + exists: recommended + xdmf_topology(NX_UINT): + unit: NX_UNITLESS + doc: | + An array of triplets of integers which can serve as a supplementary + array for Paraview to display the reconstruction. The XDMF datatype + is here 1, the number of primitives 1 per triplet, the last integer + in each triplet is the identifier of each point starting from zero. + dimensions: + rank: 1 + dim: [[1, n_topology]] + + # n_topology == 3*n_ions + # not in all cases a PARAPROBE.Transcoder.Results.SimID..h5 is required + # namely when an NXapm-compliant NeXus file is directly used for interacting + # with paraprobe tools in all other cases, the PARAPROBE.Transcoder.Results + # file will get an *.nxs file ending + # the original proposal + # results(NXprocess): + # exists: [min, 1, max, 1] + # doc: | + # Paraprobe-transcoder prepares the data in POS, ePOS, APT files from + # APSuite, RRNG, RNG, and NeXus/HDF5 NXapm in such a way that they can + # be used with the tools of the paraprobe-toolbox. + # reconstruction(NXcg_point_set): + # dimensionality(NX_POSINT): + # cardinality(NX_POSINT): + # identifier_offset(NX_INT): + # position(NX_NUMBER): + # ##MK::number_of_ion_types(NX_POSINT): + # ##MK::maximum_number_of_atoms_per_molecular_ion(NX_POSINT): + # ranging(NXcollection): + # exists: [min, 1, max, 256] + # doc: | + # This is the collection of iontypes distinguished. + # The default unknown iontype always has to map to 0. + # Its non-physical mass_to_charge_state_ratio is [0., 0.001] Da. + # ion_type(NX_UINT): + # exists: optional + # isotope_vector(NX_UINT): + # nuclid_list(NX_UINT): + # exists: recommended + # charge_state(NX_INT): + # name: + # exists: optional + # mass_to_charge_range(NX_FLOAT): + # the key problem still for apm is people use different formats + # when people would like to use paraprobe without nomad and pos, epos, apt + # rrng and rng files the data have to be transcoded, this is the main + # reason for having the transcoder however, when you already have an NXapm + # file (like) in nomad, why should we create yet another format here the + # transcoder is not needed + # namely take e.g. paraprobe-nanochem all it needs to know is the place of + # an HDF5 file where the nanochem tool knows there will be groups in this file + # with entry/atom_probe/reconstruction/reconstructed_positions + # and entry/atom_probe/ranging/peak_identification and a set of NXion + # this suggest the need for three fundamental changes: + # if transcoder config gets an nxs file as input it just checks if + # the above-mentioned groups are available, if yes it accepts and + # guides that no transcoding is needed any longer + # if transcoder config gets other files it creates the above-mentioned + # groups in different places than it does currently + # convenience functions of tools have to be changed in the following way: + # you hunt for PARAPROBE.Transcoder.Config.SimID..h5 + # if the references to dataset files there end with nxs you know + # data are in an NXapm so reconstruction will be in + # entry/atom_probe/reconstruction/reconstructed_positions + # ranging will be in + # entry/atom_probe/ranging/peak_identification + # however if the references to dataset files there end with != nxs + # you point the tool to in fact data inside PARAPROBE.Transcoder.Results + # because in this case transcoding was necessary but also then you + # will find the data in entry/atom_probe/.. respectively + # alternatively: + atom_probe(NXinstrument): + doc: | + On a mid term perspective we would like to evolve the paraprobe-toolbox + to an implementation stage where it works exclusively with completely + provenance-tracked formats for both the configuration of the workflow step + and/or analysis with each tool and also for the output of these analyses + in the form of so-called tool-specific results files. + Currently the Hierarchical Data Format 5 (HDF5) is used to store such data. + + Different file formats can be used to inject reconstructed datasets and + ranging definitions into the toolbox. Traditionally, these are the POS, + ePOS, and APT files with the tomographic reconstruction and other metadata + and RNG and RRNG file formats for the ranging definitions how mass-to-charge + state-ratio values map on (molecular) ion types. Such input should be + injected via specific NeXus/HDF5 files which are documented + in compliance with the NXapm application definition. + + So far the paraprobe-toolbox was used as a standalone tool. Therefore, it + was not relevant during the development to focus on interoperability. + Essentially paraprobe-transcoder was used as a parser to transcode data + in the above-mentioned file formats into a paraprobe-specific + representation. This transcoding should become deprecated. + Here we describe steps we have taken into this direction. + + With the work in the FAIRmat project and the desire to make the paraprobe- + toolbox also accessible as a cloud-computing capable service in the Nomad + Remote Tools Hub (NORTH) the topic of interoperability became more important + and eventually the NXapm application definition was proposed. + NORTH is a GUI and related service in a NOMAD OASIS instance which allows + to spawn preconfigured docker containers via JupyterHub. + Currently, NORTH includes the so-called apm container. A container with + tools specific for analyzing data from atom probe microscopy as well as + processing of point cloud and mesh data. + + The NXapm application definition and related implementation work within + NOMAD OASIS enabled users to parse content of POS, ePOS, APT, RNG, and + RRNG files, surplus key metadata from vendor-agnostic electronic lab notebook + solutions directly into NOMAD OASIS via the uploads section. + The process is automated and yields an NXapm-compliant NeXus/HDF5 file + inside the uploads section in return. + + With these improvements made there is no longer a need for - at least the + users of a NOMAD OASIS and NORTH instance to use the deprecated + PARAPROBE.Transcoder.Results.*.h5 files. Ideally, paraprobe should + automatically detect that the input can now be an NXapm-compliant NeXus/HDF5 + file and in response work with this file directly. + To remain compliant with users however who do not have or do not wish + to use a NOMAD OASIS or NXapm or NeXus at all right now, the solution is + as follows: + + Calling the configuration stage of paraprobe-transcoder is always mandatory. + It is always the first step of working with the toolbox. In this process + the user defines the input files. These can either be nxs i.e. the NXapm/NeXus/ + HDF5 file from e.g. the upload section, or such a file that was obtained from + a colleague with a NOMAD OASIS instance. + In all other cases, users can pass the reconstruction and ranging definitions + using the traditional POS, ePOS, or APT and RNG or RRNG file formats respectively. + + Based on which input the user delivers, the parmsetup-transcoder tool then + creates a configuration file PARAPROBE.Transcoder.Config.SimID.*.nxs and + informs the user whether the input was NeXus (and thus if all relevant + input is already available) or whether the paraprobe-transcoder tool needs + to be executed to convert the content of the vendor files first into a + format which paraprobe can provenance track and understand. + In the latter case, the PARAPROBE.Transcoder.Config.SimID.*.nxs file is + used to communicate to all subsequently used tools from which files + the tools can expect to find the reconstruction and ranging definitions. + + All subsequent analysis steps start also with a tool-specific configuration. + This configuration step reads in (among others) the + PARAPROBE.Transcoder.Config.SimID.*.nxs file from which the configuration + tool identifies automatically whether to read the reconstruction and ranging data + from PARAPROBE.Transcoder.Results.SimID.*.h5 or directly the NXapm-compliant + NeXus/HDF5 file that was created upon preparing the upload or the file shared + from a colleague. This design removes the need for unnecessary copies of the data. + Currently still though users should execute the transcoder step as it will + generate a supplementary XDMF topology field with which the data in either + the NeXus/HDF5 or the transcoded vendor files can be displayed using e.g. + Paraview. For this purpose XDMF is used. + + Of course ideally the APT community would at some point converge to use + a common data exchange file format. To this end, AMETEK/Cameca's APT file format + could be a good starting point but so far it is lacking a consistent way of + how to store generalized ranging definitions and post-processing results. + POS, ePOS, Rouen's ATO, as well as other so far used representations of data + like CSV or text files have, to the best of our current knowledge, no + concept of how to marry reconstruction and (optional) ranging data into + one self-descriptive format. + + This summarizes the rationale behind the current choices of the I/O for + paraprobe. Furthermore, this summarizes also why the fundamental design + of splitting an analysis always into steps of configuration (with parmsetup), + task execution (with the respective C/C++ or Python tool of the toolbox), + and post-processing (e.g. with autoreporter) is useful because it offers + a clear description of provenance tracking. This is a necessary step to make + atom probe microscopy data at all better aligned with the aims of the + FAIR principles. + + The internal organization of the data entries in the atom_probe group + in this application definition for paraprobe-transcoder results files + mirror the definitions of the NXapm for consistency reasons. + + # APSuite, RRNG, RNG, and NeXus/HDF5 NXapm in such a way that they can + # be used with the tools of the paraprobe-toolbox. + mass_to_charge_conversion(NXprocess): + mass_to_charge(NX_FLOAT): + unit: NX_ANY + doc: | + Mass-to-charge-state ratio values. + + # \@units: Da + dimensions: + rank: 1 + dim: [[1, n_ions]] + reconstruction(NXprocess): + + # number_of_ions(NX_UINT): + # doc: | + # For now still a support field to store the total number of ions in the + # dataset. This field will become deprecated when the new HDF5 I/O routines + # come in place which detect the metadata to an entry automatically. + # For now has to be the same value as n_ions. + reconstructed_positions(NX_FLOAT): + unit: NX_LENGTH + doc: | + Three-dimensional reconstructed positions of the ions. + Interleaved array of x, y, z positions in the specimen space. + dimensions: + rank: 2 + dim: [[1, n_ions], [2, 3]] + ranging(NXprocess): + peak_identification(NXprocess): + doc: | + Details about how peaks, with taking into account + error models, were interpreted as ion types or not. + (NXion): + exists: ['min', '1', 'max', '256'] + isotope_vector(NX_UINT): + nuclid_list(NX_UINT): + exists: recommended + charge_state(NX_INT): + mass_to_charge_range(NX_FLOAT): + charge_model(NXprocess): + doc: | + Details and results of the combinatorial analyses of this + range definition to identify the charge_state for an ion. + charge_vector(NX_UINT): + unit: NX_UNITLESS + doc: | + Currently charge_state not charge! + dimensions: + rank: 1 + dim: [[1, n_combinatorics]] + isotope_matrix(NX_UINT): + unit: NX_UNITLESS + doc: | + Specific isotopes building each candidate matching the range. + dimensions: + rank: 2 + dim: [[1, n_combinatorics], [2, n_ivec_max]] + mass_vector(NX_FLOAT): + unit: NX_ANY + doc: | + Accumulated mass of the isotopes in each candidate. + Not corrected for quantum effects. + dimensions: + rank: 1 + dim: [[1, n_combinatorics]] + + # min_abundance(NX_FLOAT): + # doc: | + # Minimum natural abundance + # unit: NX_DIMENSIONLESS + natural_abundance_product_vector(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Product of natural abundance of the isotopes per candidate. + dimensions: + rank: 1 + dim: [[1, n_combinatorics]] + min_abundance_product(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Filter criterion on the product of the natural abundances + computed from each isotope building the (molecular) ion. + Such a filter can be used to reduce the number of possible + molecular ions considered when trying to find a unique solution + to the question which charge_state does a molecular ion + within a given range and given combination of elements have. + min_half_life(NX_FLOAT): + unit: NX_TIME + doc: | + Filter criterion on the minimum half life which all isotopes + building the (molecular) ion need to have to consider the + candidate. + Such a filter can be used to reduce the number of possible + molecular ions considered when trying to find a unique solution + to the question which charge_state does a molecular ion + within a given range and given combination of elements have. + + # NEW ISSUE: value can be the string infinity! + # min_half_life_vector(NX_FLOAT): + # doc: | + # Needs to be documented + # unit: NX_TIME + sacrifice_isotopic_uniqueness(NX_BOOLEAN): + doc: | + If the value is zero/false it means that non-unique solutions + are accepted. These are solutions where multiple candidates + differ in their isotopes but have the same charge. + + # add further fields coming from using the charge state recovery + # workflow from the ifes_apt_tc_data_modeling library + ##MK::end of the tool-specific section + performance(NXcs_profiling): + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# dc03e6cf382ef885356e95ad6889162c3ded9664dea8344499decc097be77690 +# +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The total number of ions in the reconstruction. +# +# +# +# +# Maximum number of allowed atoms per (molecular) ion (fragment). +# Needs to match maximum_number_of_atoms_per_molecular_ion. +# +# +# +# +# Number of mass-to-charge-state-ratio intervals mapped on this ion type. +# +# +# +# +# Total number of integers in the supplementary XDMF topology array. +# +# +# +# +# Number of ions probed in the combinatorial analysis of the charge states +# +# +# +# +# Results of a paraprobe-transcoder tool run. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# Given name of the program/software/tool with which this NeXus +# (configuration) file was generated. +# +# +# +# Ideally program version plus build number, or commit hash or description +# of ever persistent resources where the source code of the program and +# build instructions can be found so that the program can be configured +# ideally in such a manner that the result of this computational process +# is recreatable in the same deterministic manner. +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# was started, i.e. the paraprobe-tool executable started as a process. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when the analysis behind this results file +# were completed and the paraprobe-tool executable exited as a process. +# +# +# +# +# The absolute path and name of the config file for this analysis. +# +# +# +# At least SHA256 strong hash of the specific config_file for +# tracking provenance. +# +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# A statement whether the paraprobe-tool executable managed to +# process the analysis or failed prematurely. +# +# This status is written to the results file after the end_time +# at which point the executable must not compute any analysis. +# Only when this status message is present and shows `success`, the +# user should consider the results. In all other cases it might be +# that the executable has terminated prematurely or another error +# occurred. +# +# +# +# +# +# +# +# +# If used, contact information and eventually details +# of at least the person who performed this analysis. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Details about the coordinate system conventions used. +# +# +# +# The individual coordinate systems which should be used. +# Field names should be prefixed with the following controlled terms +# indicating which individual coordinate system is described: +# +# * paraprobe +# * lab +# * specimen +# * laser +# * leap +# * detector +# * recon +# +# +# +# +# +# +# +# An array of triplets of integers which can serve as a supplementary +# array for Paraview to display the reconstruction. The XDMF datatype +# is here 1, the number of primitives 1 per triplet, the last integer +# in each triplet is the identifier of each point starting from zero. +# +# +# +# +# +# +# +# +# +# On a mid term perspective we would like to evolve the paraprobe-toolbox +# to an implementation stage where it works exclusively with completely +# provenance-tracked formats for both the configuration of the workflow step +# and/or analysis with each tool and also for the output of these analyses +# in the form of so-called tool-specific results files. +# Currently the Hierarchical Data Format 5 (HDF5) is used to store such data. +# +# Different file formats can be used to inject reconstructed datasets and +# ranging definitions into the toolbox. Traditionally, these are the POS, +# ePOS, and APT files with the tomographic reconstruction and other metadata +# and RNG and RRNG file formats for the ranging definitions how mass-to-charge +# state-ratio values map on (molecular) ion types. Such input should be +# injected via specific NeXus/HDF5 files which are documented +# in compliance with the NXapm application definition. +# +# So far the paraprobe-toolbox was used as a standalone tool. Therefore, it +# was not relevant during the development to focus on interoperability. +# Essentially paraprobe-transcoder was used as a parser to transcode data +# in the above-mentioned file formats into a paraprobe-specific +# representation. This transcoding should become deprecated. +# Here we describe steps we have taken into this direction. +# +# With the work in the FAIRmat project and the desire to make the paraprobe- +# toolbox also accessible as a cloud-computing capable service in the Nomad +# Remote Tools Hub (NORTH) the topic of interoperability became more important +# and eventually the NXapm application definition was proposed. +# NORTH is a GUI and related service in a NOMAD OASIS instance which allows +# to spawn preconfigured docker containers via JupyterHub. +# Currently, NORTH includes the so-called apm container. A container with +# tools specific for analyzing data from atom probe microscopy as well as +# processing of point cloud and mesh data. +# +# The NXapm application definition and related implementation work within +# NOMAD OASIS enabled users to parse content of POS, ePOS, APT, RNG, and +# RRNG files, surplus key metadata from vendor-agnostic electronic lab notebook +# solutions directly into NOMAD OASIS via the uploads section. +# The process is automated and yields an NXapm-compliant NeXus/HDF5 file +# inside the uploads section in return. +# +# With these improvements made there is no longer a need for - at least the +# users of a NOMAD OASIS and NORTH instance to use the deprecated +# PARAPROBE.Transcoder.Results.*.h5 files. Ideally, paraprobe should +# automatically detect that the input can now be an NXapm-compliant NeXus/HDF5 +# file and in response work with this file directly. +# To remain compliant with users however who do not have or do not wish +# to use a NOMAD OASIS or NXapm or NeXus at all right now, the solution is +# as follows: +# +# Calling the configuration stage of paraprobe-transcoder is always mandatory. +# It is always the first step of working with the toolbox. In this process +# the user defines the input files. These can either be nxs i.e. the NXapm/NeXus/ +# HDF5 file from e.g. the upload section, or such a file that was obtained from +# a colleague with a NOMAD OASIS instance. +# In all other cases, users can pass the reconstruction and ranging definitions +# using the traditional POS, ePOS, or APT and RNG or RRNG file formats respectively. +# +# Based on which input the user delivers, the parmsetup-transcoder tool then +# creates a configuration file PARAPROBE.Transcoder.Config.SimID.*.nxs and +# informs the user whether the input was NeXus (and thus if all relevant +# input is already available) or whether the paraprobe-transcoder tool needs +# to be executed to convert the content of the vendor files first into a +# format which paraprobe can provenance track and understand. +# In the latter case, the PARAPROBE.Transcoder.Config.SimID.*.nxs file is +# used to communicate to all subsequently used tools from which files +# the tools can expect to find the reconstruction and ranging definitions. +# +# All subsequent analysis steps start also with a tool-specific configuration. +# This configuration step reads in (among others) the +# PARAPROBE.Transcoder.Config.SimID.*.nxs file from which the configuration +# tool identifies automatically whether to read the reconstruction and ranging data +# from PARAPROBE.Transcoder.Results.SimID.*.h5 or directly the NXapm-compliant +# NeXus/HDF5 file that was created upon preparing the upload or the file shared +# from a colleague. This design removes the need for unnecessary copies of the data. +# Currently still though users should execute the transcoder step as it will +# generate a supplementary XDMF topology field with which the data in either +# the NeXus/HDF5 or the transcoded vendor files can be displayed using e.g. +# Paraview. For this purpose XDMF is used. +# +# Of course ideally the APT community would at some point converge to use +# a common data exchange file format. To this end, AMETEK/Cameca's APT file format +# could be a good starting point but so far it is lacking a consistent way of +# how to store generalized ranging definitions and post-processing results. +# POS, ePOS, Rouen's ATO, as well as other so far used representations of data +# like CSV or text files have, to the best of our current knowledge, no +# concept of how to marry reconstruction and (optional) ranging data into +# one self-descriptive format. +# +# This summarizes the rationale behind the current choices of the I/O for +# paraprobe. Furthermore, this summarizes also why the fundamental design +# of splitting an analysis always into steps of configuration (with parmsetup), +# task execution (with the respective C/C++ or Python tool of the toolbox), +# and post-processing (e.g. with autoreporter) is useful because it offers +# a clear description of provenance tracking. This is a necessary step to make +# atom probe microscopy data at all better aligned with the aims of the +# FAIR principles. +# +# The internal organization of the data entries in the atom_probe group +# in this application definition for paraprobe-transcoder results files +# mirror the definitions of the NXapm for consistency reasons. +# +# +# +# +# +# Mass-to-charge-state ratio values. +# +# +# +# +# +# +# +# +# +# +# +# Three-dimensional reconstructed positions of the ions. +# Interleaved array of x, y, z positions in the specimen space. +# +# +# +# +# +# +# +# +# +# +# Details about how peaks, with taking into account +# error models, were interpreted as ion types or not. +# +# +# +# +# +# +# +# +# Details and results of the combinatorial analyses of this +# range definition to identify the charge_state for an ion. +# +# +# +# Currently charge_state not charge! +# +# +# +# +# +# +# +# Specific isotopes building each candidate matching the range. +# +# +# +# +# +# +# +# +# Accumulated mass of the isotopes in each candidate. +# Not corrected for quantum effects. +# +# +# +# +# +# +# +# +# Product of natural abundance of the isotopes per candidate. +# +# +# +# +# +# +# +# Filter criterion on the product of the natural abundances +# computed from each isotope building the (molecular) ion. +# Such a filter can be used to reduce the number of possible +# molecular ions considered when trying to find a unique solution +# to the question which charge_state does a molecular ion +# within a given range and given combination of elements have. +# +# +# +# +# Filter criterion on the minimum half life which all isotopes +# building the (molecular) ion need to have to consider the +# candidate. +# Such a filter can be used to reduce the number of possible +# molecular ions considered when trying to find a unique solution +# to the question which charge_state does a molecular ion +# within a given range and given combination of elements have. +# +# +# +# +# +# If the value is zero/false it means that non-unique solutions +# are accepted. These are solutions where multiple candidates +# differ in their isotopes but have the same charge. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specify if it was different from the number_of_processes +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# Specify if it was different from the number_of_threads +# in the NXcs_profiling super class. +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXbeam_path.yaml b/contributed_definitions/nyaml/NXbeam_path.yaml new file mode 100644 index 0000000000..f7651dee2a --- /dev/null +++ b/contributed_definitions/nyaml/NXbeam_path.yaml @@ -0,0 +1,780 @@ +category: base +doc: | + A beam path consisting of one or more optical elements. + + NXbeam_path is used in NXopt to describe the beam path, i.e. the arrangement + of optical elements between the excitation source and the sample, or between + the sample and the detector unit. + + To describe the order of the elements, use 'order(NXtransformations)', where + each element's position points to the preceding element via '@depends_on'. + Special case beam splitter: A beam splitter is a device which separates the + beam into two or more beams. If such a device is part of the beam path use + two or more NXbeam_paths to describe the beam paths after the beam splitter. + In this case, in the dependency chain of the new beam paths, the first + elements each point to the beam splitter, as this is the previous element. + + Describe the relevant optical elements in the beam path by using the + appropriate base classes. You may use as many elements as needed, also + several elements of the same type as long as each element has its own name. + +# 05/2023 +# A draft of a new base class to describe a beam path consisting of one or +# more optical elements (e.g. a beam path in a luminescence setup). + +# To do: +# [ ] Harmonize common fields/classes among base classes used in NXbeam_path, +# e.g. NXshape in NXbeam_splitter and NXpolarizer_opt, or NXsample used for +# describing substrates and coatings etc. +# [ ] How to describe a setup or beam path? Order/sequence defined by +# NXtransformations? => discussion needed +type: group +NXbeam_path(NXobject): + depends_on: + doc: | + Entry point of the dependency chain defined by the NXtransformations + field, i.e. a link to the last element in the beam path. + Example: /entry/instrument/beam_path/detector. + (NXtransformations): + + # Possibilities: + # (1) Modify NXtransformations to include properties that modify the light beam + # (e.g. polarization state) instead (or in addition) to transformations like + # translation and rotation + # (2) Base class similar to NXtransformations but for changes of optical + # properties (e.g. polarization state). + doc: | + Specify the order of the optical elements by defining a dependency chain. + For each element, a '@depends_on' attribute should be used to state the + position of the element in the beam path by pointing to the previous + element. For the very first element, use the string "." instead. + AXISNAME(NX_NUMBER): + unit: NX_TRANSFORMATION + doc: | + For each element in the beam path, one such field must exist with a + '@depends_on' attribute defined to specify its position in the beam + path. Note that also 'NXopt/ENTRY/INSTRUMENT/sample_stage' and windows + ('NXopt/ENTRY/INSTRUMENT/sample_stage/entry_window' and + 'NXopt/ENTRY/INSTRUMENT/sample_stage/exit_window') may be added to the + dependency chain, i.e. may have an entry in this class even if they are + not described in the beam path. + ELEMENT is a place holder for the name of an optical beam path element. + Note that the name of this field must be exactly the same as the + element's field name. + \@depends_on: + doc: | + Add a link to the previous beam path element. + (NXsource): + doc: | + Excitation source. One or more may be needed (e.g. two for a pump-probe + setup with one pump and one probe beam). + Depending on the source type, different properties are relevant, which + are provided through the respective base class (e.g. use NXopt_source for + lamps or lasers, NXchem_source for chemical reaction etc.). + Some base classes are incomplete (NXchem_source, NXbio_source); the + expertise of the respective communities is needed. + depends_on: + doc: | + Use this field to point to the previous optical element. + type: + doc: | + Type of excitation source. + enumeration: [semiconductor laser, gas laser, other laser, lamp, X-rays, silicon carbide globar, super continuum, chemical reaction, ultrasound, sound, living organism, power supply, electron source, other] + + # Spallation Neutron Source + # Pulsed Reactor Neutron Source + # Reactor Neutron Source + # Synchrotron X-ray Source + # Pulsed Muon Source + # Rotating Anode X-ray + # Fixed Tube X-ray + # UV Laser + # Free-Electron Laser + # Optical Laser + # Ion Source + # UV Plasma Source + # Metal Jet X-ray + + # separate base classes for different sources: + # (NXacoustic_source): # needs to be developed + # doc: | + # Acoustic source, e.g. an ultrasonic transducero or a imploding gas + # bubble (sonoluminescence). + # (NXpower_supply): # needs to be developed + # (NXchem_source): # input for experts from that field needed + # (NXbio_source): # input for experts from that field needed + # is NXsource sufficient for x-rays? + # (NXopt_source): + # doc: Specify the properties of the optical source. + lifespan(NX_NUMBER): + unit: NX_TIME + doc: | + Lifespan of the excitation (typically provided in hours). + measure_time(NX_NUMBER): + unit: NX_TIME + doc: | + How many hours has the lamp been used? + excitation_wavelength(NX_FLOAT): + unit: NX_ANY + doc: | + Wavelengths or energy vector of the excitation source. This can be a + single value or a spectrum, depending on the type of experiment. + \@units: + doc: | + Unit of wavelength or energy. + beam_profile: + + # ??? What's the best way to enter this ??? + doc: | + Two- or three-dimensional beam profile. + dimensions: + rank: 2 + dim: [[1, N_beam_profile_dim], [2, N_beam_profile_points]] + peak_power(NX_FLOAT): + unit: NX_POWER + doc: | + Power of one light pulse if the source is a pulsed source. + cw(NX_BOOLEAN): + doc: | + Is the excitation source continuous wave (CW)? + cw_power(NX_FLOAT): + doc: | + Power of CW beam. + bandwidth(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + FWHM bandwidth of the excitation source. + coherence_length(NX_FLOAT): + unit: NX_LENGTH + doc: | + Coherence length. + divergence(NX_FLOAT): + unit: NX_ANGLE + doc: | + Divergence of the excitation beam. + (NXpinhole): + doc: | + Use this field to describe a simple pinhole (round geometry). Define its + dimension using 'diameter'. For more complex geometries, 'NXaperture' + should be used. + (NXslit): + doc: | + Use this field to describe a simple slit (rectangular geometry). Define + its dimensions using 'x_gap' and 'y_gap'. For more complex geometries, + 'NXaperture' should be used. + aperture_NUMBER(NXaperture): + doc: | + Use this field to describe an aperture. To specify a window, use the + field 'window_NUMBER(NXaperture)'. + window_NUMBER(NXaperture): + doc: | + A window, e.g. an entry or exit window of a cryostat. + depends_on: + doc: | + Use this field to point to the previous optical element. + material(NX_CHAR): + doc: | + The material of the window. + enumeration: [quartz, diamond, calcium fluoride, zinc selenide, thallium bromoiodide, alkali halide compound, Mylar, other] + other_material(NX_CHAR): + doc: | + If you specified 'other' as material, decsribe here what it is. + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the window + orientation_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angle of the window normal (outer) vs. the substrate normal + (similar to the angle of incidence). + reference_data_link: + doc: | + If reference data were measured add a link to the NeXus file where they + are described. + (NXmirror): + filter_NUMBER(NXfilter): + (NXattenuator): + doc: | + A device that reduces the intensity of a beam by attenuation. + attenuator_transmission(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + The transmitted intensity divided by the incident intensity. + attenuation(NX_FLOAT): + unit: NX_ANY + doc: | + Attenuation of the attenuator in dB. + \@units: + doc: | + Unit of the measured data is not covered by NXDL units state + here which unit was used. + (NXaperture): + doc: | + Input and output aperture of the attenuator. + (NXgeometry): + doc: | + Geometry (shape, size etc.) of the attenuator. + (NXgrating): + doc: | + A diffraction grating. Define relevant parameters in the corresponding + fields, e.g. order of diffration (diffraction_order) or angular + dispersion (angular_dispersion). + type: + doc: | + Define the type of the grating. + angular_dispersion(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Dispersion of the grating in nm/mm (or e.g. nm/mrad). + grooves(NX_FLOAT): + unit: NX_PER_LENGTH + doc: | + Number of grooves per mm. + blaze_wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Blaze wavelength of the grating. + efficiency(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Efficiency curve versus wavelength or energy. + dimensions: + rank: 1 + dim: [[1, N_spectrum]] + spectrum(NX_FLOAT): + unit: NX_ANY + doc: | + Spectral values, e.g. wavelength or energy. Vector of length + N_spectrum. + \@units: + doc: | + Unit of wavelength array (e.g. nanometer or Angstrom) + (NXdisk_chopper): + doc: | + A device blocking the beam in a temporal periodic pattern, e.g. a optical + chopper wheel. Specify the frequency range using 'min_frequency' and + 'max_frequency'. + min_frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Minimum frequency in Hertz. + max_frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Maximum frequency in Hertz. + frequency_resolution(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Frequency resolution in Hertz. + (NXmonochromator): + doc: | + A monochromator or spectrometer. + spectrum(NX_FLOAT): + unit: NX_ANY + doc: | + Spectral values of the monochromator, e.g. wavelength or energy values + used for the measurement. + \@units: + doc: | + Unit of wavelength array (e.g. nanometer or Angstrom) + (NXgrating): + doc: | + Diffraction grating. If two or more gratings were used, define the + angular dispersion and the wavelength range (min/max wavelength) for + each grating and make sure that the wavelength ranges do not overlap. + The dispersion should be defined for the entire wavelength range of the + experiment. + angular_dispersion(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Dispersion of the grating in nm/mm. + grating_wavelength_min(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Minimum wavelength of the grating. + grating_wavelength_max(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Maximum wavelength of the grating. + spectral_resolution(NX_FLOAT): + unit: NX_WAVENUMBER + doc: | + Spectral resolution of the instrument. + (NXslit): + doc: | + Define the width of the monochromator slit in the subfield x_gap. + fixed_slit(NX_BOOLEAN): + doc: | + Was the slit width fixed? + max_gap(NX_FLOAT): + unit: NX_LENGTH + doc: | + If slit width was not fixed, define the maximum slit width. + + # x-ray optics: + (NXxraylens): + + # what else? + + # ====== New base classes: ====== + (NXpolarizer_opt): + (NXbeam_splitter): + (NXwaveplate): + (NXlens_opt): + (NXfiber): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# f0ed01c487c4175dc723d226e0d33b89fa8107576fe95b4f0b825c1f91244ccc +# +# +# +# +# +# +# +# A beam path consisting of one or more optical elements. +# +# NXbeam_path is used in NXopt to describe the beam path, i.e. the arrangement +# of optical elements between the excitation source and the sample, or between +# the sample and the detector unit. +# +# To describe the order of the elements, use 'order(NXtransformations)', where +# each element's position points to the preceding element via '@depends_on'. +# Special case beam splitter: A beam splitter is a device which separates the +# beam into two or more beams. If such a device is part of the beam path use +# two or more NXbeam_paths to describe the beam paths after the beam splitter. +# In this case, in the dependency chain of the new beam paths, the first +# elements each point to the beam splitter, as this is the previous element. +# +# Describe the relevant optical elements in the beam path by using the +# appropriate base classes. You may use as many elements as needed, also +# several elements of the same type as long as each element has its own name. +# +# +# +# Entry point of the dependency chain defined by the NXtransformations +# field, i.e. a link to the last element in the beam path. +# Example: /entry/instrument/beam_path/detector. +# +# +# +# +# +# Specify the order of the optical elements by defining a dependency chain. +# For each element, a '@depends_on' attribute should be used to state the +# position of the element in the beam path by pointing to the previous +# element. For the very first element, use the string "." instead. +# +# +# +# For each element in the beam path, one such field must exist with a +# '@depends_on' attribute defined to specify its position in the beam +# path. Note that also 'NXopt/ENTRY/INSTRUMENT/sample_stage' and windows +# ('NXopt/ENTRY/INSTRUMENT/sample_stage/entry_window' and +# 'NXopt/ENTRY/INSTRUMENT/sample_stage/exit_window') may be added to the +# dependency chain, i.e. may have an entry in this class even if they are +# not described in the beam path. +# ELEMENT is a place holder for the name of an optical beam path element. +# Note that the name of this field must be exactly the same as the +# element's field name. +# +# +# +# Add a link to the previous beam path element. +# +# +# +# +# +# +# Excitation source. One or more may be needed (e.g. two for a pump-probe +# setup with one pump and one probe beam). +# Depending on the source type, different properties are relevant, which +# are provided through the respective base class (e.g. use NXopt_source for +# lamps or lasers, NXchem_source for chemical reaction etc.). +# Some base classes are incomplete (NXchem_source, NXbio_source); the +# expertise of the respective communities is needed. +# +# +# +# Use this field to point to the previous optical element. +# +# +# +# +# Type of excitation source. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Lifespan of the excitation (typically provided in hours). +# +# +# +# +# How many hours has the lamp been used? +# +# +# +# +# Wavelengths or energy vector of the excitation source. This can be a +# single value or a spectrum, depending on the type of experiment. +# +# +# +# Unit of wavelength or energy. +# +# +# +# +# +# +# Two- or three-dimensional beam profile. +# +# +# +# +# +# +# +# +# Power of one light pulse if the source is a pulsed source. +# +# +# +# +# Is the excitation source continuous wave (CW)? +# +# +# +# +# Power of CW beam. +# +# +# +# +# FWHM bandwidth of the excitation source. +# +# +# +# +# Coherence length. +# +# +# +# +# Divergence of the excitation beam. +# +# +# +# +# +# Use this field to describe a simple pinhole (round geometry). Define its +# dimension using 'diameter'. For more complex geometries, 'NXaperture' +# should be used. +# +# +# +# +# Use this field to describe a simple slit (rectangular geometry). Define +# its dimensions using 'x_gap' and 'y_gap'. For more complex geometries, +# 'NXaperture' should be used. +# +# +# +# +# Use this field to describe an aperture. To specify a window, use the +# field 'window_NUMBER(NXaperture)'. +# +# +# +# +# A window, e.g. an entry or exit window of a cryostat. +# +# +# +# Use this field to point to the previous optical element. +# +# +# +# +# The material of the window. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you specified 'other' as material, decsribe here what it is. +# +# +# +# +# Thickness of the window +# +# +# +# +# Angle of the window normal (outer) vs. the substrate normal +# (similar to the angle of incidence). +# +# +# +# +# If reference data were measured add a link to the NeXus file where they +# are described. +# +# +# +# +# +# +# +# A device that reduces the intensity of a beam by attenuation. +# +# +# +# The transmitted intensity divided by the incident intensity. +# +# +# +# +# Attenuation of the attenuator in dB. +# +# +# +# Unit of the measured data is not covered by NXDL units state +# here which unit was used. +# +# +# +# +# +# Input and output aperture of the attenuator. +# +# +# +# +# Geometry (shape, size etc.) of the attenuator. +# +# +# +# +# +# A diffraction grating. Define relevant parameters in the corresponding +# fields, e.g. order of diffration (diffraction_order) or angular +# dispersion (angular_dispersion). +# +# +# +# Define the type of the grating. +# +# +# +# +# Dispersion of the grating in nm/mm (or e.g. nm/mrad). +# +# +# +# +# Number of grooves per mm. +# +# +# +# +# Blaze wavelength of the grating. +# +# +# +# +# Efficiency curve versus wavelength or energy. +# +# +# +# +# +# +# +# Spectral values, e.g. wavelength or energy. Vector of length +# N_spectrum. +# +# +# +# Unit of wavelength array (e.g. nanometer or Angstrom) +# +# +# +# +# +# +# A device blocking the beam in a temporal periodic pattern, e.g. a optical +# chopper wheel. Specify the frequency range using 'min_frequency' and +# 'max_frequency'. +# +# +# +# Minimum frequency in Hertz. +# +# +# +# +# Maximum frequency in Hertz. +# +# +# +# +# Frequency resolution in Hertz. +# +# +# +# +# +# A monochromator or spectrometer. +# +# +# +# Spectral values of the monochromator, e.g. wavelength or energy values +# used for the measurement. +# +# +# +# Unit of wavelength array (e.g. nanometer or Angstrom) +# +# +# +# +# +# Diffraction grating. If two or more gratings were used, define the +# angular dispersion and the wavelength range (min/max wavelength) for +# each grating and make sure that the wavelength ranges do not overlap. +# The dispersion should be defined for the entire wavelength range of the +# experiment. +# +# +# +# Dispersion of the grating in nm/mm. +# +# +# +# +# Minimum wavelength of the grating. +# +# +# +# +# Maximum wavelength of the grating. +# +# +# +# +# +# Spectral resolution of the instrument. +# +# +# +# +# Define the width of the monochromator slit in the subfield x_gap. +# +# +# +# Was the slit width fixed? +# +# +# +# +# If slit width was not fixed, define the maximum slit width. +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXbeam_splitter.yaml b/contributed_definitions/nyaml/NXbeam_splitter.yaml new file mode 100644 index 0000000000..64547668be --- /dev/null +++ b/contributed_definitions/nyaml/NXbeam_splitter.yaml @@ -0,0 +1,637 @@ +category: base +doc: | + A beam splitter, i.e. a device splitting the light into two or more beams. + + Information about types and properties of beam splitters is provided e.g. + [here](https://www.rp-photonics.com/beam_splitters.html). + + Use two or more NXbeam_paths to describe the beam paths after the beam + splitter. In the dependency chain of the new beam paths, the first elements + each point to this beam splitter, as this is the previous element. +symbols: + N_spectrum: | + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the beam splitter material and/or coating is defined. + N_spectrum_RT: | + Length of the spectrum vector (e.g. wavelength or energy) for which the + reflectance or transmission of the beam splitter is given. + N_shapepar: | + Number of parameters needed do descripe the shape of the beam splitter. + N_objects: | + Number of objects the beam splitter is made up of. + N_outputs: | + Number of outputs, i.e. number of paths the beam takes after being split by + the beam splitter. + +# A draft of a new base class to describe a beam splitting device. +type: group +NXbeam_splitter(NXobject): + type: + doc: | + Specify the beam splitter type (e.g. dielectric mirror, pellicle, + dichroic mirror etc.). Shape (e.g. prism, plate, cube) and dimension + should be described in 'geometry'. Define if the beam splitter is + polarizing or not in the field 'polarizing(NX_BOOLEAN)'. + enumeration: [dichroic mirror, dielectric mirror, metal-coated mirror, Nicol prism, Glan-Thompson prism, pellicle mirror, Polka dot beam splitter, fiber optic splitter, other] + + # ??? Are there any other common types of beam splitters ??? + other_type: + doc: | + If you selected 'other' in 'type' use this field to specify which type of + beam splitter was used. + polarizing(NX_BOOLEAN): + doc: | + Is the beam splitter polarizing? + multiple_outputs(NX_BOOLEAN): + + # ??? Redundant because number of outputs is defined by N_outputs ??? + doc: | + Does the beam splitter have multiple outputs (diffractive optical + element), i.e. more than two outputs? + (NXshape): + exists: recommended + doc: | + Describe the geometry (shape, dimension etc.) of the beam splitter. + Specify the dimensions in 'SHAPE/size'. A sketch of the device should be + provided in the 'sketch(NXdata)' field to clarify (i) the shape and + dimensions of the device, and (ii) the input and outputs (i.e. the + direction of the incoming and outcoming (split) beams). + + # Specify the length and height if the surface facing the incident + # beam is a square or rectangle. Otherwise, if the device has a round + # geometry (disc), sepcify the diameter instead. + # The thickness or depth of the device should be defined in 'depth', + # while the thickness of the substrate and coating should be specified + # in 'substrate/substrate_thickness' and 'coating/coating_thickness'. + shape: + doc: | + Describe the shape (plate, cube, wedged, prism etc.). + enumeration: [cube, cylinder, plate, prism, wedged, other] + other_shape: + doc: | + If you chose 'other' in 'shape' describe what it is. + sketch(NXdata): + doc: | + Sketch of the beam splitter showing its geometry. The paths of the + incoming and split beam should be illustrated and labelled (0 for the + incoming beam, and 1, 2,..., N_outputs for the outputs (i.e. the split + beam paths)). + size: + doc: | + Physical extent of the beam splitter device. The beam splitter might be + made up of one or more objects (NX_objects). The meaning and location + of the axes used will vary according to the value of the 'shape' + variable. 'N_shapepar' defines how many parameters: + + * For 'cube' the parameters are (width, length). + * For 'cylinder' the parameters are (diameter, length). + * For 'plate' the parameters are (width, height, length). + * For 'prism' the parameters are (width, height, length). + * For 'wedged' the parameters are (width, height, shortest length). + The wedge angle should be provided in 'SHAPE/wedge_angle'. + * For 'other' the parameters may be (A, B, C, ...) with the labels + defined in the sketch plotted in 'SHAPE/sketch'. + dimensions: + rank: 2 + dim: [[1, N_objects], [2, N_shapepar]] + wedge_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Wedge angle if 'shape' is 'wedged'. + + # width, height, diameter, depth: Should we use 'size' in NXshape instead? + # width(NX_FLOAT): + # doc: | + # Width of the device's surface facing the incident beam if the surface + # is square or rectangular (e.g. is shape is a cube). + # unit: NX_LENGTH + # height(NX_FLOAT): + # doc: | + # Height of the device's surface facing the incident beam if the surface + # is square or rectangular (e.g. is shape is a cube). + # unit: NX_LENGTH + # diameter(NX_FLOAT): + # doc: | + # Diameter of the device's surface facing the incident beam if the + # surface has circular geometry (e.g. is shape is a cylinder). + # unit: NX_LENGTH + # length(NX_FLOAT): + # doc: | + # Specify the length of the beam splitter. If the device has a wedged + # shape provide the minimum and maximum length of the device. + # Otherwise, if the beam splitter has a homogeneous thickness, the two + # values are equal. + # dimensions: + # rank: 1 + # dim: [[1,2]] + splitting_ratio(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Beam splitting ratio(s) for the various outputs (i.e. the + paths of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting with 1. + dimensions: + rank: 1 + dim: [[1, N_outputs]] + clear_aperture(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Clear aperture of the device (e.g. 90% of diameter for a disc, or 90% of + length and height for square geometry). + + # ??? Would it be better to provide the clear aperture as length ??? + substrate(NXsample): + doc: | + Substrate of the beam splitter. Describe the material of the substrate in + substrate/substrate_material and provide its index of refraction in + substrate/index_of_refraction_substrate, if known. + substrate_material: + doc: | + Specify the material of the beam splitter. If the device has a coating + it should be described in coating/coating_material. Is the material + birefringent? + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the beam splitter substrate. Define the minimum and + maximum thickness (for a wedged geomtry). For a homogeneous thickness + (e.g. as in plate beam splitters) the minimum and maximum values are + equal. + dimensions: + rank: 1 + dim: [[1, 2]] + index_of_refration_substrate(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the beam splitter substrate. Specify at + given spectral values (e.g. wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + coating(NXsample): + doc: | + Is the beam splitter coated? If yes, specify the type and material of the + coating and the spectral range for which it is designed. If known, you + may also provide its index of refraction. For a beam splitter cube + consisting of two prisms which are glued together, you may want to + specify the the glue and the coatings of each prism. + coating_type: + doc: | + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + coating_material: + doc: | + Specify the coating material. + coating_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the coating. + wavelength_range_coating(NX_FLOAT): + exists: recommended + unit: NX_WAVELENGTH + doc: | + Wavelength range for which the coating is designed. Enter the minimum + and maximum values of the wavelength range. + dimensions: + rank: 1 + dim: [[1, 2]] + index_of_refraction_coating(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the coating. Specify at given spectral + values (e.g. wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + wavelength_range(NX_FLOAT): + exists: recommended + unit: NX_WAVELENGTH + doc: | + Wavelength range for which the beam splitter is designed. Enter the + minimum and maximum values of the wavelength range. Alternatively, or + additionally, you may define the wavelength range for the coating in + coating/wavelength_range_coating. + dimensions: + rank: 1 + dim: [[1, 2]] + optical_loss(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Optical loss of the beam splitter for the various outputs (i.e. the paths + of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting + with 1. + dimensions: + rank: 1 + dim: [[1, N_outputs]] + incident_angle(NX_NUMBER): + unit: NX_ANGLE + doc: | + Optimized angle of incidence for the desired splitting ratio. + deflection_angle(NX_NUMBER): + unit: NX_ANGLE + + # is this really needed? + doc: | + Angle of deflection corresponding to the optimized angle of incidence + defined in incident_angle. + AOI_range(NX_NUMBER): + unit: NX_ANGLE + doc: | + Range of the angles of incidence (AOI) for which the beam splitter can be + operated. Specify the minimum and maximum angles of the range. + dimensions: + rank: 1 + dim: [[1, 2]] + + # Aren't some beamsplitters defined for specific angles? Should we instead + # use dim: [[1,N_angles]], N_angles being the number of angles for which the + # beam splitter can be operated? + # If this is the case for some devices, we might also have to define a field + # for the corresponding defelction angles... + reflectance(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Reflectance of the beam splitter at given spectral values. + dimensions: + rank: 1 + dim: [[1, N_spectrum_RT]] + transmission(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Transmission at given spectral values for the various outputs (i.e. the + paths of the beam after being split by the beam splitter). + The order of the ratios must be consistent with the labels + 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting + with 1. + dimensions: + rank: 2 + dim: [[1, N_outputs], [2, N_spectrum_RT]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9c9fd3b4d0c17a3247a3133fbcc1af74f2ccf9c22249019dc21b7f568d8fa3ac +# +# +# +# +# +# +# +# +# Length of the spectrum vector (e.g. wavelength or energy) for which the +# refractive index of the beam splitter material and/or coating is defined. +# +# +# +# +# Length of the spectrum vector (e.g. wavelength or energy) for which the +# reflectance or transmission of the beam splitter is given. +# +# +# +# +# Number of parameters needed do descripe the shape of the beam splitter. +# +# +# +# +# Number of objects the beam splitter is made up of. +# +# +# +# +# Number of outputs, i.e. number of paths the beam takes after being split by +# the beam splitter. +# +# +# +# +# A beam splitter, i.e. a device splitting the light into two or more beams. +# +# Information about types and properties of beam splitters is provided e.g. +# [here](https://www.rp-photonics.com/beam_splitters.html). +# +# Use two or more NXbeam_paths to describe the beam paths after the beam +# splitter. In the dependency chain of the new beam paths, the first elements +# each point to this beam splitter, as this is the previous element. +# +# +# +# Specify the beam splitter type (e.g. dielectric mirror, pellicle, +# dichroic mirror etc.). Shape (e.g. prism, plate, cube) and dimension +# should be described in 'geometry'. Define if the beam splitter is +# polarizing or not in the field 'polarizing(NX_BOOLEAN)'. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you selected 'other' in 'type' use this field to specify which type of +# beam splitter was used. +# +# +# +# +# Is the beam splitter polarizing? +# +# +# +# +# +# Does the beam splitter have multiple outputs (diffractive optical +# element), i.e. more than two outputs? +# +# +# +# +# Describe the geometry (shape, dimension etc.) of the beam splitter. +# Specify the dimensions in 'SHAPE/size'. A sketch of the device should be +# provided in the 'sketch(NXdata)' field to clarify (i) the shape and +# dimensions of the device, and (ii) the input and outputs (i.e. the +# direction of the incoming and outcoming (split) beams). +# +# +# +# +# Describe the shape (plate, cube, wedged, prism etc.). +# +# +# +# +# +# +# +# +# +# +# +# +# If you chose 'other' in 'shape' describe what it is. +# +# +# +# +# Sketch of the beam splitter showing its geometry. The paths of the +# incoming and split beam should be illustrated and labelled (0 for the +# incoming beam, and 1, 2,..., N_outputs for the outputs (i.e. the split +# beam paths)). +# +# +# +# +# Physical extent of the beam splitter device. The beam splitter might be +# made up of one or more objects (NX_objects). The meaning and location +# of the axes used will vary according to the value of the 'shape' +# variable. 'N_shapepar' defines how many parameters: +# +# * For 'cube' the parameters are (width, length). +# * For 'cylinder' the parameters are (diameter, length). +# * For 'plate' the parameters are (width, height, length). +# * For 'prism' the parameters are (width, height, length). +# * For 'wedged' the parameters are (width, height, shortest length). +# The wedge angle should be provided in 'SHAPE/wedge_angle'. +# * For 'other' the parameters may be (A, B, C, ...) with the labels +# defined in the sketch plotted in 'SHAPE/sketch'. +# +# +# +# +# +# +# +# +# Wedge angle if 'shape' is 'wedged'. +# +# +# +# +# +# +# Beam splitting ratio(s) for the various outputs (i.e. the +# paths of the beam after being split by the beam splitter). +# The order of the ratios must be consistent with the labels +# 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting with 1. +# +# +# +# +# +# +# +# Clear aperture of the device (e.g. 90% of diameter for a disc, or 90% of +# length and height for square geometry). +# +# +# +# +# +# Substrate of the beam splitter. Describe the material of the substrate in +# substrate/substrate_material and provide its index of refraction in +# substrate/index_of_refraction_substrate, if known. +# +# +# +# Specify the material of the beam splitter. If the device has a coating +# it should be described in coating/coating_material. Is the material +# birefringent? +# +# +# +# +# Thickness of the beam splitter substrate. Define the minimum and +# maximum thickness (for a wedged geomtry). For a homogeneous thickness +# (e.g. as in plate beam splitters) the minimum and maximum values are +# equal. +# +# +# +# +# +# +# +# Complex index of refraction of the beam splitter substrate. Specify at +# given spectral values (e.g. wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# Is the beam splitter coated? If yes, specify the type and material of the +# coating and the spectral range for which it is designed. If known, you +# may also provide its index of refraction. For a beam splitter cube +# consisting of two prisms which are glued together, you may want to +# specify the the glue and the coatings of each prism. +# +# +# +# Specify the coating type (e.g. dielectric, anti-reflection (AR), +# multilayer coating etc.). +# +# +# +# +# Specify the coating material. +# +# +# +# +# Thickness of the coating. +# +# +# +# +# Wavelength range for which the coating is designed. Enter the minimum +# and maximum values of the wavelength range. +# +# +# +# +# +# +# +# Complex index of refraction of the coating. Specify at given spectral +# values (e.g. wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# Wavelength range for which the beam splitter is designed. Enter the +# minimum and maximum values of the wavelength range. Alternatively, or +# additionally, you may define the wavelength range for the coating in +# coating/wavelength_range_coating. +# +# +# +# +# +# +# +# Optical loss of the beam splitter for the various outputs (i.e. the paths +# of the beam after being split by the beam splitter). +# The order of the ratios must be consistent with the labels +# 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting +# with 1. +# +# +# +# +# +# +# +# Optimized angle of incidence for the desired splitting ratio. +# +# +# +# +# +# Angle of deflection corresponding to the optimized angle of incidence +# defined in incident_angle. +# +# +# +# +# Range of the angles of incidence (AOI) for which the beam splitter can be +# operated. Specify the minimum and maximum angles of the range. +# +# +# +# +# +# +# +# +# Reflectance of the beam splitter at given spectral values. +# +# +# +# +# +# +# +# Transmission at given spectral values for the various outputs (i.e. the +# paths of the beam after being split by the beam splitter). +# The order of the ratios must be consistent with the labels +# 1, 2, ... N_outputs defined by the sketch in 'SHAPE/sketch', starting +# with 1. +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXbias_spectroscopy.yaml b/contributed_definitions/nyaml/NXbias_spectroscopy.yaml new file mode 100644 index 0000000000..87971be740 --- /dev/null +++ b/contributed_definitions/nyaml/NXbias_spectroscopy.yaml @@ -0,0 +1,282 @@ +category: base +doc: | + Base classes definition for bias spectroscopy. + + Bias sweeps while measuring arbitrary channels with I(V) curves. +type: group +NXbias_spectroscopy(NXobject): + channels: + doc: | + Select the channels to record. + reset_bias(NX_BOOLEAN): + doc: | + If chosen, the Bias voltage resets to its initial value (before the sweep initiation) at + the conclusion of the spectroscopy measurement. When this option is not selected, the Bias + voltage maintains the last value acquired during the sweep. This functionality proves + beneficial, especially when combining multiple sweep segments. As an illustration of an + automated measurement: turn off the z-Controller, commence spectroscopy sweep segments ( + forward sweep only, without resetting the bias), restore the bias to its initial value, + and then turn on the z-Controller. + record_final_z(NX_BOOLEAN): + doc: | + Select whether to record the Z position during Z averaging time at the end of + the sweep (after Z control time) and store the average value in the header of + the file when saving. Using this option increases the sweep time by Z averaging + time. + lock_in_run(NX_BOOLEAN): + doc: | + Select whether to set the Lock-In to run during the measurement. When using this + feature, make sure the Lock-In is configured correctly and settling times are + set to twice the Lock-In period at least. This option is ignored when Lock-In is + already running. This option is disabled if the Sweep Mode is MLS and the flag + to configure the Lock-In per segment in the Multiline segment editor is set. + integration_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the spectroscopy data are acquired and averaged. + number_of_sweeps(NX_NUMBER): + doc: | + Number of sweeps to measure and average. + sweep_start(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The first bias values of the sweep. + sweep_end(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The last bias values of the sweep. + num_pixel(NX_NUMBER): + doc: | + Define the sweep number of points, that is, the maximum spectrum resolution eq. + Bias window divide by Num Pixel. + z_avg_time(NX_NUMBER): + unit: NX_TIME + doc: | + Duration over which the Z position is recorded and averaged before and after the + sweep (the latter only if Record final Z position is selected in the Advanced + section). After the initial z averaging time, if Z-Controller to Hold is + selected in the Advanced section, the z-Controller is set to hold and the tip is + placed at the previously averaged z position (plus z offset). + sw_filter_type(NX_CHAR): + doc: | + Select a filter to smooth the displayed data. When saving, if any filter is selected, + filtered data are saved to file along with the unfiltered data. + sw_filter_order(NX_NUMBER): + doc: | + Filter order of a dynamic filter or width (in number of points) for the Gaussian + filter. + sw_filter_cutoff_frq(NX_NUMBER): + doc: | + Cutoff frequency for dynamic filters. + z_offset(NX_NUMBER): + unit: NX_LENGTH + doc: | + Offset added to the initial averaged position Zaver before starting to sweep. + This parameter is disabled when Z-Controller to Hold is deselected in the + Advanced section. The LED “Alt” next to the Z offset indicates if an alternate + Z-controller setpoint is enabled. + settling_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time to wait after changing the bias to the next level and before + starting to acquire data. + first_settling_time(NX_NUMBER): + doc: | + No doc yet. + end_settling_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time to wait after the sweep has finished and the bias is ramped to + the initial value. + z_control_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the Z-Controller is enabled once a sweep has finished. + When averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled + for this duration between each sweep. After the last sweep, it will wait the + specified time before continuing a running scan. This ensures each sweep + reliably starts from the same position. This parameter is disabled when + Z-Controller to Hold is deselected in the Advanced section. + max_slew_rate(NX_NUMBER): + doc: | + Maximum rate at which the bias changes (before, during and after sweeping). + (V/s) + backward_sweep(NX_BOOLEAN): + doc: | + Select whether to measure the backward (return) sweep or the forward only. + z_ccontroller_hold(NX_BOOLEAN): + doc: | + Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. + It is selected by default. When deselected, Z-offset and Z control time parameters + are disabled. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a3079d513b63e99022e710b15756f7cd46a7101b306d34339dc6d6b3c7d685b1 +# +# +# +# +# +# Base classes definition for bias spectroscopy. +# +# Bias sweeps while measuring arbitrary channels with I(V) curves. +# +# +# +# Select the channels to record. +# +# +# +# +# If chosen, the Bias voltage resets to its initial value (before the sweep initiation) at +# the conclusion of the spectroscopy measurement. When this option is not selected, the Bias +# voltage maintains the last value acquired during the sweep. This functionality proves +# beneficial, especially when combining multiple sweep segments. As an illustration of an +# automated measurement: turn off the z-Controller, commence spectroscopy sweep segments ( +# forward sweep only, without resetting the bias), restore the bias to its initial value, +# and then turn on the z-Controller. +# +# +# +# +# Select whether to record the Z position during Z averaging time at the end of +# the sweep (after Z control time) and store the average value in the header of +# the file when saving. Using this option increases the sweep time by Z averaging +# time. +# +# +# +# +# Select whether to set the Lock-In to run during the measurement. When using this +# feature, make sure the Lock-In is configured correctly and settling times are +# set to twice the Lock-In period at least. This option is ignored when Lock-In is +# already running. This option is disabled if the Sweep Mode is MLS and the flag +# to configure the Lock-In per segment in the Multiline segment editor is set. +# +# +# +# +# Time during which the spectroscopy data are acquired and averaged. +# +# +# +# +# Number of sweeps to measure and average. +# +# +# +# +# The first bias values of the sweep. +# +# +# +# +# The last bias values of the sweep. +# +# +# +# +# Define the sweep number of points, that is, the maximum spectrum resolution eq. +# Bias window divide by Num Pixel. +# +# +# +# +# Duration over which the Z position is recorded and averaged before and after the +# sweep (the latter only if Record final Z position is selected in the Advanced +# section). After the initial z averaging time, if Z-Controller to Hold is +# selected in the Advanced section, the z-Controller is set to hold and the tip is +# placed at the previously averaged z position (plus z offset). +# +# +# +# +# Select a filter to smooth the displayed data. When saving, if any filter is selected, +# filtered data are saved to file along with the unfiltered data. +# +# +# +# +# Filter order of a dynamic filter or width (in number of points) for the Gaussian +# filter. +# +# +# +# +# Cutoff frequency for dynamic filters. +# +# +# +# +# Offset added to the initial averaged position Zaver before starting to sweep. +# This parameter is disabled when Z-Controller to Hold is deselected in the +# Advanced section. The LED “Alt” next to the Z offset indicates if an alternate +# Z-controller setpoint is enabled. +# +# +# +# +# Time to wait after changing the bias to the next level and before +# starting to acquire data. +# +# +# +# +# No doc yet. +# +# +# +# +# Time to wait after the sweep has finished and the bias is ramped to +# the initial value. +# +# +# +# +# Time during which the Z-Controller is enabled once a sweep has finished. +# When averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled +# for this duration between each sweep. After the last sweep, it will wait the +# specified time before continuing a running scan. This ensures each sweep +# reliably starts from the same position. This parameter is disabled when +# Z-Controller to Hold is deselected in the Advanced section. +# +# +# +# +# Maximum rate at which the bias changes (before, during and after sweeping). +# (V/s) +# +# +# +# +# Select whether to measure the backward (return) sweep or the forward only. +# +# +# +# +# Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. +# It is selected by default. When deselected, Z-offset and Z control time parameters +# are disabled. +# +# +# diff --git a/contributed_definitions/nyaml/NXcalibration.yaml b/contributed_definitions/nyaml/NXcalibration.yaml new file mode 100644 index 0000000000..4ae8d0d03b --- /dev/null +++ b/contributed_definitions/nyaml/NXcalibration.yaml @@ -0,0 +1,322 @@ +category: base +doc: | + Subclass of NXprocess to describe post-processing calibrations. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays + ncoeff: | + Number of coefficients of the calibration function + ncal: | + Number of points of the calibrated and uncalibrated axes +type: group +NXcalibration(NXobject): + description(NX_CHAR): + doc: | + A description of the procedures employed. + calibration_method(NXidentifier): + doc: | + A digital persistent identifier (e.g., DOI, ISO standard) referring to a detailed description of a + calibration method but no actual calibration data. + calibration_reference(NXidentifier): + doc: | + A digital persistent identifier (e.g., a DOI) referring to a publicly available calibration measurement + used for this instrument, e.g., a measurement of a known standard containing calibration information. + The axis values may be copied or linked in the appropriate NXcalibration fields for reference. + calibration_object(NXserialized): + doc: | + A file serialisation of a calibration which may not be publicly available (externally from the nexus file). + + This metadata can be a documentation of the source (file) or database (entry) from which pieces + of information have been extracted for consumption (e.g. in a research data management system (RDMS)). + It is also possible to include the actual file by using the `file` field. + + The axis values may be copied or linked in the appropriate NXcalibration fields for reference. + last_process(NX_CHAR): + doc: | + Indicates the name of the last operation applied in the NXprocess sequence. + applied(NX_BOOLEAN): + doc: | + Has the calibration been applied? + original_axis(NX_FLOAT): + unit: NX_ANY + doc: | + Vector containing the data coordinates in the original uncalibrated axis + dimensions: + rank: 1 + dim: [[1, ncal]] + \@symbol: + doc: | + The symbol of the axis to be used in the fit_function, e.g., `energy`, `E`. + This should comply to the following naming rules (similar to python's naming rules): + + * A variable name must start with a letter or the underscore character + * A variable name cannot start with a number + * A variable name can only contain alpha-numeric characters and underscores (A-z, 0-9, and _ ) + * Variable names are case-sensitive (age, Age and AGE are three different variables) + \@input_path: + doc: | + The path from which this data is derived, e.g., raw detector axis. + Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. + input_SYMBOL(NX_FLOAT): + unit: NX_ANY + doc: | + Additional input axis to be used in the formula. + The part after `input_` is used as the symbol to be used in the `fit_function`, i.e., + if the field name is `input_my_field` you should refer to this axis by `my_field` in the `fit_function`. + dimensions: + rank: 1 + dim: [[1, ncal]] + \@input_path: + doc: | + The path from which this data is derived, e.g., raw detector axis. + Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. + coefficients(NX_FLOAT): + unit: NX_ANY + doc: | + For non-linear energy calibrations, e.g. in a TOF, a polynomial function is fit + to a set of features (peaks) at well defined energy positions to determine + E(TOF). Here we can store the array of fit coefficients. + dimensions: + rank: 1 + dim: [[1, ncoeff]] + fit_function(NX_CHAR): + doc: | + For non-linear energy calibrations. Here we can store the formula of the + fit function. + + Use a0, a1, ..., an for the coefficients, corresponding to the values in the coefficients field. + + Use x0, x1, ..., xn for the nth position in the `original_axis` field. + If there is the symbol attribute specified for the `original_axis` this may be used instead of x. + If you want to use the whole axis use `x`. + Alternate axis can also be available as specified by the `input_SYMBOL` field. + The data should then be referred here by the `SYMBOL` name, e.g., for a field + name `input_my_field` it should be referred here by `my_field` or `my_field0` if + you want to read the zeroth element of the array. + + The formula should be numpy compliant. + scaling(NX_FLOAT): + unit: NX_ANY + doc: | + For linear calibration. Scaling parameter. + This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. + offset(NX_FLOAT): + unit: NX_ANY + doc: | + For linear calibration. Offset parameter. + This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. + mapping_MAPPING(NX_FLOAT): + doc: | + Mapping data for calibration. + + This can be used to map data points from uncalibrated to calibrated values, + i.e., by multiplying each point in the input axis by the corresponding point in the mapping data. + calibrated_axis(NX_FLOAT): + unit: NX_ANY + doc: | + A vector representing the axis after calibration, matching the data length + dimensions: + rank: 1 + dim: [[1, ncal]] + \@output_path: + doc: | + The path to which this data is written, e.g., the calibrated energy. + Should be a valid NeXus path name, e.g., /entry/data/energy. + (NXdata): + doc: | + Any data acquired/used during the calibration that does not fit the `NX_FLOAT` fields above. + NXdata groups can be used for multidimensional data which are relevant to the calibration + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6c2f680dbb28daa8ed319e3a6a06275148e93310cb1a8824ed779304d4097702 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays +# +# +# +# Number of coefficients of the calibration function +# +# +# +# +# Number of points of the calibrated and uncalibrated axes +# +# +# +# +# Subclass of NXprocess to describe post-processing calibrations. +# +# +# +# A description of the procedures employed. +# +# +# +# +# A digital persistent identifier (e.g., DOI, ISO standard) referring to a detailed description of a +# calibration method but no actual calibration data. +# +# +# +# +# A digital persistent identifier (e.g., a DOI) referring to a publicly available calibration measurement +# used for this instrument, e.g., a measurement of a known standard containing calibration information. +# The axis values may be copied or linked in the appropriate NXcalibration fields for reference. +# +# +# +# +# A file serialisation of a calibration which may not be publicly available (externally from the nexus file). +# +# This metadata can be a documentation of the source (file) or database (entry) from which pieces +# of information have been extracted for consumption (e.g. in a research data management system (RDMS)). +# It is also possible to include the actual file by using the `file` field. +# +# The axis values may be copied or linked in the appropriate NXcalibration fields for reference. +# +# +# +# +# Indicates the name of the last operation applied in the NXprocess sequence. +# +# +# +# +# Has the calibration been applied? +# +# +# +# +# Vector containing the data coordinates in the original uncalibrated axis +# +# +# +# +# +# +# The symbol of the axis to be used in the fit_function, e.g., `energy`, `E`. +# This should comply to the following naming rules (similar to python's naming rules): +# +# * A variable name must start with a letter or the underscore character +# * A variable name cannot start with a number +# * A variable name can only contain alpha-numeric characters and underscores (A-z, 0-9, and _ ) +# * Variable names are case-sensitive (age, Age and AGE are three different variables) +# +# +# +# +# The path from which this data is derived, e.g., raw detector axis. +# Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. +# +# +# +# +# +# Additional input axis to be used in the formula. +# The part after `input_` is used as the symbol to be used in the `fit_function`, i.e., +# if the field name is `input_my_field` you should refer to this axis by `my_field` in the `fit_function`. +# +# +# +# +# +# +# The path from which this data is derived, e.g., raw detector axis. +# Should be a valid NeXus path name, e.g., /entry/instrument/detector/raw. +# +# +# +# +# +# For non-linear energy calibrations, e.g. in a TOF, a polynomial function is fit +# to a set of features (peaks) at well defined energy positions to determine +# E(TOF). Here we can store the array of fit coefficients. +# +# +# +# +# +# +# +# For non-linear energy calibrations. Here we can store the formula of the +# fit function. +# +# Use a0, a1, ..., an for the coefficients, corresponding to the values in the coefficients field. +# +# Use x0, x1, ..., xn for the nth position in the `original_axis` field. +# If there is the symbol attribute specified for the `original_axis` this may be used instead of x. +# If you want to use the whole axis use `x`. +# Alternate axis can also be available as specified by the `input_SYMBOL` field. +# The data should then be referred here by the `SYMBOL` name, e.g., for a field +# name `input_my_field` it should be referred here by `my_field` or `my_field0` if +# you want to read the zeroth element of the array. +# +# The formula should be numpy compliant. +# +# +# +# +# For linear calibration. Scaling parameter. +# This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. +# +# +# +# +# For linear calibration. Offset parameter. +# This should yield the relation `calibrated_axis` = `scaling` * `original_axis` + `offset`. +# +# +# +# +# Mapping data for calibration. +# +# This can be used to map data points from uncalibrated to calibrated values, +# i.e., by multiplying each point in the input axis by the corresponding point in the mapping data. +# +# +# +# +# A vector representing the axis after calibration, matching the data length +# +# +# +# +# +# +# The path to which this data is written, e.g., the calibrated energy. +# Should be a valid NeXus path name, e.g., /entry/data/energy. +# +# +# +# +# +# Any data acquired/used during the calibration that does not fit the `NX_FLOAT` fields above. +# NXdata groups can be used for multidimensional data which are relevant to the calibration +# +# +# diff --git a/contributed_definitions/nyaml/NXcg_alpha_complex.yaml b/contributed_definitions/nyaml/NXcg_alpha_complex.yaml new file mode 100644 index 0000000000..275a5e1065 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_alpha_complex.yaml @@ -0,0 +1,78 @@ +category: base +doc: | + Computational geometry of alpha shapes or alpha wrappings about primitives. + + For details see: + + * https://dx.doi.org/10.1109/TIT.1983.1056714 for 2D, + * https://dx.doi.org/10.1145/174462.156635 for 3D, + * https://dl.acm.org/doi/10.5555/871114 for weighted, and + * https://doc.cgal.org/latest/Alpha_shapes_3 for 3D implementation + * https://doc.cgal.org/latest/Manual/packages.html#PkgAlphaWrap3 for 3D wrappings + + in CGAL, the Computational Geometry Algorithms Library. + As a starting point, we follow the conventions of the CGAL library. +# The so-called spectrum or sets of (weighted) alpha shapes includes the convex hull of a point set. +type: group +NXcg_alpha_complex(NXcg_primitive_set): + type: + doc: | + Type of alpha complex following the terminology used by CGAL for now. + + Basic means (unweighted) alpha shapes. Alpha_wrapping means meshes + created using the alpha_wrapping algorithm. + enumeration: [convex_hull, alpha_shape, alpha_wrapping] + regularize_alpha_complex(NX_BOOLEAN): + doc: | + Are singular faces removed, i.e. has the alpha complex + been regularized or not. + # R+0 means positive real number including zero which is a super set of NX_FLOAT and a sub-set of NX_NUMBER + alpha(NX_NUMBER): + doc: | + The alpha parameter, i.e. the radius of the alpha-sphere that + is used when computing the alpha complex. + unit: NX_LENGTH + # the dim: argument can be omitted to indicate that a scalar is expected + # means a length quantity, i.e. m, km, or nm is possible i.e. has to be length but no further constraints + # stating meter is a stronger constraint while m is the strongest constraint, meaning literally the value is m. + offset(NX_NUMBER): + doc: | + The offset distance parameter used when computing alpha_wrappings. + unit: NX_LENGTH + # check again carefully the CGAL documentation talks about, for 3D, the square of the radius! + point_setID(NXcg_point_set): + # basically just constraints that if you use one or more instances of NXcg_point_set + # inside an instance of NXcg_alpha_complex, name that group with the prefix "point_set" + doc: | + Point cloud for which the alpha shape or wrapping has been computed. + # this could also just be implemented as a link but how would this be possible + # unfold the NXcg_point_set and add a + # weight(NX_NUMBER): + # doc: Weights for each point + # In general, an alpha complex is a disconnected and non-pure complex, + # meaning in particular that the alpha complex may have singular faces. + # so the number of cells, faces and edges depends on how a specific alpha complex, + # i.e. an alpha-shape of S for alpha, is filtrated with respect to k < d-dimensional + # simplices. Here we assume that number_of_cells, number_of_faces, number_of_edges + # are reported assuming one filtrates these simplices according to type. + # also using the assumption the base class reports the unique vertices + # of the specifically filtrated alpha complex. + triangle_setID(NXcg_triangle_set): + doc: | + Triangle soup for which the alpha wrapping has been computed. + triangle_meshID(NXcg_triangle_set): # should be a mesh + doc: | + Triangle mesh representing the alpha complex. + # add for each triangle if desirable a notation of whether the simplex is + # exterior, regular, singular, or interior with respect to the alpha complex + # a triangulation is more than a triangle (soup)/set because there it has connectivity + # customize the NXcg_triangle_set base class members such that connectivity can be contained naturally + # we need to find also a better name for this, what people intutive understand + # as the interior, may not even exist for a given alpha value + # more specifically it is the set of filtrated cells acknowledging mode + # e.g. the interior cells of the regularized alpha complex + interior_cellsID(NXcg_tetrahedron_set): + doc: | + Set of tetrahedra representing the volume inside the alpha complex. + # document the alpha status + # https://doc.cgal.org/latest/Alpha_shapes_3/classCGAL_1_1Alpha__status.html diff --git a/contributed_definitions/nyaml/NXcg_cylinder_set.yaml b/contributed_definitions/nyaml/NXcg_cylinder_set.yaml new file mode 100644 index 0000000000..65b686032e --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_cylinder_set.yaml @@ -0,0 +1,87 @@ +category: base +doc: | + Computational geometry description of a set of cylinders. + + The radius can either be defined in the radii field or by filling both + the upper_cap_radii or lower_cap_radii field. The latter field case can + thus be used to represent truncated cones. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the space in which the members are assumed embedded. + c: | + The cardinality of the set, i.e. the number of members. +# redundant as there is NXcsg, NXquadric, NXsolid_geometry with which +# cylinder could be constructed, but NXcylinder is easier to understand +type: group +NXcg_cylinder_set(NXcg_primitive_set): + height(NX_NUMBER): + doc: | + A direction vector which is parallel to the cylinder/cone axis + and whose magnitude is the height of the cylinder/cone. + unit: NX_LENGTH + dim: (c, d) + # observe that although we claim that d is the dimensionality we have + # currently no strategy to tell it must not be d but the actual value + # equally so the symbol c, currently all we say that in the specialization + # defined here the fields radii, upper_cap_radius, and others are all having + # value arguments of the same shape, i.e. these are arrays of rank one with some length c! + # behind the dimensionality field defined either in the here defined specialization + # of NXcg_primitive_set or otherwise that variable is undefined + # alternatively one could store the center of the lower and upper cap but + # these are then no longer necessarily on the same axis + # maybe a future feature for representing skewed cylinder, but then + # one should really better use NXquadric... + radius(NX_NUMBER): + doc: | + Radius of the cylinder if all have the same radius. + unit: NX_LENGTH + radii(NX_NUMBER): + doc: | + Radii of the cylinder. + unit: NX_LENGTH + dim: (c,) + upper_cap_radii(NX_NUMBER): + doc: | + Radii of the upper circular cap. + + This field, combined with lower_cap_radius can be used to describe + (eventually truncated) circular cones. + unit: NX_LENGTH + dim: (c,) + lower_cap_radii(NX_NUMBER): + doc: | + Radii of the upper circular cap. + + This field, combined with upper_cap_radius can be used to describe + (eventually truncated) circular cones. + unit: NX_LENGTH + dim: (c,) + # properties of the cylinder + lateral_surface_area(NX_NUMBER): + doc: | + Lateral surface area + unit: NX_AREA + dim: (c,) + upper_cap_surface_area(NX_NUMBER): + doc: | + Area of the upper cap of each cylinder. + unit: NX_AREA + dim: (c,) + lower_cap_surface_area(NX_NUMBER): + doc: | + Area of the lower cap of each cylinder. + unit: NX_AREA + dim: (c,) + total_surface_area(NX_NUMBER): # example for a specialization of surface_area from the NXcg_primitive_set + doc: | + Sum of upper and lower cap areas and lateral surface area + of each cylinder. + unit: NX_AREA + dim: (c,) + # again cap, lateral surface area and volume are so trivial to compute + # do we need really storage for this or recompute on-the-fly? + # similarly to hollow sphere discussion, hollow cylinder, cylinder stack + # do wish to define intersections?, if this is the case, one + # should use the NXcsg and NXquadric descriptions? diff --git a/contributed_definitions/nyaml/NXcg_ellipsoid_set.yaml b/contributed_definitions/nyaml/NXcg_ellipsoid_set.yaml new file mode 100644 index 0000000000..9aab0dffaf --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_ellipsoid_set.yaml @@ -0,0 +1,26 @@ +category: base +doc: | + Computational geometry description of a set of ellipsoids. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the space in which the members are assumed embedded. + c: | + The cardinality of the set, i.e. the number of members. +# redundant as there is NXcsg, and NXquadric but easier to understand +type: group +NXcg_ellipsoid_set(NXcg_primitive_set): + half_axes_radius(NX_NUMBER): + doc: | + Radius of the half axes. + + Use if all ellipsoids in the set have the same half-axes. + unit: NX_LENGTH + dim: (d,) + half_axes_radii(NX_NUMBER): + doc: | + Half-axes radii of each ellipsoid. + unit: NX_LENGTH + dim: (c, d) + # properties of ellipsoids diff --git a/contributed_definitions/nyaml/NXcg_face_list_data_structure.yaml b/contributed_definitions/nyaml/NXcg_face_list_data_structure.yaml new file mode 100644 index 0000000000..4f33188c79 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_face_list_data_structure.yaml @@ -0,0 +1,155 @@ +category: base +doc: | + Computational geometry of primitives via a face-and-edge-list data structure. + + Primitives must neither be degenerated nor self-intersect but can differ in + their properties. A face-and-edge-list-based description of primitives is + frequently used for triangles and polyhedra to store them on disk for + visualization purposes (see OFF, PLY, VTK, or STL file formats). + + Although this description is storage efficient it is not well suited for + topological analyses though. In this case, scientists may need a different + view on the primitives which is better represented with e.g. a + half_edge_data_structure. + + Having an own base class for the data structure how primitives are stored is + useful to embrace both users with small or very detailed specification demands. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 2. + n_v: | + The number of vertices. + n_e: | + The number of edges. + n_f: | + The number of faces. + n_total: | + The total number of vertices of all faces. Faces are polygons. + n_weinberg: | + The total number of Weinberg vector values of all faces. +# duplicate of an NXoff_geometry ? +type: group +NXcg_face_list_data_structure(NXobject): + \@depends_on(NX_CHAR): + doc: | + Hint to help resolve in which Euclidean coordinate system + field values vertices are defined. + dimensionality(NX_POSINT): + doc: | + Dimensionality of the primitives described. + unit: NX_UNITLESS + # resulting in a design similar to that of NXoff_geometry and the XDMF mixed primitive topology + number_of_vertices(NX_INT): + doc: | + Number of vertices for each face. + + Each entry represents the total number of vertices for that face, + irrespectively whether vertices are shared among faces or not. + unit: NX_UNITLESS + dim: (n_f,) + number_of_edges(NX_INT): + doc: | + Number of edges for each face. + + Each entry represents the total number of edges for that face, + irrespectively whether edges are shared across faces or not. + unit: NX_UNITLESS + dim: (n_e,) + number_of_faces(NX_INT): + doc: | + Number of faces of the primitives. + unit: NX_UNITLESS + vertex_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the vertices differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + unit: NX_UNITLESS + edge_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the edges differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the faces differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of NXcg_primitive_set for further details. + unit: NX_UNITLESS + vertex_identifier(NX_INT): + unit: NX_UNITLESS + doc: | + Integer identifier to distinguish all vertices explicitly. + dim: (n_v,) + edge_identifier(NX_INT): + doc: | + Integer used to distinguish all edges explicitly. + unit: NX_UNITLESS + dim: (n_e,) + face_identifier(NX_INT): + doc: | + Integer used to distinguish all faces explicitly. + unit: NX_UNITLESS + dim: (n_f,) + vertices(NX_NUMBER): + doc: | + Positions of the vertices. + + Users are encouraged to reduce the vertices to a unique set as this may + result in a more efficient storage of the geometry data. + It is also possible though to store the vertex positions naively in which + case vertices_are_unique is likely False. Naively here means that each + vertex is stored even though many share the same positions. + unit: NX_ANY + dim: (n_v, d) + edges(NX_INT): + doc: | + The edges are stored as pairs of vertex identifier. + unit: NX_UNITLESS + dim: (n_e, 2) + faces(NX_INT): + doc: | + The faces are stored as a concatenated array of vertex identifier tuples. + + The first entry is the identifier of the start vertex of the first face, + followed by the second vertex of the first face, until the last vertex + of the first face. Thereafter, the start vertex of the second face, the + second vertex of the second face, and so on and so forth. + + Therefore, summating over the number_of_vertices, allows to extract + the vertex identifiers for the i-th face on the following index interval + of the faces array: :math:`[\sum_{i = 0}^{i = n-1}, \sum_{i=0}^{i = n}]`. + unit: NX_UNITLESS + dim: (n_total,) + # properties + vertices_are_unique(NX_BOOLEAN): + doc: | + If true, indicates that the vertices are all placed at different positions + and have different identifiers, i.e. no points overlap or are counted more + than once. + edges_are_unique(NX_BOOLEAN): + doc: | + If true, indicates that no edge is stored more than once. + + Users are encouraged to consider using a half_edge_data_structure instead. + faces_are_unique(NX_BOOLEAN): + doc: | + If true, indicates that no face is stored more than once. + winding_order(NX_INT): + doc: | + Specifies for each face which winding order was used if any: + + * 0 - undefined + * 1 - counter-clockwise (CCW) + * 2 - clock-wise (CW) + unit: NX_UNITLESS + dim: (n_f,) diff --git a/contributed_definitions/nyaml/NXcg_geodesic_mesh.yaml b/contributed_definitions/nyaml/NXcg_geodesic_mesh.yaml new file mode 100644 index 0000000000..0f4f9afc64 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_geodesic_mesh.yaml @@ -0,0 +1,31 @@ +category: base +doc: | + Computational geometry description of a geodesic mesh. + + A geodesic surface mesh is a triangulated surface mesh with metadata which + can be used as an approximation to describe the surface of a sphere. + Triangulation of spheres are commonly used in Materials Science + for quantifying texture of materials, i.e. the relative rotation of + crystals to sample directions. + + For additional details or an introduction into the topic of geodesic meshes + see (from which specifically the section on subdivision schemes is relevant). + + * `E. S. Popko and C. J. Kitrick `_ + + Earth scientists have specific demands and different views about what should + be included in such a base class, given that nested geodesic meshes are a key + component of climate modelling software. For now we propose to use this + base class as a container for organizing data related to geodesic meshes. + + Specifically an instance of this base class should detail the rule set how + e.g. a geodesic (surface) mesh was instantiated as there are many + possibilities to do so. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcg_geodesic_mesh(NXcg_primitive_set): + (NXcg_triangulated_surface_mesh): + + # Discussions with NFDI-Earth could make this base class more meaty and detailed. diff --git a/contributed_definitions/nyaml/NXcg_grid.yaml b/contributed_definitions/nyaml/NXcg_grid.yaml new file mode 100644 index 0000000000..de8cf9c8f3 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_grid.yaml @@ -0,0 +1,90 @@ +category: base +doc: | + Computational geometry description of a grid of Wigner-Seitz cells in Euclidean space. + + Three-dimensional grids with cubic cells are if not the most frequently used + example of such grids. Examples of numerical methods where grids are used + are spectral-solver based crystal plasticity or other stencil methods like + phase-field or cellular automata. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the grid. + c: | + The cardinality or total number of cells aka grid points. + n_b: | + Number of boundaries of the bounding box or primitive housing the grid. +type: group +NXcg_grid(NXcg_primitive_set): + origin(NX_NUMBER): + doc: | + Location of the origin of the grid. + + Use the depends_on field that is inherited from the :ref:`NXcg_primitive_set` + class to specify the coordinate system in which the origin location is defined. + unit: NX_ANY + dim: (d,) + symmetry(NX_CHAR): + doc: | + The symmetry of the lattice defining the shape of the unit cell. + enumeration: [cubic] # enumerate all other possible tilings of R^d + cell_dimensions(NX_NUMBER): + doc: | + The unit cell dimensions using crystallographic notation. + unit: NX_LENGTH + dim: (d,) + extent(NX_INT): + doc: | + Number of unit cells along each of the d unit vectors. + + The total number of cells or grid points has to be the cardinality. + If the grid has an irregular number of grid positions in each direction, + as it could be for instance the case of a grid where all grid points + outside some masking primitive are removed, this extent field should + not be used. Instead, use the coordinate field. + unit: NX_UNITLESS + dim: (d,) + # number_of_cells(NX_UINT): maybe already too trivial quantities + # should constraints on the grid be place here or not + position(NX_NUMBER): + doc: | + Position of each cell in Euclidean space. + unit: NX_ANY + dim: (c, d) + coordinate(NX_INT): + doc: | + Coordinate of each cell with respect to the discrete grid. + unit: NX_DIMENSIONLESS + dim: (c, d) + # this should be a ROI + bounding_box(NXcg_polyhedron_set): + doc: | + A tight bounding box about the grid. + # does it have to be a tight bounding box? + # a good example for a general bounding box description for such a grids of triclinic cells + # https://docs.lammps.org/Howto_triclinic.html NXcg_polyhedron because a parallelepiped + number_of_boundaries(NX_INT): + doc: | + Number of boundaries distinguished + + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + unit: NX_UNITLESS + boundaries(NX_CHAR): + doc: | + Name of domain boundaries of the simulation box/ROI + e.g. left, right, front, back, bottom, top. + dim: (n_b,) + boundary_conditions(NX_INT): + unit: NX_UNITLESS + doc: | + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + dim: (n_b,) diff --git a/contributed_definitions/nyaml/NXcg_half_edge_data_structure.yaml b/contributed_definitions/nyaml/NXcg_half_edge_data_structure.yaml new file mode 100644 index 0000000000..de58e12e70 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_half_edge_data_structure.yaml @@ -0,0 +1,130 @@ +category: base +doc: | + Computational geeometry description of a half-edge data structure. + + Such a data structure can be used to efficiently circulate around faces + and iterate over vertices of a planar graph. +# holes in the polygon mesh can be handled +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 2. + n_v: | + The number of vertices. + n_f: | + The number of faces. + n_he: | + The number of half-edges. +type: group +NXcg_half_edge_data_structure(NXobject): + \@depends_on(NX_CHAR): + doc: | + Hint to help resolve in which Euclidean coordinate system + field values vertices are defined. + dimensionality(NX_POSINT): + doc: | + Dimensionality of the primitives described. + unit: NX_UNITLESS + # resulting in a design similar to that of NXoff_geometry and the XDMF mixed primitive topology + number_of_vertices(NX_INT): + doc: | + Number of vertices for each face. + + Each entry represents the total number of vertices for that face, + irrespectively whether vertices are shared among faces or not. + unit: NX_UNITLESS + dim: (n_f,) + number_of_edges(NX_INT): + doc: | + Number of edges for each face. + + Each entry represents the total number of edges for that face, + irrespectively whether edges are shared across faces or not. + unit: NX_UNITLESS + dim: (n_e,) + number_of_faces(NX_INT): + doc: | + Number of faces of the primitives. + unit: NX_UNITLESS + vertex_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the vertices differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + unit: NX_UNITLESS + edge_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the edges differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + unit: NX_UNITLESS + face_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the faces differs from zero. + + Identifier can be defined explicitly or implicitly. + Inspect the definition of :ref:`NXcg_primitive_set` for further details. + # therefore, vertex_-, face_-, half_edge_-identifier are implicit + position(NX_NUMBER): + doc: | + The position of the vertices. + unit: NX_ANY + dim: (n_v, d) + vertex_incident_half_edge(NX_INT): + doc: | + Identifier of the incident half-edge. + unit: NX_UNITLESS + dim: (n_v,) + face_half_edge(NX_INT): + doc: | + Identifier of the (starting)/associated half-edge of the face. + unit: NX_UNITLESS + dim: (n_f,) + half_edge_vertex_origin(NX_INT): + doc: | + The identifier of the vertex from which this half-edge is outwards pointing. + unit: NX_UNITLESS + dim: (n_he,) + half_edge_twin(NX_INT): + doc: | + Identifier of the associated oppositely pointing half-edge. + unit: NX_UNITLESS + dim: (n_he,) + half_edge_incident_face(NX_INT): + doc: | + If the half-edge is a boundary half-edge the + incident face identifier is NULL, i.e. 0. + unit: NX_UNITLESS + dim: (n_he,) + half_edge_next(NX_INT): + doc: | + Identifier of the next half-edge. + unit: NX_UNITLESS + dim: (n_he,) + half_edge_prev(NX_INT): + doc: | + Identifier of the previous half-edge. + unit: NX_UNITLESS + dim: (n_he,) + weinberg_vector: + doc: | + Users are referred to the literature for the background of L. Weinberg's + work about topological characterization of planar graphs: + + * `L. Weinberg 1966a, `_ + * `L. Weinberg, 1966b, `_ + * `E. A. Lazar et al. `_ + + and how this work can e.g. be applied in space-filling tessellations + of microstructural objects like crystals/grains. + + # eventually store the Weinberg vector as an integer array + # which could be more efficient + # see https://jerryyin.info/geometry-processing-algorithms/half-edge/ + # for an illustrative example of half-edge data structures diff --git a/contributed_definitions/nyaml/NXcg_hexahedron_set.yaml b/contributed_definitions/nyaml/NXcg_hexahedron_set.yaml new file mode 100644 index 0000000000..574895a93b --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_hexahedron_set.yaml @@ -0,0 +1,128 @@ +category: base +doc: | + Computational geometry description of a set of hexahedra in Euclidean space. + + This class can also be used to describe cuboids or cubes, axis-aligned or not. + The class represents different access and description levels to offer both + applied scientists and computational geometry experts an approach whereby + different specific views can be implemented using the same base class: + + * In the simplest case experimentalists may use this base class to describe + the dimensions or size of a specimen. In this case the alignment with axes + is not relevant as eventually only the volume of the specimen is of interest. + * In many cases, take for example an experiment where a specimen was cut out + from a specifically deformed piece of material, the orientation of the + specimen's edges with the experiment coordinate system is of high relevance. + Examples include knowledge about the specimen edge, whether it is + parallel to the rolling, the transverse, or the normal direction. + * While the above-mentioned use cases are sufficient to pinpoint the sample + within a known laboratory/experiment coordinate system, these descriptions + are not detailed enough to specify e.g. a CAD model of the specimen. + * Therefore, groups and fields for an additional, computational-geometry- + based view of hexahedra is offered to serve additional computational + tasks: storage-oriented simple views or detailed topological/graph-based + descriptions. + + Hexahedra are important geometrical primitives, which are among the most + frequently used elements in finite element meshing/modeling. + + As a specialization of the :ref:`NXcg_primitive_set` base class hexahedra + are assumed non-degenerated, closed, and built of polygons that are + not self-intersecting. + + The term hexahedra will be used throughout this base class but includes + the special cases cuboid, cube, box, axis-aligned bounding box (AABB), + and optimal bounding box (OBB). + + An axis-aligned bounding box is a common data object in computational science + and simulation codes to represent a cuboid whose edges are aligned with the + base vectors of a coordinate system. As a part of binary trees, these data + objects are important for making time- as well as space-efficient queries + of geometric primitives in techniques like kd-trees. + + An optimal bounding box is a common data object which provides the best + tightly fitting box about an arbitrary object. In general, such boxes are + rotated. Exact and substantially faster in practice approximate algorithms + exist to compute optimal or near optimal bounding boxes for sets of points. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of hexahedra. +# it is useful to define own base classes for frequently used classes +# a polyhedron is a specific polytope in 3d, do we need +# higher-dimensional polytopes? that could be useful for simplicies though +# as they are used in numerics etc. maybe reach out here to our friends +# from MarDI, for now let's assume we do not need polytopes for d > 3 +type: group +NXcg_hexahedron_set(NXcg_primitive_set): + # qualifiers and properties of hexahedra + shape(NX_NUMBER): + unit: NX_LENGTH + doc: | + Qualifier for the shape of each hexahedron. + dim: (c, 3) + length(NX_NUMBER): + unit: NX_LENGTH + doc: | + Qualifier that is useful in cases when one edge is longer than all other + edges of the hexahedra. Often the term length is associated with the + assumption that one edge is parallel to an axis of the coordinate system. + dim: (c,) + width(NX_NUMBER): + unit: NX_LENGTH + doc: | + Qualifier often used to describe the extent of an object in the horizontal + direction assuming a specific coordinate system. + + For the sake of explicitness quantities like length, width, and height + should not be reported without specifying also the assumed reference frame. + dim: (c,) + height(NX_NUMBER): + doc: | + Qualifier often used to describe the extent of an object in the vertical + direction assuming a specific coordinate system. + unit: NX_LENGTH + dim: (c,) + volume(NX_NUMBER): + doc: | + Volume of each hexahedron. + unit: NX_VOLUME + dim: (c,) + area(NX_NUMBER): + doc: | + Total (surface) area (of all six faces) of each hexahedron. + unit: NX_AREA + dim: (c,) + face_area(NX_NUMBER): + doc: | + Area of each of the six faces of each hexahedron. + unit: NX_AREA + dim: (c, 6) + is_box(NX_BOOLEAN): + doc: | + Specifies if the hexahedra represent cuboids or cubes eventually rotated + ones but at least not too exotic six-faced polyhedra. + dim: (c,) + is_axis_aligned(NX_BOOLEAN): + doc: | + Only to be used if is_box is present. In this case, this field describes + whether hexahedra are boxes whose primary edges are parallel to the + axes of the coordinate system. + dim: (c,) + # substantially more detailed descriptors of the shape, the mesh + # orientation(NXorientation_set): + vertex_normal(NXcg_unit_normal_set): + edge_normal(NXcg_unit_normal_set): + face_normal(NXcg_unit_normal_set): + + # detailed mesh-based representation + hexahedra(NXcg_face_list_data_structure): + doc: | + Combined storage of all primitives of all hexahedra. + hexahedronID(NXcg_face_list_data_structure): + doc: | + Individual storage of each hexahedron. + hexahedron_half_edgeID(NXcg_half_edge_data_structure): + doc: | + Individual storage of each hexahedron as a graph. diff --git a/contributed_definitions/nyaml/NXcg_marching_cubes.yaml b/contributed_definitions/nyaml/NXcg_marching_cubes.yaml new file mode 100644 index 0000000000..d731f8103b --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_marching_cubes.yaml @@ -0,0 +1,33 @@ +category: base +doc: | + Computational geometry description of the marching cubes algorithm. + + Documenting which specific version was used helps with understanding how + robust the results are with respect to the topology of the triangulation. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcg_marching_cubes(NXobject): + grid(NXcg_grid): + doc: | + Reference/link to and/or details of the grid on which a specific + marching cubes algorithm implementation is operating. + implementation(NX_CHAR): + doc: | + Reference to the specific implementation of marching cubes used. + + See for example the following papers for details about how to identify a + DOI which specifies the implementation used: + + * `W. E. Lorensen `_ + * `T. S. Newman and H. Yi `_ + + The value placed here should be a DOI. If there are no specific DOI or + details write not_further_specified, or give at least a free-text + description. + (NXprogram): + + # we could also think about storing the rule sets in here explicitly including the + # coordinate system conventions; however, the problem is that many commercial + # tools like Matlab do not expose the rule set. diff --git a/contributed_definitions/nyaml/NXcg_parallelogram_set.yaml b/contributed_definitions/nyaml/NXcg_parallelogram_set.yaml new file mode 100644 index 0000000000..05dc7778f1 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_parallelogram_set.yaml @@ -0,0 +1,65 @@ +category: base +doc: | + Computational geometry description of a set of parallelograms. + + This class can also be used to describe rectangles or squares, irrespective + whether these are axis-aligned or not. The class represents different + access and description levels to embrace applied scientists and computational + geometry experts with their different views: + + * The simplest case is the communication of dimensions aka the size of a + region of interest in the 2D plane. In this case, communicating the + alignment with axes is maybe not as relevant as it is to report the area + of the ROI. + * In other cases the extent of the parallelogram is relevant though. + * Finally, in CAD models it should be possible to specify the polygons + which the parallelograms represent with exact numerical details. + + Parallelograms are important geometrical primitives as their usage for + describing many scanning experiments shows where typically parallelogram-shaped + ROIs are scanned across the surface of a sample. + + The term parallelogram will be used throughout this base class thus including + the important special cases rectangle, square, 2D box, axis-aligned bounding box + (AABB), or optimal bounding box (OBB) as analogous 2D variants to their 3D + counterparts. See :ref:`NXcg_hexahedron_set` for the generalization in 3D. + + An axis-aligned bounding box is a common data object in computational science + and simulation codes to represent a rectangle whose edges are aligned with the + axes of a coordinate system. As a part of binary trees AABBs are important data + objects for executing time- as well as space-efficient queries + of geometric primitives in techniques like kd-trees. + + An optimal bounding box is a common data object which provides the best, i.e. + most tightly fitting box about an arbitrary object. In general such boxes are + rotated. Other than in 3D dimensions, the rotation calipher method offers + a rigorous approach to compute an optimal bounding box to a point set in 2D. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of parallelograms. +type: group +NXcg_parallelogram_set(NXcg_primitive_set): + # qualifiers and properties of parallelograms + is_rectangle(NX_BOOLEAN): + doc: | + To specify which parallelogram is a rectangle. + dim: (c,) + is_axis_aligned(NX_BOOLEAN): + doc: | + Only to be used if is_rectangle is present. In this case, this field + describes whether parallelograms are rectangles whose primary edges + are parallel to the axes of the coordinate system. + dim: (c,) + # detailed mesh-based representation + parallelograms(NXcg_face_list_data_structure): + # exists: [min, 0, max, 1] + doc: | + Combined storage of all primitives of all parallelograms. + parallelogramID(NXcg_face_list_data_structure): + doc: | + Individual storage of each parallelogram. + ##MK::parallelogram_half_edgeID(NXcg_half_edge_data_structure) + # a half-edge structure would be overkill as this is a simple primitive + diff --git a/contributed_definitions/nyaml/NXcg_point_set.yaml b/contributed_definitions/nyaml/NXcg_point_set.yaml new file mode 100644 index 0000000000..673953b0c6 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_point_set.yaml @@ -0,0 +1,43 @@ +category: base +doc: | + Computational geometry description of a set of points. + + Points may have an associated time value. Users are advised though to store + time data of point sets rather as instances of time events, where for each + point in time there is an :ref:`NXcg_point_set` instance which specifies the + points' locations. + + This is a frequent situation in experiments and computer simulations, where + positions of points are taken at the same point in time (real time or + simulated physical time). Thereby, the storage of redundant time stamp + information per point is considered as obsolete. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality. + c: | + The cardinality of the set, i.e. the number of points. +type: group +NXcg_point_set(NXcg_primitive_set): + position(NX_NUMBER): + doc: | + Coordinates of the points. + unit: NX_ANY + dim: (c, d) + time(NX_NUMBER): + doc: | + (Elapsed) time for each point. + + If the field time is needed contextualize the time_offset relative to which + time values are defined. Alternative store timestamp. + unit: NX_TIME + dim: (c,) + timestamp(NX_DATE_TIME): + doc: | + ISO8601 with local time zone offset for each point. + dim: (c,) + time_offset(NX_DATE_TIME): + doc: | + ISO8601 with local time zone offset that serves as the reference + for values in the field time. diff --git a/contributed_definitions/nyaml/NXcg_polygon_set.yaml b/contributed_definitions/nyaml/NXcg_polygon_set.yaml new file mode 100644 index 0000000000..6f712610ff --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_polygon_set.yaml @@ -0,0 +1,79 @@ +category: base +# somewhat redundant as there is NXoff_geometry but easier to understand +doc: | + Computational geometry description of a set of polygons in Euclidean space. + + Polygons are specialized polylines: + + * A polygon is a geometric primitive that is bounded by a closed polyline + * All vertices of this polyline lay in the d-1 dimensional plane. + whereas vertices of a polyline do not necessarily lay on a plane. + * A polygon has at least three vertices. + + Each polygon is built from a sequence of vertices (points with identifiers). + The members of a set of polygons may have a different number of vertices. + Sometimes a collection/set of polygons is referred to as a soup of polygons. + + As three-dimensional objects, a set of polygons can be used to define the + hull of what is effectively a polyhedron; however users are advised to use + the specific :ref:`NXcg_polyhedron_set` base class if they wish to describe closed + polyhedra. Even more general complexes can be thought of. An example are the + so-called piecewise-linear complexes used in the TetGen library. + + As these complexes can have holes though, polyhedra without holes are one + subclass of such complexes, users should rather design an own + base class e.g. NXcg_polytope_set to describe such even more + complex primitives instead of abusing this base class for such purposes. +# Users can take advantage of NXcg_polygon_set to describe such complexes +# when using the defines_plc and related topological and boundary constraint +# descriptors. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be either 2 or 3. + c: | + The cardinality of the set, i.e. the number of polygons. + # n_unique: Number of unique points supporting the polygons. + n_total: | + The total number of vertices when visiting every polygon. +type: group +NXcg_polygon_set(NXcg_primitive_set): + number_of_total_vertices(NX_INT): + doc: | + The total number of vertices in the set. + unit: NX_UNITLESS + # detailed mesh-based representation + polygons(NXcg_face_list_data_structure): + doc: | + Combined storage of all primitives of all polygons. + polygonID(NXcg_face_list_data_structure): + doc: | + Individual storage of the mesh of each polygon. + polygon_half_edgeID(NXcg_half_edge_data_structure): + doc: | + Individual storage of each polygon as a graph. + # properties of the polygon primitives + edge_length(NX_NUMBER): + doc: | + For each polygon its accumulated length along its edges. + unit: NX_LENGTH + dim: (c,) + interior_angle(NX_NUMBER): + doc: | + Interior angles for each polygon. There are as many values per polygon + as the are number_of_vertices. + The angle is the angle at the specific vertex, i.e. between the adjoining + edges of the vertex according to the sequence in the polygons array. + Usually, the winding_order field is required to interpret the value. + unit: NX_ANGLE + dim: (n_total,) + shape(NX_INT): + doc: | + Curvature type: + + * 0 - unspecified, + * 1 - convex, + * 2 - concave + unit: NX_UNITLESS + dim: (c,) diff --git a/contributed_definitions/nyaml/NXcg_polyhedron_set.yaml b/contributed_definitions/nyaml/NXcg_polyhedron_set.yaml new file mode 100644 index 0000000000..9285618b3b --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_polyhedron_set.yaml @@ -0,0 +1,62 @@ +category: base +doc: | + Computational geometry description of a set of polyhedra in Euclidean space. + + Polyhedra or so-called cells (especially in the convex of tessellations) are + constructed from polygon meshes. Polyhedra may make contact to allow a usage + of this base class for a description of tessellations. + + For the description of more complicated manifolds and especially for polyhedra + with holes, users are advised to check if their particular needs are described + by creating customized instances of an :ref:`NXcg_polygon_set`. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of polyhedra. + n_e_total: | + The total number of edges for all polyhedra. + n_f_total: | + The total number of faces for all polyhedra. +# it is useful to define own base classes for frequently used classes +# a polyhedron is a specific polytope in 3d, do we need +# higher-dimensional polytopes? that could be useful for simplicies though +# as they are used in numerics etc. maybe reach out here to our friends +# from MarDI, for now let's assume we do not need polytopes for d > 3 +# NeXus already supports polyhedra via NXoff_geometry +# the here proposed base class extends the capabilities to qualifiers of +# polyhedra and also half_edge_data_structures that can be useful +# for clean graph-based descriptions of polyhedra. +type: group +NXcg_polyhedron_set(NXcg_primitive_set): + # qualifiers and properties of polyhedra + number_of_faces(NX_INT): + doc: | + The number of faces for each polyhedron. Faces of adjoining polyhedra + are counted for each polyhedron. + unit: NX_UNITLESS + dim: (c,) + face_area(NX_NUMBER): + doc: | + Area of each of faces. + unit: NX_AREA + dim: (n_f_total,) + number_of_edges(NX_INT): + doc: | + The number of edges for each polyhedron. Edges of adjoining polyhedra + are counterd for each polyhedron. + edge_length(NX_NUMBER): + doc: | + Length of each edge. + unit: NX_LENGTH + dim: (n_e_total,) + # detailed mesh-based representation + polyhedra(NXcg_face_list_data_structure): + doc: | + Combined storage of all primitives of all polyhedra. + polyhedronID(NXcg_face_list_data_structure): + doc: | + Individual storage of each polyhedron. + polyhedron_half_edgeID(NXcg_half_edge_data_structure): + doc: | + Individual storage of each polygon as a graph. diff --git a/contributed_definitions/nyaml/NXcg_polyline_set.yaml b/contributed_definitions/nyaml/NXcg_polyline_set.yaml new file mode 100644 index 0000000000..bef7167078 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_polyline_set.yaml @@ -0,0 +1,93 @@ +category: base +doc: | + Computational geometry description of a set of polylines. + + Each polyline is built from a sequence of vertices (points with identifiers). + Each polyline must have a start and an end point. + The sequence describes the positive traversal along the polyline when + walking from the first to the last vertex. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 1. + c: | + The cardinality of the set, i.e. the number of polylines. + # n_unique: The number of unique vertices supporting the polyline. + # multiple vertices possible with the same point coordinates but different names. + n_v: | + The number of vertices, supporting the polylines. + n_total: | + The total number of vertices traversed when visiting every polyline. +type: group +NXcg_polyline_set(NXcg_primitive_set): + \@depends_on(NX_CHAR): + doc: | + Reference to an instance of :ref:`NXcg_point_set` which defines + the location of the vertices that are referred to in the + NXcg_polyline_set instance. + number_of_unique_vertices(NX_POSINT): + doc: | + The total number of vertices that have different positions. + unit: NX_UNITLESS + number_of_total_vertices(NX_INT): + doc: | + The total number of vertices, irrespective of their eventual uniqueness. + unit: NX_UNITLESS + number_of_vertices(NX_INT): + doc: | + The total number of vertices of each polyline, irrespectively + whether vertices are shared by vertices or not. + See the docstring for polylines for further details about how + a set with different polyline members should be stored. + unit: NX_UNITLESS + dim: (c,) + # Users are encouraged to reduce the vertex set to the unique vertices. + # Unique means not necessarily unique in position only but also unique in + # identifier. In fact, it is possible to distinguish two vertices as two when + # they share the same position in space but have different identifiers. + vertices(NX_NUMBER): + doc: | + Positions of the vertices which support the members of the polyline set. + + Users are encouraged to reduce the vertices to unique positions and vertices + as this often supports with storing geometry data more efficiently. + It is also possible though to store the vertex positions naively + in which case vertices_are_unique is likely False. + Naively, here means that one stores each vertex of a triangle mesh + even though many vertices are shared between triangles and thus + storing multiple copies of their positions is redundant. + unit: NX_ANY + dim: (n_v, d) + # alternatively we may store the actual vertices in an instance of + # NXcg_point_set and (e.g. to promote compact storage of information and primitives) + # and then use + + vertices_are_unique(NX_BOOLEAN): + doc: | + If true indicates that the vertices are all placed at different + positions and have different identifiers, i.e. no points overlap + or are counted several times. + polylines(NX_INT): + doc: | + Sequence of identifier for vertices how they build each polyline. + + A trivial example is a set with two polylines with three vertices each. + If the polylines meet in a junction, say the second vertex is shared + and marking the junction between the two polylines, it is possible that + there are only five unique positions. This suggests to store five + unique vertices. + + A non-trivial example is a set with several polylines. Assume that each + has a different number of vertices. The array stores the identifier of + the vertices in the sequence how the polylines are visited: + + The first entry is the identifier of the first vertex of the first polyline, + followed by the second vertex of the first polyline, until the last vertex + of the first polyline. + Thereafter, the first vertex of the second polyline, and so on and so forth. + Using the (cumulated) counts in number_of_vertices, the vertices of the + n-th polyline can be accessed on the following array index interval: + :math:`[\sum_{i=0}^{i=N-1}, \sum_{i=0}^{i=N}]`. + unit: NX_UNITLESS + dim: (n_total,) diff --git a/contributed_definitions/nyaml/NXcg_primitive_set.yaml b/contributed_definitions/nyaml/NXcg_primitive_set.yaml new file mode 100644 index 0000000000..586929596f --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_primitive_set.yaml @@ -0,0 +1,136 @@ +category: base +doc: | + Computational geometry description of a set of primitives in Euclidean space. + + Primitives must neither be degenerated nor self-intersect. + Individual primitives can differ in their properties (e.g. size, shape, rotation). +# this base class defines common fields and properties of geometric primitives +# more complex primitive sets like NXcg_cylinder_set are considered specializations +# of NXcg_primitive_set. They contain all fields and groups which NXcg_primitive_set +# defines. This is an action of compositing an information set; an act of inheriting +# TODO:: many properties of non-degenerate primitives are in the number set +# R+ instead of in R+0 but currently NeXus does not allow for such value range +# constraints unless the coarsely discretized NX_INT, NX_POSINT, NX_FLOAT +# but there is no say NX_FLOAT+0 +# MK::but in computational geometry numerical precision matters as it defines +# whether objects numerically intersect or not and thus it can make a real difference +# if one stores triangles with 16, 32, or 64 bit precision, however: +# are two triangle_set instance A and B no longer conceptually triangle sets +# because A stores the positions of vertices using int8 while B stores such using float64 ? +# we here assume that we still conceptually talk that A and B are triangle sets +# but this brings at the level of the application definition the problem that if the +# precision is not properly constrainted a consuming application will not obtain +# the instances of the concept triangle_set with relevant high enough precision +# and thus neither the base class nor the application definition is specific enough +# for what it was designed in the first place - be specific about the requirements +# on your data... +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the space. + c: | + The cardinality of the set, i.e. the number of members. +type: group +NXcg_primitive_set(NXobject): + # individual specializations like NXcg_polyline_set typically overwrite + # the meaning of the depends_on concept to build consistent inference chains + # to enable an instantiation of the actual geometric primitives + \@depends_on(NX_CHAR): + doc: | + Hint to help resolve in which Euclidean coordinate system field values + like center or orientation are defined. + dimensionality(NX_POSINT): + doc: | + The dimensionality of the primitive set. + unit: NX_UNITLESS + enumeration: [1, 2, 3] + cardinality(NX_POSINT): + doc: | + The cardinality of the primitive set. + unit: NX_UNITLESS + identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + Therefore, implicit identifier are completely defined by the value of + identifier_offset and cardinality. For example if identifier run from + -2 to 3 the value for identifier_offset is -2. + + For explicit indexing the field identifier has to be used. + Fortran-/Matlab- and C-/Python-style indexing have specific implicit + identifier conventions where identifier_offset is 1 and 0 respectively. + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Identifier of each member for explicit indexing. + dim: (c,) # numpy style indexing + center(NX_NUMBER): + doc: | + The center of mass position of each primitive. + unit: NX_ANY + dim: (c, d) + # a depends_on to define in which coordinate system + is_center_of_mass(NX_BOOLEAN): + doc: | + True if the center is a center of mass. + dim: (c,) + shape(NX_NUMBER): + doc: | + A qualitative description of the shape of each primitive. + unit: NX_LENGTH + dim: (c, d) + length(NX_NUMBER): + doc: | + Qualifier for the length of characteristic features of the primitive. + + Often the term length is associated with the assumption that one + edge is parallel to an axis of the coordinate system. + unit: NX_LENGTH + dim: (c,) + width(NX_NUMBER): + doc: | + Qualifier often used to describe the length of one characteristic edge + within the coordinate system. + unit: NX_LENGTH + dim: (c,) + is_closed(NX_BOOLEAN): + doc: | + True if primitive is closed such that it has properties like area or volume. + dim: (c,) + volume(NX_NUMBER): + doc: | + Volume of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + unit: NX_VOLUME + dim: (c,) + area(NX_NUMBER): + doc: | + Alias for surface_area of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + unit: NX_AREA + dim: (c,) + orientation(NX_NUMBER): + doc: | + Direction unit vector which points along the + longest principal axis of each primitive. + + Use the depends_on attribute to specify in which coordinate system + these direction unit vectors are defined. + unit: NX_DIMENSIONLESS + dim: (c, d) + vertex_normal(NXcg_unit_normal_set): + edge_normal(NXcg_unit_normal_set): + face_normal(NXcg_unit_normal_set): + # roi(NXcg_parallelogram_set or NXcg_hexahedron_set) + # aabb(NXcg_parallelogram_set or NXcg_hexahedron_set) + # obb(NXcg_parallelogram_set or NXcg_hexahedron_set) + # MK::one could add (NXcg_parallelogram_set) and/or (NXcg_hexahedron_set) + # but then one would not give any hint at the base class level how to name diff --git a/contributed_definitions/nyaml/NXcg_roi_set.yaml b/contributed_definitions/nyaml/NXcg_roi_set.yaml new file mode 100644 index 0000000000..b10a341fe0 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_roi_set.yaml @@ -0,0 +1,33 @@ +category: base +doc: | + Base class for a region-of-interest (ROI) bound by geometric primitives. + + So-called region-of-interest(s) (ROIs) are typically used to describe a + region in space (and time) where an observation is made or for which + a computer simulation is performed with given boundary conditions. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + + Use the depends_on fields of the respective specialized :ref:`NXcg_primitive_set` + base class surplus :ref:`NXcoordinate_system_set` with at least one instance + of :ref:`NXcoordinate_system` to define explicitly the reference frame in + which the primitives are defined. + + Alternatively, although disencouraged, one may use one :ref:`NXcoordinate_system_set` + with with only one :ref:`NXcoordinate_system` in the application definition + to specify implicitly in which reference frame the primitives are defined. + + If none of these two possibilities is used all primitives are assumed + defined in the McStas coordinate system. +# eventually redundant NXsolid_geometry? +type: group +NXcg_roi_set(NXobject): + (NXcg_sphere_set): + (NXcg_ellipsoid_set): + (NXcg_cylinder_set): + (NXcg_parallelogram_set): + (NXcg_hexahedron_set): + (NXcg_polyhedron_set): + # how to handle cases where multiple primitives should be included? + # see comment to NXcg_triangle_set roi diff --git a/contributed_definitions/nyaml/NXcg_sphere_set.yaml b/contributed_definitions/nyaml/NXcg_sphere_set.yaml new file mode 100644 index 0000000000..c6b6e1d59b --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_sphere_set.yaml @@ -0,0 +1,25 @@ +category: base +doc: | + Computational geometry description of a set of spheres. + + Each sphere can have a different radius but all need to have finite volume. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 2. + c: | + The cardinality of the set, i.e. the number of circles or spheres. +# redundant as there is NXcsg, and NXquadric but easier to understand +type: group +NXcg_sphere_set(NXcg_ellipsoid_set): + radius(NX_NUMBER): + doc: | + In the case that all spheres have the same radius. + unit: NX_LENGTH + radii(NX_NUMBER): + doc: | + In the case that spheres have different radius use this + instead of the radius field. + unit: NX_LENGTH + dim: (c,) diff --git a/contributed_definitions/nyaml/NXcg_tetrahedron_set.yaml b/contributed_definitions/nyaml/NXcg_tetrahedron_set.yaml new file mode 100644 index 0000000000..1200fc9e10 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_tetrahedron_set.yaml @@ -0,0 +1,44 @@ +category: base +doc: | + Computational geometry description of a set of tetrahedra. + + Among hexahedral elements, tetrahedral elements are one of the most + frequently used geometric primitive for meshing and describing volumetric + objects in continuum-field simulations. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of tetrahedra. +type: group +NXcg_tetrahedron_set(NXcg_primitive_set): + # qualifiers and properties of tetrahedra + face_area(NX_NUMBER): + doc: | + Area of each of the four triangular faces of each tetrahedron. + unit: NX_AREA + dim: (c, 4) + edge_length(NX_NUMBER): + doc: | + Length of each edge of each tetrahedron. + unit: NX_LENGTH + dim: (c, 6) + # substantially more detailed descriptors of the shape, the mesh + # currently not used should be discussed as sequence might not be clear to everybody + # interior_angle(NX_NUMBER): + # doc: | + # Interior angle values for each tetrahedron. + # The quadruplet of angles is a sequence following the order of the vertices. + # The angle is the angle at the specific vertex. + # + # The sequence of the vertices follows their definition in tetrahedra. + # detailed mesh-based representation + tetrahedra(NXcg_face_list_data_structure): + doc: | + Combined storage of all primitives of all tetrahedra. + tetrahedronID(NXcg_face_list_data_structure): + doc: | + Individual storage of each tetrahedron. + tetrahedron_half_edgeID(NXcg_half_edge_data_structure): + doc: | + Individual storage of each tetrahedron as a graph. diff --git a/contributed_definitions/nyaml/NXcg_triangle_set.yaml b/contributed_definitions/nyaml/NXcg_triangle_set.yaml new file mode 100644 index 0000000000..5eb5b915eb --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_triangle_set.yaml @@ -0,0 +1,50 @@ +category: base +doc: | + Computational geometry description of a set of triangles. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 2. + c: | + The cardinality of the set, i.e. the number of triangles. + n_unique: | + The number of unique vertices supporting the triangles. +type: group +NXcg_triangle_set(NXcg_primitive_set): + number_of_unique_vertices(NX_INT): + doc: | + Number of unique vertices in the triangle set. + unit: NX_UNITLESS + triangles(NXcg_face_list_data_structure): + doc: | + Combined storage of all primitives of all triangles. + + This description resembles the typical representation of primitives + in file formats such as OFF, PLY, VTK, or STL. + triangleID(NXcg_face_list_data_structure): + doc: | + Individual storage of each triangle. + Users are advised that using such individual storage of primitives + may be less storage efficient than creating a combined storage. + # ##MK::considered too trivial: + # triangle_half_edgeID(NXcg_half_edge_data_structure): + # doc: | + # Individual storage of each triangle as a graph. + # properties of triangles + edge_length(NX_NUMBER): + doc: | + Length of the edges of each triangle. + + For each triangle values are reported via traversing + the vertices in the sequence as these are defined. + unit: NX_LENGTH + dim: (c, 3) + interior_angle(NX_NUMBER): + doc: | + Interior angles of each triangle. + + For each triangle values are reported for the angle opposite + to the respective edges in the sequence how vertices are defined. + unit: NX_ANGLE + dim: (c, 3) diff --git a/contributed_definitions/nyaml/NXcg_triangulated_surface_mesh.yaml b/contributed_definitions/nyaml/NXcg_triangulated_surface_mesh.yaml new file mode 100644 index 0000000000..927134bb85 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_triangulated_surface_mesh.yaml @@ -0,0 +1,15 @@ +category: base +doc: | + Computational geometry description of a mesh of triangles. + + The mesh may be self-intersecting and have holes but the + triangles used must not be degenerated. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcg_triangulated_surface_mesh(NXcg_triangle_set): + (NXcg_half_edge_data_structure): + doc: | + A graph-based approach to describe the mesh when it is also desired + to perform topological processing or analyses on the mesh. diff --git a/contributed_definitions/nyaml/NXcg_unit_normal_set.yaml b/contributed_definitions/nyaml/NXcg_unit_normal_set.yaml new file mode 100644 index 0000000000..1f293365d8 --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_unit_normal_set.yaml @@ -0,0 +1,37 @@ +category: base +doc: | + Computational geometry description of a set of (oriented) unit normal vectors. + + Store normal vector information as properties of primitives. + Use only only as a child of an instance of :ref:`NXcg_primitive_set` + so that this instance acts as the parent to define a context. +# eventually remove this base class and make normal vector a property of the primitive +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality, which has to be at least 2. + c: | + The cardinality of the set, i.e. the number of unit normals. + +# the benefit of NXcg_point_set is that the origin is 0 by default +# how to resolve the association between the unit normal and its associated primitive? +# rather make this a set of vectors, irrespective whether these are unit or not +type: group +NXcg_unit_normal_set(NXobject): + normals(NX_NUMBER): + doc: | + Direction of each normal - a unit normal. + unit: NX_LENGTH # length is normalized to 1 but it remains a length quantity + dim: (c, d) + orientation(NX_INT): + doc: | + Qualifier which details the orientation of each normal vector + in relation to its primitive, assuming the object is viewed + from a position outside the object. + + * 0 - undefined + * 1 - outer unit normal vector + * 2 - inner unit normal vector + unit: NX_UNITLESS + dim: (c,) diff --git a/contributed_definitions/nyaml/NXchamber.yaml b/contributed_definitions/nyaml/NXchamber.yaml new file mode 100644 index 0000000000..2a4d2c4495 --- /dev/null +++ b/contributed_definitions/nyaml/NXchamber.yaml @@ -0,0 +1,14 @@ +category: base +doc: | + Base class for a chamber in an instrument that stores real or simulated objects. +type: group +NXchamber(NXobject): + name(NX_CHAR): + doc: | + Given name for the chamber of this component e.g. analysis chamber + or buffer chamber, load-lock chamber, microscope column, glove box. + description(NX_CHAR): + doc: | + Free-text field for describing details about the chamber. + For example out of which material was the chamber built. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXchemical_composition.yaml b/contributed_definitions/nyaml/NXchemical_composition.yaml new file mode 100644 index 0000000000..4656b10dd8 --- /dev/null +++ b/contributed_definitions/nyaml/NXchemical_composition.yaml @@ -0,0 +1,110 @@ +category: base +doc: | + (Chemical) composition of a sample or a set of things. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n: | + The number of samples or things. +type: group +NXchemical_composition(NXobject): + + # molecule descriptor + # chemical_formula: + # doc: | + # IUPAC chemical formula + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total based on which composition information is normalized. + dimensions: + rank: 1 + dim: [[1, n]] + ION(NXion): + count(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total yields the composition + of this element, isotope, molecule or ion. + dimensions: + rank: 1 + dim: [[1, n]] + composition(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Count divided by total in atom percent. + dimensions: + rank: 1 + dim: [[1, n]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# dcbe5c04c6c94a2087662d892db25152b6af759a9841a0a127cf6c3859d10592 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The number of samples or things. +# +# +# +# +# (Chemical) composition of a sample or a set of things. +# +# +# +# +# Total based on which composition information is normalized. +# +# +# +# +# +# +# +# +# Count or weight which, when divided by total yields the composition +# of this element, isotope, molecule or ion. +# +# +# +# +# +# +# +# Count divided by total in atom percent. +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXchemical_process.yaml b/contributed_definitions/nyaml/NXchemical_process.yaml new file mode 100644 index 0000000000..68f117c3f1 --- /dev/null +++ b/contributed_definitions/nyaml/NXchemical_process.yaml @@ -0,0 +1,90 @@ +category: base +doc: | + A planned or unplanned process which results in chemical changes (i.e., changes in the chemical bonds) in a specified material. + + Examples include any chemical reactions (addition, subtraction, replacement, ...). +type: group +NXchemical_process(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process ended. + description: + doc: | + Short description of the chemical process. + method: + doc: | + Method by which this process was performed. + notes(NXnote): + doc: | + This can be any data or other descriptor acquired during the chemical process + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9ab9d17820c3d4b4853123d5dc1181d8a2a008936a1a67bf83913552bfeaf033 +# +# +# +# +# +# A planned or unplanned process which results in chemical changes (i.e., changes in the chemical bonds) in a specified material. +# +# Examples include any chemical reactions (addition, subtraction, replacement, ...). +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this process started. +# +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this process ended. +# +# +# +# +# Short description of the chemical process. +# +# +# +# +# Method by which this process was performed. +# +# +# +# +# This can be any data or other descriptor acquired during the chemical process +# (NXnote allows to add pictures, audio, movies). Alternatively, a +# reference to the location or a unique identifier or other metadata file. In the +# case these are not available, free-text description. +# +# +# diff --git a/contributed_definitions/nyaml/NXcircuit.yaml b/contributed_definitions/nyaml/NXcircuit.yaml new file mode 100644 index 0000000000..4e4adec032 --- /dev/null +++ b/contributed_definitions/nyaml/NXcircuit.yaml @@ -0,0 +1,227 @@ +category: base +doc: | + Application definition for circuit devices. +type: group +NXcircuit(NXobject): + hardware(NXfabrication): + doc: | + Hardware type used in circuit, includes hardware manufacturers and type + tunneling_current(NX_NUMBER): + unit: NX_CURRENT + doc: | + The tunneling current between tip and sample after application of bias voltage. + calibration(NX_NUMBER): + doc: | + Calibration of the current measurement (A/V). + offset(NX_NUMBER): + unit: NX_CURRENT + doc: | + Offset of the current measurement. + gain(NX_NUMBER): + doc: | + Proportional relationship between the probe output voltage and the actual + tunneling current when measuring the tunneling current. + channels(NX_CHAR): + doc: | + The scan channels are selected by users (in scan contronaller). + rt_frequency(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + The bandwitdh of the Hardware and/or Software + signals_oversampling(NX_NUMBER): + unit: NX_ANY + doc: | + (Signals Periods) The Signals Period is the rate at which the signals are + transferred to the host computer running the control software. This is usually + lower by a factor of 10 than the sampling rate, because an internal oversampling + of the signal is done on the real time engine. You can reduce the oversampling + down to 1 in order to resolve higher frequencies in the Spectrum Analyzer. + acquisition_period(NX_NUMBER): + unit: NX_TIME + doc: | + Update rate for several processes like History Graph, Auto-Approach, and for + many Programming Interface functions. This is usually set to 20 ms. All + additional timings (7-9) can only be integer multiples of this value. They can + be set to different values, but the actual timing value will be coerced to a + multiple of the Acquisition Period. + animations_period(NX_NUMBER): + unit: NX_TIME + doc: | + Update rate of animated graphical indicators. These are e.g. some graphs & + sliders. A reasonable value is 40 ms (25 updates per second). Increase this + period to reduce the processor load for the graphical user interface, especially + on slow computers. This value is purely a user interface update rate and does + not affect measurements in any way. + indicators_period(NX_NUMBER): + unit: NX_TIME + doc: | + Update rate of digital indicators, e.g. the numbers displayed besides each + slider. Here, 3 updates per second, or 300 ms is enough. This value is purely a + user interface update rate and does not affect measurements in any way. + measurements_period(NX_NUMBER): + unit: NX_TIME + doc: | + The Measurements period is the integration time for precise measurements + (averaging over specified period), mostly used in sweep modules. Examples are + recording of a force-distance curve or a resonance of a cantilever. For fast + measurements with small steps, a value of 40 ms may be reasonable. For normal + use, 300-500 ms is a good value, but for recording a resonance of a high-Q + cantilever, values of several seconds might be necessary. Usually this parameter + doesn’t need to be set from this module; the sweep modules will set this value + according to the sweep timings. + number_of_outputs(NX_INT): + doc: | + Number of output channels + output_mode(NX_CHAR): + doc: | + The user output in each monitor mode. + output_value(NX_NUMBER): + unit: NX_ANY + doc: | + The values for each output channel. + output_name(NX_CHAR): + doc: | + User outputs whose name can be modified in the corresponding module. + output_slew_rate(NX_CHAR): + doc: | + The rate at which the one of the signal changes when ramping to the starting + point. (V/s) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 572c9e0f471453e5d17c0e86bde59fde7aef0a8a782b5f0f69ba53b412449a89 +# +# +# +# +# +# Application definition for circuit devices. +# +# +# +# Hardware type used in circuit, includes hardware manufacturers and type +# +# +# +# +# The tunneling current between tip and sample after application of bias voltage. +# +# +# +# +# Calibration of the current measurement (A/V). +# +# +# +# +# Offset of the current measurement. +# +# +# +# +# Proportional relationship between the probe output voltage and the actual +# tunneling current when measuring the tunneling current. +# +# +# +# +# The scan channels are selected by users (in scan contronaller). +# +# +# +# +# The bandwitdh of the Hardware and/or Software +# +# +# +# +# (Signals Periods) The Signals Period is the rate at which the signals are +# transferred to the host computer running the control software. This is usually +# lower by a factor of 10 than the sampling rate, because an internal oversampling +# of the signal is done on the real time engine. You can reduce the oversampling +# down to 1 in order to resolve higher frequencies in the Spectrum Analyzer. +# +# +# +# +# Update rate for several processes like History Graph, Auto-Approach, and for +# many Programming Interface functions. This is usually set to 20 ms. All +# additional timings (7-9) can only be integer multiples of this value. They can +# be set to different values, but the actual timing value will be coerced to a +# multiple of the Acquisition Period. +# +# +# +# +# Update rate of animated graphical indicators. These are e.g. some graphs & +# sliders. A reasonable value is 40 ms (25 updates per second). Increase this +# period to reduce the processor load for the graphical user interface, especially +# on slow computers. This value is purely a user interface update rate and does +# not affect measurements in any way. +# +# +# +# +# Update rate of digital indicators, e.g. the numbers displayed besides each +# slider. Here, 3 updates per second, or 300 ms is enough. This value is purely a +# user interface update rate and does not affect measurements in any way. +# +# +# +# +# The Measurements period is the integration time for precise measurements +# (averaging over specified period), mostly used in sweep modules. Examples are +# recording of a force-distance curve or a resonance of a cantilever. For fast +# measurements with small steps, a value of 40 ms may be reasonable. For normal +# use, 300-500 ms is a good value, but for recording a resonance of a high-Q +# cantilever, values of several seconds might be necessary. Usually this parameter +# doesn’t need to be set from this module; the sweep modules will set this value +# according to the sweep timings. +# +# +# +# +# Number of output channels +# +# +# +# +# The user output in each monitor mode. +# +# +# +# +# The values for each output channel. +# +# +# +# +# User outputs whose name can be modified in the corresponding module. +# +# +# +# +# The rate at which the one of the signal changes when ramping to the starting +# point. (V/s) +# +# +# diff --git a/contributed_definitions/nyaml/NXcircuit_board.yaml b/contributed_definitions/nyaml/NXcircuit_board.yaml new file mode 100644 index 0000000000..c3c3d044e7 --- /dev/null +++ b/contributed_definitions/nyaml/NXcircuit_board.yaml @@ -0,0 +1,67 @@ +category: base +doc: | + Circuit board with e.g. ADC and/or DAC electronic components. + + Currently used to store the settings of the so-called magboards used in + Nion electron microscopes but likely this could be a useful base class for + substantially more use cases where details at a deep technical instrument design + level are relevant or important. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcircuit_board(NXobject): + relay(NX_NUMBER): + unit: NX_UNITLESS + doc: | + TBD by Nion Co. + (NXdac): + (NXadc): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b720e7a4089ff6b669d026c44b1d610485fe501d8ebc34ca5f367e65bf99066a +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Circuit board with e.g. ADC and/or DAC electronic components. +# +# Currently used to store the settings of the so-called magboards used in +# Nion electron microscopes but likely this could be a useful base class for +# substantially more use cases where details at a deep technical instrument design +# level are relevant or important. +# +# +# +# TBD by Nion Co. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXclustering.yaml b/contributed_definitions/nyaml/NXclustering.yaml new file mode 100644 index 0000000000..fe14504583 --- /dev/null +++ b/contributed_definitions/nyaml/NXclustering.yaml @@ -0,0 +1,206 @@ +category: base +doc: | + Metadata to the results of a clustering analysis. + + Clustering algorithms are routine tools to segment a set of objects/primitives + into groups, objects of different type. A plethora of algorithms have been + proposed for geometric primitives as objects, such as points, triangles, + or (abstract) objects. + + This base class considers metadata and results of one clustering + applied to a set in which objects are either categorized as noise + or belonging to a cluster, specifically here only one cluster. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_lbl_num: | + Number of numeral labels per object. + n_lbl_cat: | + Number of categorical labels per object. + n_cluster: | + Total number of clusters detected. +type: group +NXclustering(NXobject): + number_of_numeric_labels(NX_UINT): + unit: NX_UNITLESS + doc: | + How many numeric labels does each object have. + number_of_categorical_labels(NX_UINT): + unit: NX_UNITLESS + doc: | + How many categorical labels does each object have. + objects: + doc: | + Reference to a set of objects investigated in a cluster analysis. + Objects must have clear integer identifier. + numeric_label(NX_NUMBER): + doc: | + Reference to numeric attribute data for each object. + categorical_label: + doc: | + Reference to categorical attribute data for each object. + + # list instances of base classes of an applied cluster algorithm + # e.g. (NXclustering_hdbscan): + identifier_offset(NX_UINT): + unit: NX_UNITLESS + doc: | + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + unassigned(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of objects categorized as unassigned. + noise(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of objects categorized as noise. + number_of_cluster(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of clusters (excluding noise and unassigned). + size(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Number of objects associated to each cluster. The labels are implicit, + meaning the zeroth/first entry in the array belongs to the first cluster, + the second entry to the second cluster and so on and so forth. + The first cluster has the value of identifier_offset as its identifier. + The second cluster has identifier_offset + 1, and so on and so forth. + dimensions: + rank: 1 + dim: [[1, n_cluster]] + + # should we handle, and if so how fuzzy assignments or similarly probability + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# bbc782a9d72772178ebeebf1b4e9e199de33a4e111361efeba48cb4b169e051c +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of numeral labels per object. +# +# +# +# +# Number of categorical labels per object. +# +# +# +# +# Total number of clusters detected. +# +# +# +# +# Metadata to the results of a clustering analysis. +# +# Clustering algorithms are routine tools to segment a set of objects/primitives +# into groups, objects of different type. A plethora of algorithms have been +# proposed for geometric primitives as objects, such as points, triangles, +# or (abstract) objects. +# +# This base class considers metadata and results of one clustering +# applied to a set in which objects are either categorized as noise +# or belonging to a cluster, specifically here only one cluster. +# +# +# +# How many numeric labels does each object have. +# +# +# +# +# How many categorical labels does each object have. +# +# +# +# +# Reference to a set of objects investigated in a cluster analysis. +# Objects must have clear integer identifier. +# +# +# +# +# Reference to numeric attribute data for each object. +# +# +# +# +# Reference to categorical attribute data for each object. +# +# +# +# +# +# Which identifier is the first to be used to label a cluster. +# +# The value should be chosen in such a way that special values can be resolved: +# * identifier_offset-1 indicates an object belongs to no cluster. +# * identifier_offset-2 indicates an object belongs to the noise category. +# Setting for instance identifier_offset to 1 recovers the commonly used +# case that objects of the noise category get values to -1 and unassigned points to 0. +# +# +# +# +# Total number of objects categorized as unassigned. +# +# +# +# +# Total number of objects categorized as noise. +# +# +# +# +# Total number of clusters (excluding noise and unassigned). +# +# +# +# +# Number of objects associated to each cluster. The labels are implicit, +# meaning the zeroth/first entry in the array belongs to the first cluster, +# the second entry to the second cluster and so on and so forth. +# The first cluster has the value of identifier_offset as its identifier. +# The second cluster has identifier_offset + 1, and so on and so forth. +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXcollectioncolumn.yaml b/contributed_definitions/nyaml/NXcollectioncolumn.yaml new file mode 100644 index 0000000000..5f5788bd11 --- /dev/null +++ b/contributed_definitions/nyaml/NXcollectioncolumn.yaml @@ -0,0 +1,195 @@ +category: base +doc: | + Subclass of NXelectronanalyser to describe the electron collection + column of a photoelectron analyser. +type: group +NXcollectioncolumn(NXobject): + scheme(NX_CHAR): + doc: | + Scheme of the electron collection lens, i.e. standard, deflector, PEEM, momentum + microscope, etc. + extractor_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Voltage applied to the extractor lens + extractor_current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Current necessary to keep the extractor lens at a set voltage. Variations + indicate leakage, field emission or arc currents to the extractor lens. + working_distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Distance between sample and detector entrance + lens_mode(NX_CHAR): + doc: | + Labelling of the lens setting in use. + projection(NX_CHAR): + doc: | + The space projected in the angularly dispersive directions, real or reciprocal + enumeration: [real, reciprocal] + angular_acceptance(NX_FLOAT): + unit: NX_ANGLE + doc: + - | + Acceptance angle of the collection column. + - | + xref: + spec: ISO 18115-1:2023 + term: 7.4 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.4 + spatial_acceptance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Acceptance length or area of the collection column. + magnification(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + The magnification of the electron lens assembly. + depends_on(NX_CHAR): + doc: | + Specifies the position of the collectioncolumn by pointing to the last + transformation in the transformation chain in the NXtransformations group. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the deflector as a component in the instrument. Conventions from the + NXtransformations base class are used. In principle, the McStas coordinate + system is used. The first transformation has to point either to another + component of the system or . (for pointing to the reference frame) to relate it + relative to the experimental setup. Typically, the components of a system should + all be related relative to each other and only one component should relate to + the reference coordinate system. + (NXaperture): + doc: | + The size and position of an aperture inserted in the column, e.g. field aperture + or contrast aperture + (NXdeflector): + doc: | + Deflectors in the collection column section + (NXlens_em): + doc: | + Individual lenses in the collection column section + (NXfabrication): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# dadb7b6ffb1466761253f335bf00a73741580668da2e77983b4702847426d506 +# +# +# +# +# +# Subclass of NXelectronanalyser to describe the electron collection +# column of a photoelectron analyser. +# +# +# +# Scheme of the electron collection lens, i.e. standard, deflector, PEEM, momentum +# microscope, etc. +# +# +# +# +# Voltage applied to the extractor lens +# +# +# +# +# Current necessary to keep the extractor lens at a set voltage. Variations +# indicate leakage, field emission or arc currents to the extractor lens. +# +# +# +# +# Distance between sample and detector entrance +# +# +# +# +# Labelling of the lens setting in use. +# +# +# +# +# The space projected in the angularly dispersive directions, real or reciprocal +# +# +# +# +# +# +# +# +# Acceptance angle of the collection column. +# +# This concept is related to term `7.4`_ of the ISO 18115-1:2023 standard. +# +# .. _7.4: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.4 +# +# +# +# +# Acceptance length or area of the collection column. +# +# +# +# +# The magnification of the electron lens assembly. +# +# +# +# +# Specifies the position of the collectioncolumn by pointing to the last +# transformation in the transformation chain in the NXtransformations group. +# +# +# +# +# Collection of axis-based translations and rotations to describe the location and +# geometry of the deflector as a component in the instrument. Conventions from the +# NXtransformations base class are used. In principle, the McStas coordinate +# system is used. The first transformation has to point either to another +# component of the system or . (for pointing to the reference frame) to relate it +# relative to the experimental setup. Typically, the components of a system should +# all be related relative to each other and only one component should relate to +# the reference coordinate system. +# +# +# +# +# The size and position of an aperture inserted in the column, e.g. field aperture +# or contrast aperture +# +# +# +# +# Deflectors in the collection column section +# +# +# +# +# Individual lenses in the collection column section +# +# +# +# diff --git a/contributed_definitions/nyaml/NXcomponent_em.yaml b/contributed_definitions/nyaml/NXcomponent_em.yaml new file mode 100644 index 0000000000..78870cc26b --- /dev/null +++ b/contributed_definitions/nyaml/NXcomponent_em.yaml @@ -0,0 +1,39 @@ +category: base +doc: | + Base class for components used in an electron microscope. + + The electron microscope can be a real one or a simulated microscope. + The key motivation behind this generalization is the observation that in all + cases a controlled electron beam is generated in reality or that beam is simulated + and this beam is then used or modified in a controlled manner for the purpose + of studying physical interaction mechanisms of the beam with matter. + Here it does not matter whether one considers a real specimen or a simulated one. + + Using a common description for the real experiment in the lab and - what is + typically a simplification of it - via a computer simulation, has the benefit + that many pieces of information can be stored in the same way. In effect, + users are guided with finding information and unnecessary descriptive + variety for what are exactly the same concept is avoided to work towards + more interoperability. + + Another motivation to make no fundamental distinction between a scanning and + a transmission electron microscope is that both are electron microscopes whose + components are often very similar. +# `point Electronic GmbH `_ +type: group +NXcomponent_em(NXobject): + name(NX_CHAR): + doc: | + Given name to the component e.g stage, lens C1, etc. + description(NX_CHAR): # NXidentifier + doc: | + Ideally, a (globally) unique persistent identifier, link, or text to a + resource which gives further details to this component. + If such resource does not exist, a free-text field to report + further details about the component is possible. + (NXfabrication): + (NXprogram): + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. diff --git a/contributed_definitions/nyaml/NXcontainer.yaml b/contributed_definitions/nyaml/NXcontainer.yaml new file mode 100644 index 0000000000..2bfbdf7f58 --- /dev/null +++ b/contributed_definitions/nyaml/NXcontainer.yaml @@ -0,0 +1,294 @@ +category: base +doc: | + State of a container holding the sample under investigation. + + A container is any object in the beam path which absorbs the beam and + whose contribution to the overall attenuation/scattering needs to be + determined to process the experimental data. Examples of containers + include glass capillary tubes, vanadium cans, windows in furnaces or + diamonds in a Diamond Anvil Cell. The following figures show a complex + example of a container: + + .. figure:: container/ComplexExampleContainer.png + + A hypothetical capillary furnace. The beam passes from left to right + (blue dashes), passing through window 1, then window 2, before + passing through the downstream wall of the capillary. It is then + scattered by the sample with scattered beams passing through the + upstream wall of the capillary, then windows 4 and 5. As part of the + corrections for a PDF experiment it is necessary to subtract the PDF + of the empty container (i.e. each of the windows and the capillary). + To calculate the PDF of the empty container it is necessary to have + the measured scattering data and to know the nature (e.g. density, + elemental composition, etc.) of the portion of the container which + the beam passed through. + + .. figure:: container/ComplexContainerBeampath.png + + A complete description of the shapes of the container elements with + their orientation relative to the beam and also information on + whether they are upstream or downstream of the sample is also + therefore important. For example, although the windows 2 and 4 have + the same shape, the path taken through them by the beam is very + different and this needs to be modelled. Furthermore, it is not + inconceivable that windows might move during an experiment and thus + the changes to the beampath would need to be accounted for. + + This class encodes the position of the container with respect to the + sample and allows the calculation of the beampath through the container. + It also includes sufficient data to model beam absorption of the + container and a link to a dataset containing a measurement of the + container with nothing inside, to allow data corrections (at a specific + beam energy/measurement time) to be made. +type: group +NXcontainer(NXobject): + name: + doc: | + Descriptive name of container. + description: + doc: | + Verbose description of container and how it fits into the wider + experimental set up. + chemical_formula: + doc: | + Chemical composition of the material the container is made from. + 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. + density(NX_FLOAT): + unit: NX_MASS_DENSITY + doc: | + Density of the material the container is made from. + dimensions: + rank: 1 + dim: [[1, n_comp]] + packing_fraction(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Fraction of the volume of the container occupied by the material + forming the container. + dimensions: + dim: [[1, n_comp]] + relative_molecular_mass(NX_FLOAT): + unit: NX_MASS + doc: | + Relative molecular mass of container. + dimensions: + rank: 1 + dim: [[1, n_comp]] + beam(NXbeam): + doc: | + Details of beam incident on container, including the position + relative to the sample (to determine whether the container is + upstream or downstream of the sample). + shape(NXshape): + doc: | + Shape of the container. In combination with orientation this + should allow the beampath through the container to be modelled to + allow the adsorption to be calculated. + orientation(NXtransformations): + doc: | + The angle the container makes to the beam and how it may change + during the experiment.In combination with shape this should allow + the beampath through the container to be modelled to allow the + adsorption of the container to be calculated. + reference_measurement(link): + target: /NXentry + doc: | + A link to a full data collection which contains the actual + measured data for this container within the experimental set up + (with no sample or inner container(s)). This data set will also + include the wavelength/energy, measurement time and intensity for + which these data are valid. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# fbb634b42fbf75d55158a96329119a770f9ff716d2e3ec127b28b192c5fe872a +# +# +# +# +# +# +# State of a container holding the sample under investigation. +# +# A container is any object in the beam path which absorbs the beam and +# whose contribution to the overall attenuation/scattering needs to be +# determined to process the experimental data. Examples of containers +# include glass capillary tubes, vanadium cans, windows in furnaces or +# diamonds in a Diamond Anvil Cell. The following figures show a complex +# example of a container: +# +# .. figure:: container/ComplexExampleContainer.png +# +# A hypothetical capillary furnace. The beam passes from left to right +# (blue dashes), passing through window 1, then window 2, before +# passing through the downstream wall of the capillary. It is then +# scattered by the sample with scattered beams passing through the +# upstream wall of the capillary, then windows 4 and 5. As part of the +# corrections for a PDF experiment it is necessary to subtract the PDF +# of the empty container (i.e. each of the windows and the capillary). +# To calculate the PDF of the empty container it is necessary to have +# the measured scattering data and to know the nature (e.g. density, +# elemental composition, etc.) of the portion of the container which +# the beam passed through. +# +# .. figure:: container/ComplexContainerBeampath.png +# +# A complete description of the shapes of the container elements with +# their orientation relative to the beam and also information on +# whether they are upstream or downstream of the sample is also +# therefore important. For example, although the windows 2 and 4 have +# the same shape, the path taken through them by the beam is very +# different and this needs to be modelled. Furthermore, it is not +# inconceivable that windows might move during an experiment and thus +# the changes to the beampath would need to be accounted for. +# +# This class encodes the position of the container with respect to the +# sample and allows the calculation of the beampath through the container. +# It also includes sufficient data to model beam absorption of the +# container and a link to a dataset containing a measurement of the +# container with nothing inside, to allow data corrections (at a specific +# beam energy/measurement time) to be made. +# +# +# +# Descriptive name of container. +# +# +# +# +# Verbose description of container and how it fits into the wider +# experimental set up. +# +# +# +# +# Chemical composition of the material the container is made from. +# 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. +# +# +# +# +# Density of the material the container is made from. +# +# +# +# +# +# +# +# Fraction of the volume of the container occupied by the material +# forming the container. +# +# +# +# +# +# +# Relative molecular mass of container. +# +# +# +# +# +# +# Details of beam incident on container, including the position +# relative to the sample (to determine whether the container is +# upstream or downstream of the sample). +# +# +# +# +# Shape of the container. In combination with orientation this +# should allow the beampath through the container to be modelled to +# allow the adsorption to be calculated. +# +# +# +# +# The angle the container makes to the beam and how it may change +# during the experiment.In combination with shape this should allow +# the beampath through the container to be modelled to allow the +# adsorption of the container to be calculated. +# +# +# +# +# A link to a full data collection which contains the actual +# measured data for this container within the experimental set up +# (with no sample or inner container(s)). This data set will also +# include the wavelength/energy, measurement time and intensity for +# which these data are valid. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXcoordinate_system.yaml b/contributed_definitions/nyaml/NXcoordinate_system.yaml new file mode 100644 index 0000000000..b219399001 --- /dev/null +++ b/contributed_definitions/nyaml/NXcoordinate_system.yaml @@ -0,0 +1,86 @@ +category: base +doc: | + Base class to detail a coordinate system (CS). + + Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as + a member in an :ref:`NXcoordinate_system_set` and the name of the instance + should be this alias. This may support a process whereby jargon when talking + about coordinate systems and conventions may become cleaner for users + because it is not evident for people outside a lab that terms like e.g. + tip space or specimen space refer to the same coordinate system. + This is an example of jargon used in e.g. the field of atom + probe tomography. +type: group +NXcoordinate_system(NXobject): + origin(NX_CHAR): + doc: | + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door-handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. + # implementing a proposal for "a common base table" along thoughts like: + # https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#nxtransformations + # similar to a place where all transformations are stored + # https://www.zenodo.org/record/3526738/files/lyso009a_0087.JF07T32V01_master.h5?download=1 + alias(NX_CHAR): + doc: | + An alternative name given to that coordinate system. + type(NX_CHAR): + doc: | + Coordinate system type. + enumeration: [cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + x_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the x-axis. + x_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. + x(NX_NUMBER): + doc: | + Base unit vector along the first axis which spans the coordinate system. + This axis is frequently referred to as the x-axis in real space and + the i-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) + y_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the y-axis. + y_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + y(NX_NUMBER): + doc: | + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) + z_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the z-axis. + z_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + z(NX_NUMBER): + doc: | + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) diff --git a/contributed_definitions/nyaml/NXcoordinate_system_set.yaml b/contributed_definitions/nyaml/NXcoordinate_system_set.yaml new file mode 100644 index 0000000000..c0b922c928 --- /dev/null +++ b/contributed_definitions/nyaml/NXcoordinate_system_set.yaml @@ -0,0 +1,98 @@ +category: base +doc: | + Base class to hold different coordinate systems and representation conversions. + + How many nodes of type :ref:`NXcoordinate_system_set` should be used in an appdef? + + * 0; if no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across + the appdef an instance of NXcoordinate_system is defined, + the default NeXus `McStas `_ + coordinate system is assumed. This makes :ref:`NXcoordinate_system_set` and + NXcoordinate_system base classes backwards compatible to older + NeXus conventions and classes. + * 1; if only one :ref:`NXcoordinate_system_set` is defined, it should be placed + as high up in the node hierarchy (ideally right below an instance of NXentry) + of the application definition tree as possible. + This :ref:`NXcoordinate_system_set` should at least define one NXcoordinate_system + instance which should be called mcstas for the sake of improved clarity. + Alternatively, at least one NXcoordinate_system member of the set should be + defined and named such that it is clear how this coordinate system is + typically referred to in a community. Additional NXcoordinate_system instances + should be specified if possible in that same :ref:`NXcoordinate_system_set` instead + of cluttering them across the tree. + + If this is the case, it is assumed that the NXcoordinate_system_members + overwrite the NeXus default McStas coordinate system, i.e. users can thereby + conveniently and explicitly specify the coordinate system(s) that + they wish to use. + + Users are encouraged to write also explicit and clean depends_on fields in + all groups that encode information about where the interpretation of coordinate + systems is relevant. If these depends_on hints are not provided, it is + automatically assumed that all children (to arbitrary depth) + of that branch and sub-branches below the one in which that + :ref:`NXcoordinate_system_set` is defined use either the only NXcoordinate_system_set + instance in that set or the application definition is considered + underconstrained which should at all costs be avoided and in which case + again McStas is assumed. + * 2 and more; as soon as more than one :ref:`NXcoordinate_system_set` is specified + somewhere in the tree, different interpretations are possible as to which + of these coordinate system sets and instances apply or take preference. + We realize that such ambiguities should at all costs be avoided. + However, the opportunity for multiple sets and their instances enables to + have branch-specific coordinate system conventions which could especially + be useful for deep classes where multiple scientific methods are combined or + cases where having a definition of global translation and conversion tables + how to convert between representations in different coordinate systems + is not desired or available for now. + We argue that having 2 or more :ref:`NXcoordinate_system_set` instances and respective + NXcoordinate_system instances makes the interpretation eventually unnecessary + complicated. Instead, developers of application definitions should always try + to work for clarity and thus use only one top-level coordinate system set. + + For these reasons we conclude that the option with one top-level + :ref:`NXcoordinate_system_set` instance is the preferred choice. + + McStas is used if neither an instance of :ref:`NXcoordinate_system_set` nor an instance + of NXcoordinate_system is specified. However, even in this case it is better + to be explicit like for every other coordinate system definition to support + users with interpreting the content and logic behind every instance of the tree. + + How to store coordinate systems inside :ref:`NXcoordinate_system_set`? + Individual coordinate systems should be specified as members of the + :ref:`NXcoordinate_system_set` instance using instances of NXcoordinate_system. + + How many individual instances of NXcoordinate_system to allow within one + instance of :ref:`NXcoordinate_system_set`? + + * 0; This case should be avoided for the sake of clarity but this case could + mean the authors of the definition meant that McStas is used. We conclude, + McStas is used in this case. + * 1; Like above-mentioned this case has the advantage that it is explicit + and faces no ambiguities. However, in reality typically multiple + coordinate systems have to be mastered especially for complex + multi-signal modality experiments. + * 2 or more; If this case is realized, the best practice is that in every + case where a coordinate system should be referred to the respective class + has a depends_on field which resolves the possible ambiguities which specific + coordinate systems is referred to. The benefit of this explicit and clear + specifying of the coordinate system used in every case is that especially + in combination with having coordinate systems inside deeper branches + makes up for a very versatile, backwards compatible, but powerful system + to express different types of coordinate systems using NeXus. + + In effect, 1 should be the preferred choice. However, if more than one coordinate + system is defined for practical purposes, explicit depends_on fields should + always guide the user for each group and field which of the coordinate system + one refers to. +type: group +NXcoordinate_system_set(NXobject): + (NXcoordinate_system): +# How to interpret "depends_on" calls for NXtransformations instances which live +# within an instance of NXcoordinate_system(_set)? +# Depends on cardinality of NXcoordinate_system_set, i.e. how many NXcoordinate_system are defined? +# - 0, the root of an NXtransformation chain i.e. "." means McStas +# - 1, the root of an NXtransformation chain i.e. "." means "that specific CS" i.e. the one defined by the single instance of NXcoordinate_system in the set +# - > 1, "." becomes ambiguous. My suggestion, spell out the name of the specific NXcoordinate_system instance to be used, using "." +# despite all these, a warning should be raised, like a logic warning (and McStas kick in) or an error (i.e. be forbidden) be raised + diff --git a/contributed_definitions/nyaml/NXcorrector_cs.yaml b/contributed_definitions/nyaml/NXcorrector_cs.yaml new file mode 100644 index 0000000000..bbe1b033af --- /dev/null +++ b/contributed_definitions/nyaml/NXcorrector_cs.yaml @@ -0,0 +1,68 @@ +category: base +doc: | + Corrector for aberrations in an electron microscope. + + Different technology partners use different naming schemes and + models for quantifying the aberration coefficients. + + The corrector in an electron microscope is composed of multiple lenses + and multipole stigmators with details specific for the technology partner + and microscope. Many of their technical details is proprietary knowledge. +type: group +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_img: | + Number of images taken, at least one. +NXcorrector_cs(NXcomponent_em): + applied(NX_BOOLEAN): + doc: | + Was the corrector used? + # NEW ISSUE: clarify the mathematical details behind the + ZEMLIN_TABLEAU(NXprocess): + doc: | + Specific information about the concrete alignment procedure which is a + process during which the corrector is configured to enable a calibrated + usage of the instrument. + + This :ref:`NXprocess` group should also be used when one describes in a computer + simulation the specific details about the modelled or assumed aberration + corrections. In effect, this base class can also be used for harmonizing + the description of such simulation details across different computer codes + to enable that a research data management system can find these information + in a common place - formatted in a normalized representation. + This reduces the necessity to include substantial case-dependent verification + code in the research data management system. + description(NX_CHAR): + doc: | + Discouraged free-text field to add further details about + the alignment procedure. + tilt_angle(NX_NUMBER): + doc: | + The outer tilt angle of the beam in tableau acquisition. + + TODO: The relevant axes which span the tilt_angle need a + cleaner description. + unit: NX_ANGLE + dim: (n_img,) + exposure_time(NX_NUMBER): + doc: | + The exposure time of single tilt images. + unit: NX_TIME + dim: (n_img,) + magnification(NX_NUMBER): + doc: | + The factor of enlargement of the apparent size, + not the physical size, of an object. + unit: NX_DIMENSIONLESS + dim: (n_img,) + (NXimage_set): + doc: | + The images taken during the alignment procedure. + (NXprocess): + doc: | + Place for storing measured or estimated aberrations (for each image or final). + ceos(NXaberration_model_ceos): + nion(NXaberration_model_nion): + # technical components of the corrector + (NXlens_em): diff --git a/contributed_definitions/nyaml/NXcrystal_structure.yaml b/contributed_definitions/nyaml/NXcrystal_structure.yaml new file mode 100644 index 0000000000..796ac83d3c --- /dev/null +++ b/contributed_definitions/nyaml/NXcrystal_structure.yaml @@ -0,0 +1,178 @@ +category: base +doc: | + Base class to describe the atomic crystal structure of a phase. + + This base class contains key metadata that are relevant parameter to every + physics-based model to simulate radiation matter interaction. + + Examples where such base class is useful are kinematic or dynamic + diffraction simulations of e.g. (Kikuchi or other type of) patterns. +# The actual indexing of Kikuchi patterns may use different algorithms. +# Such are used within different workflows where simulated and measured +# Kikuchi pattern are compared to rate which phase and orientation is the most +# likely candidate describing the pattern measured at that each scan point +# respectively. If this evaluation yields scan points without any solutions, +# these are represented using the null-phase model phase0, aka n/a aka notIndexed. +# Traditionally, Hough transformation-based indexing has been the most frequently +# used algorithm. Dictionary-based alternatives are emerging. +symbols: + n_hkl: | + Number of reflectors (Miller crystallographic plane triplets). + n_pos: | + Number of atom positions. + d: | + Dimensionality of the lattice. +type: group +NXcrystal_structure(NXobject): + \@depends_on(NX_CHAR): + doc: | + Detail in which reference frame the unit cell is defined. + dimensionality(NX_POSINT): + doc: | + Dimensionality of the lattice. + enumeration: [1, 2, 3] + reference(NXidentifier): + doc: | + Reference to another resource that was used for + instantiating this structure model. + a_b_c(NX_NUMBER): + doc: | + Crystallography unit cell parameters a, b, and c. + unit: NX_LENGTH + dim: (d,) + # defined using which convention? + alpha_beta_gamma(NX_NUMBER): + doc: | + Crystallography unit cell parameters alpha, beta, and gamma. + unit: NX_ANGLE + dim: (d,) + area(NX_NUMBER): + doc: | + Area of the unit cell considering that d = 2. + unit: NX_AREA + volume(NX_NUMBER): + doc: | + Volume of the unit cell considering that d = 3. + unit: NX_VOLUME + crystal_system(NX_CHAR): + doc: | + Crystal system + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + # 2d + laue_group(NX_CHAR): + doc: | + Laue group using International Table of Crystallography Notation. + # add enumeration of all possible + point_group(NX_CHAR): + doc: | + Point group using International Table of Crystallography Notation. + # add enumeration all possible + # 3d + space_group(NX_CHAR): + doc: | + Space group from the International Table of Crystallography Notation. + # add enumeration of all possible + is_centrosymmetric(NX_BOOLEAN): + doc: | + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + is_chiral(NX_BOOLEAN): + doc: | + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + phase_identifier(NX_INT): + doc: | + Identifier for each phase. + + The value 0 is reserved for the unknown phase that represents the + null-model no sufficiently significant confirmation. In other words, + the phase_name is n/a, notIndexed. + + The phase identifier value has to match with the integer postfix of the + group name which represents that instance in a NeXus/HDF5 file, i.e. + if two phases were used e.g. 0 and 1, two instances of an + :ref:`NXcrystal_structure` named phase0 and phase1 + should be stored in the HDF5 file. + unit: NX_UNITLESS + # \@depends_on(NX_CHAR): + # doc: | + # Refers to the specific identifier_offset to consider. + # + # If not provided assume identifier_offset is 0. + phase_name(NX_CHAR): + doc: | + Name of the phase/alias. + + If the phase_identifier is 0 and one would like to use the field + phase_name the value should be n/a. + atom_identifier(NX_CHAR): + doc: | + Label for each atom position. + dim: (n_pos,) + atom_type(NX_UINT): + doc: | + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) `_ + unit: NX_UNITLESS + dim: (n_pos,) + # atom_position(NXcg_point_set): + atom_position(NX_NUMBER): + doc: | + Atom positions. + dim: (n_pos, d) + unit: NX_ANY + \@depends_on(NX_CHAR): + doc: | + Reference to an instance of :ref:`NXcoordinate_system` + whereby the positions can be resolved. + # in addition we need to have a physical model e.g. kinematic or dynamical e-diffraction theory + # to describe the simulated Kikuchi pattern generated from such a model + atom_occupancy(NX_NUMBER): + doc: | + Relative occupancy of the atom position. + unit: NX_DIMENSIONLESS + dim: (n_pos,) + number_of_planes(NX_UINT): + doc: | + How many reflectors are distinguished. + + Value has to match value for symbol n_hkl. + unit: NX_UNITLESS + # Miller indices :math:`(hkl)[uvw]`. + miller(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Miller indices :math:`(hkl)[uvw]` of the planes. + + The first triplet specify :math:`(hkl)` the second triplet :math:`[uvw]`. + Miller indices refer to the Cartesian right-handed coordinate system + of the unit cell. + dim: (n_hkl, 6) + dspacing(NX_NUMBER): + doc: | + Spacing between crystallographic planes as defined by field miller. + unit: NX_LENGTH + dim: (n_hkl,) + relative_intensity(NX_NUMBER): + doc: | + Relative intensity of the signal for the plane. + unit: NX_DIMENSIONLESS + dim: (n_hkl,) + number_of_scan_points(NX_UINT): + doc: | + In case the :ref:`NXcrystal_structure` base class is used + with analyzed orientation maps this field stores how many scan points + of the map were identified as that phase. + unit: NX_UNITLESS + ipfID(NXms_ipf): + pfID(NXms_pf): + odfID(NXms_odf): +# here the theoreticians expert (Marc deGraeff, Aimo Winkelmann, Peter Rez) +# can give some good suggestions on how to improve and ideally make even +# more general this section diff --git a/contributed_definitions/nyaml/NXcs_computer.yaml b/contributed_definitions/nyaml/NXcs_computer.yaml new file mode 100644 index 0000000000..01cf37da32 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_computer.yaml @@ -0,0 +1,39 @@ +category: base +doc: | + Computer science description of a set of computing nodes. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_computer(NXobject): + name(NX_CHAR): + doc: | + Given name/alias to the computing system, e.g. MyDesktop. + operating_system(NX_CHAR): + doc: | + Name of the operating system, e.g. Windows, Linux, Mac, Android. + \@version: + doc: | + Version plus build number, commit hash, or description of an ever + persistent resource where the source code of the program and build + instructions can be found so that the program can be configured in + such a manner that the result file is ideally recreatable yielding + the same results. + # difference e.g. in Win11 between hardware ID, UUID, and device ID + uuid(NX_CHAR): + doc: | + Ideally a (globally) unique persistent identifier of the computer, i.e. + the Universally Unique Identifier (UUID) of the computing node. + # when it comes to performance monitoring + (NXcs_cpu_sys): + doc: | + Details about (classical) processing units (CPUs) or a system thereof. + (NXcs_gpu_sys): + doc: | + Details about coprocessor/graphic cards/accelerator units or a system thereof. + (NXcs_mm_sys): + doc: | + Details about the memory sub-system. + (NXcs_io_sys): + doc: | + Details about the I/O sub-system. diff --git a/contributed_definitions/nyaml/NXcs_cpu.yaml b/contributed_definitions/nyaml/NXcs_cpu.yaml new file mode 100644 index 0000000000..2160aa3dd4 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_cpu.yaml @@ -0,0 +1,54 @@ +category: base +doc: | + Computer science description of a central processing unit (CPU) of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_cpu(NXobject): + name: + doc: | + Given name of the CPU. Users should be as specific as possible. + (NXfabrication): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7acc57d7e709c31f39bfe27c48566ae19f040f70c491c764259dab65ee1a36b2 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Computer science description of a central processing unit (CPU) of a computer. +# +# +# +# Given name of the CPU. Users should be as specific as possible. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXcs_cpu_obj.yaml b/contributed_definitions/nyaml/NXcs_cpu_obj.yaml new file mode 100644 index 0000000000..73097d5ca5 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_cpu_obj.yaml @@ -0,0 +1,12 @@ +category: base +doc: | + Computer science description of a (central) processing unit (C)PU of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_cpu_obj(NXobject): + name(NX_CHAR): + doc: | + Given name of the CPU. Users should be as specific as possible. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_cpu_sys.yaml b/contributed_definitions/nyaml/NXcs_cpu_sys.yaml new file mode 100644 index 0000000000..5eaf8f0eab --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_cpu_sys.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Computer science description of a system of classical central processing units. + + For coprocessor or graphic cards use :ref:`NXcs_gpu_sys` instead. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_cpu_sys(NXobject): + cpuID(NXcs_cpu_obj): + doc: | + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single CPU one + could describe using one instance of :ref:`NXcs_cpu_obj` inside one instance of + :ref:`NXcs_cpu_sys`. + A dual-socket server one could describe using two instances of :ref:`NXcs_cpu_obj` + inside one instance of :ref:`NXcs_cpu_sys`. + A server with two dual-socket server nodes one could describe + with the above group of one :ref:`NXcs_cpu_sys` into another :ref:`NXcs_cpu_sys`. diff --git a/contributed_definitions/nyaml/NXcs_filter_boolean_mask.yaml b/contributed_definitions/nyaml/NXcs_filter_boolean_mask.yaml new file mode 100644 index 0000000000..f6ed55a5a4 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_filter_boolean_mask.yaml @@ -0,0 +1,70 @@ +category: base +doc: | + Computer science base class for packing and unpacking booleans. + + This base class bookkeeps metadata to inform software about necessary modulo + operations to decode e.g. set membership of objects in sets which are encoded + as a packed array of boolean values. + + One use case is processing of object sets (point cloud data). When one applies + e.g. a spatial filter to a set of points to define which points are analyzed + and which not, one can store this information in a compact manner using an array + of boolean values. If the value is True the point is taken, otherwise the point + is not taken. + + The resulting boolean array will be filled with True and False in a manner + that is often arbitrary and in general case-dependent. + + Especially when the number of points is large, for instance several thousands + or more, some situations can be more efficiently stored if one would not store + the boolean array but just list the identifiers of the points taken. + + For example, if within a set of 1000 points only one point is taken, it would + take (naively) 4000 bits to store the array but only 32 bits to store e.g. the + ID of the single point that is taken. Of course the 4000 bit field is so + sparse that it could be compressed resulting also in a substantial reduction + of the storage demands. Therefore, boolean masks are useful in that + they store compact representation of set memberships. + + The number of encoded pieces of information is not necessarily + an integer multiple of the bit depth. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_objs: | + Number of entries (e.g. number of points or objects). + bitdepth: | + Number of bits assumed for the container datatype used. + n_total: | + Length of mask considering the eventual need for padding. +type: group +NXcs_filter_boolean_mask(NXobject): + \@depends_on(NX_CHAR): + doc: | + Possibility to refer to which set this mask applies. + + If depends_on is not provided, it is assumed that the mask + applies to its direct parent. + number_of_objects(NX_INT): + doc: | + Number of objects represented by the mask. + unit: NX_UNITLESS + bitdepth(NX_INT): + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + unit: NX_UNITLESS + mask(NX_UINT): + doc: | + The content of the mask. If padding is used, padding bits have to be set to 0. + dim: (n_total,) + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Link to/or array of identifiers for the objects. The decoded mask is + interpreted consecutively, i.e. the first bit in the mask matches + to the first identifier, the second bit in the mask to the second + identifier and so on and so forth. Resolving of identifier follows + the conventions made for depends_on, so consult the also its description. + unit: NX_UNITLESS + dim: (n_object,) diff --git a/contributed_definitions/nyaml/NXcs_gpu.yaml b/contributed_definitions/nyaml/NXcs_gpu.yaml new file mode 100644 index 0000000000..573f14f29c --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_gpu.yaml @@ -0,0 +1,54 @@ +category: base +doc: | + Computer science description of a graphic processing unit (GPU) of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_gpu(NXobject): + name: + doc: | + Given name of the GPU. Users should be as specific as possible. + (NXfabrication): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 739989c53a5e4fe43a63035920aab39528e8933c2ec9e35465e04e40d69d9a7c +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Computer science description of a graphic processing unit (GPU) of a computer. +# +# +# +# Given name of the GPU. Users should be as specific as possible. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXcs_gpu_obj.yaml b/contributed_definitions/nyaml/NXcs_gpu_obj.yaml new file mode 100644 index 0000000000..04468b7b2b --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_gpu_obj.yaml @@ -0,0 +1,12 @@ +category: base +doc: | + Computer science description of a graphic processing unit (GPU) of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_gpu_obj(NXobject): # NXcircuit_board ? + name(NX_CHAR): + doc: | + Given name of the GPU. Users should be as specific as possible. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_gpu_sys.yaml b/contributed_definitions/nyaml/NXcs_gpu_sys.yaml new file mode 100644 index 0000000000..dee199330c --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_gpu_sys.yaml @@ -0,0 +1,20 @@ +category: base +doc: | + Computer science description of a system of coprocessor or graphics processors. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_gpu_sys(NXobject): + gpuID(NXcs_gpu_obj): + doc: | + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single GPU one + could describe using one instance of :ref:`NXcs_gpu_obj` inside one instance of + :ref:`NXcs_gpu_sys`. + A desktop computer with two GPUs one could describe using two instances + of :ref:`NXcs_gpu_obj` inside one instance of :ref:`NXcs_gpu_sys`. + A GPU server like nowadays used for artificial intelligence + one could describe as a system with n instances of :ref:`NXcs_gpu_obj` + in one :ref:`NXcs_gpu_sys` or :ref:`NXcs_cpu_sys`. diff --git a/contributed_definitions/nyaml/NXcs_io_obj.yaml b/contributed_definitions/nyaml/NXcs_io_obj.yaml new file mode 100644 index 0000000000..100f0cae41 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_io_obj.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Computer science description of a storage object in an input/output system. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_io_obj(NXobject): + technology(NX_CHAR): + doc: | + Qualifier for the type of storage medium used. + enumeration: [solid_state_disk, hard_disk, tape] + max_physical_capacity(NX_NUMBER): + doc: | + Total amount of data which the medium can hold. + unit: NX_ANY + # NX_BIT + name(NX_CHAR): + doc: | + Given name to the I/O unit. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_io_sys.yaml b/contributed_definitions/nyaml/NXcs_io_sys.yaml new file mode 100644 index 0000000000..b62768a234 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_io_sys.yaml @@ -0,0 +1,13 @@ +category: base +doc: | + Computer science description of system of a computer. + + In the same way how a hierarchy of instances of :ref:`NXcs_cpu_obj` or :ref:`NXcs_gpu_obj` + can be defined one can also define a hierarchy of :ref:`NXcs_mm_obj` and :ref:`NXcs_io_obj` + instances. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_io_sys(NXobject): + ioID(NXcs_io_obj): diff --git a/contributed_definitions/nyaml/NXcs_mm_obj.yaml b/contributed_definitions/nyaml/NXcs_mm_obj.yaml new file mode 100644 index 0000000000..d1fead8c8b --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_mm_obj.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Computer science description of a memory in a memory system. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_mm_obj(NXobject): + technology(NX_CHAR): + doc: | + Qualifier for the type of random access memory. + # make an enumeration + max_physical_capacity(NX_NUMBER): + doc: | + Total amount of data which the medium can hold. + unit: NX_ANY + # NX_BIT + name(NX_CHAR): + doc: | + Given name to the I/O unit. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_mm_sys.yaml b/contributed_definitions/nyaml/NXcs_mm_sys.yaml new file mode 100644 index 0000000000..60293e362b --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_mm_sys.yaml @@ -0,0 +1,17 @@ +category: base +doc: | + Computer science description of a memory system of a computer. + + In the same way how a hierarchy of instances of :ref:`NXcs_cpu_obj` or :ref:`NXcs_gpu_obj` + can be defined one can also define a hierarchy of :ref:`NXcs_mm_obj` and :ref:`NXcs_io_obj` + instances. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_mm_sys(NXobject): + total_physical_memory(NX_NUMBER): + doc: | + How much physical memory does the system provide. + unit: NX_ANY + # NX_BIT diff --git a/contributed_definitions/nyaml/NXcs_prng.yaml b/contributed_definitions/nyaml/NXcs_prng.yaml new file mode 100644 index 0000000000..114574f691 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_prng.yaml @@ -0,0 +1,47 @@ +category: base +doc: | + Computer science description of pseudo-random number generator. + + The purpose of this base class is to identify if exactly the same sequence + can be reproduced, like for a PRNG or not (for a true physically random source). +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_prng(NXobject): + type(NX_CHAR): + doc: | + Physical approach or algorithm whereby random numbers are generated. + + Different approaches for generating random numbers with a computer exists. + Some use a dedicated physical device whose the state is unpredictable + (physically). Some use a strategy of mangling information from the system + clock. Also in this case the sequence is not reproducible without having + additional pieces of information. + + In most cases though so-called pseudo-random number generator (PRNG) + algorithms are used. These yield a deterministic sequence of practically + randomly appearing numbers. These algorithms differ in their quality in + how close the resulting sequences are random, i.e. sequentially + uncorrelated. Nowadays one of the most commonly used algorithm is the + MersenneTwister (mt19937). + enumeration: [physical, system_clock, mt19937, other] + (NXprogram): + doc: | + Name of the PRNG implementation and version. If such information is not + available or if the PRNG type was set to other the DOI to the publication + or the source code should be given. + seed(NX_INT): + doc: | + Parameter of the PRNG controlling its initialization + and thus controlling the specific sequence generated. + unit: NX_UNITLESS + warmup(NX_UINT): + doc: | + Number of initial draws from the PRNG after its initialized with the seed. + These initial draws are typically discarded in an effort to equilibrate the + sequence. If no warmup was performed or if warmup procedures are unclear, + users should set the value to zero. + unit: NX_UNITLESS + # one could add spectral properties but this is usually well documented in the PRNG literature + # one could also think about making reference to the NIST PRNG test suite to qualify the PRNG diff --git a/contributed_definitions/nyaml/NXcs_profiling.yaml b/contributed_definitions/nyaml/NXcs_profiling.yaml new file mode 100644 index 0000000000..cc41151e96 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_profiling.yaml @@ -0,0 +1,109 @@ +category: base +doc: | + Computer science description for performance and profiling data of an application. + + Performance monitoring and benchmarking of software is a task where questions + can be asked at various levels of detail. In general, there are three main + contributions to performance: + + * Hardware capabilities and configuration + * Software configuration and capabilities + * Dynamic effects of the system in operation and the system working together + with eventually multiple computers, especially when these have to exchange + information across a network and these are used usually by multiple users. + + At the most basic level users may wish to document how long e.g. a data + analysis with a scientific software (app) took. + A frequent idea is here to answer practical questions like how critical is the + effect on the workflow of the scientists, i.e. is the analysis possible in + a few seconds or would it take days if I were to run this analysis on a + comparable machine? + For this more qualitative performance monitoring, mainly the order of + magnitude is relevant, as well as how this was achieved using parallelization + (i.e. reporting the number of CPU and GPU resources used, the number of + processes and threads configured, and providing basic details about the computer). + + At more advanced levels benchmarks may go as deep as detailed temporal tracking + of individual processor instructions, their relation to other instructions, the + state of call stacks; in short eventually the entire app execution history + and hardware state history. Such analyses are mainly used for performance + optimization, i.e. by software and hardware developers as well as for + tracking bugs. Specialized software exists which documents such performance + data in specifically-formatted event log files or databases. + + This base class cannot and should not replace these specific solutions for now. + Instead, the intention of the base class is to serve scientists at the + basic level to enable simple monitoring of performance data and log profiling + data of key algorithmic steps or parts of computational workflows, so that + these pieces of information can guide users which order of magnitude differences + should be expected or not. + + Developers of application definitions should add additional fields and + references to e.g. more detailed performance data to which they wish to link + the metadata in this base class. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_profiling(NXobject): + # details about queuing systems etc + current_working_directory(NX_CHAR): + doc: | + Path to the directory from which the tool was called. + command_line_call(NX_CHAR): + doc: | + Command line call with arguments if applicable. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the app was started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the app terminated or crashed. + total_elapsed_time(NX_NUMBER): + unit: NX_TIME + doc: | + Wall-clock time how long the app execution took. This may be in principle + end_time minus start_time; however usage of eventually more precise timers + may warrant to use a finer temporal discretization, + and thus demands a more precise record of the wall-clock time. + number_of_processes(NX_UINT): + doc: | + Qualifier which specifies with how many nominal processes the app was + invoked. The main idea behind this field e.g. for apps which use e.g. MPI + (Message Passing Interface) parallelization is to communicate + how many processes were used. + + For sequentially running apps number_of_processes and number_of_threads + is 1. If the app uses exclusively GPU parallelization number_of_gpus + can be larger than 1. If no GPU is used number_of_gpus is 0 even though + the hardware may have GPUs installed, thus indicating these were not + used though. + unit: NX_UNITLESS + number_of_threads(NX_UINT): + doc: | + Qualifier how many nominal threads were used at runtime. + Specifically here the maximum number of threads used for the + high-level threading library used (e.g. OMP_NUM_THREADS), posix. + unit: NX_UNITLESS + number_of_gpus(NX_UINT): + doc: | + Qualifier with how many nominal GPUs the app was invoked at runtime. + unit: NX_UNITLESS + # there are more complicated usage models, where GPUs are activated in + # between runs etc, but here application definition and base class developers + # should feel free to suggest customizations wrt to if and how such more + # complicated models should be captured. + (NXcs_computer): + doc: | + A collection with one or more computing nodes each with own resources. + This can be as simple as a laptop or the nodes of a cluster computer. + (NXcs_profiling_event): + doc: | + A collection of individual profiling event data which detail e.g. how + much time the app took for certain computational steps and/or how much + memory was consumed during these operations. + +# how to retrieve UUID for cloud computing instances +# https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/identify_ec2_instances.html diff --git a/contributed_definitions/nyaml/NXcs_profiling_event.yaml b/contributed_definitions/nyaml/NXcs_profiling_event.yaml new file mode 100644 index 0000000000..d92fbe68bb --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_profiling_event.yaml @@ -0,0 +1,54 @@ +category: base +doc: | + Computer science description of a profiling event. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_processes: | + Number of processes. +type: group +NXcs_profiling_event(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking ended. + description(NX_CHAR): + doc: | + Free-text description what was monitored/executed during the event. + elapsed_time(NX_NUMBER): + doc: | + Wall-clock time how long the event took. + + This may be in principle end_time minus start_time; however usage of + eventually more precise timers may warrant to use a finer temporal + discretization, and thus demand for a more precise record of the + wall-clock time. + + Elapsed time may contain time portions where resources were idling. + unit: NX_TIME + number_of_processes(NX_UINT): + doc: | + Number of processes used (max) during the execution of this event. + unit: NX_UNITLESS + number_of_threads(NX_UINT): + doc: | + Number of threads used (max) during the execution of this event. + unit: NX_UNITLESS + number_of_gpus(NX_UINT): + doc: | + Number of GPUs used (max) during the execution of this event. + unit: NX_UNITLESS + max_virtual_memory_snapshot(NX_NUMBER): + doc: | + Maximum amount of virtual memory allocated per process during the event. + unit: NX_ANY # NX_BIT + dim: (n_processes,) + max_resident_memory_snapshot(NX_NUMBER): + doc: | + Maximum amount of resident memory allocated per process during the event. + unit: NX_ANY # NX_BIT + dim: (n_processes,) diff --git a/contributed_definitions/nyaml/NXcsg.yaml b/contributed_definitions/nyaml/NXcsg.yaml new file mode 100644 index 0000000000..e7f408c7a2 --- /dev/null +++ b/contributed_definitions/nyaml/NXcsg.yaml @@ -0,0 +1,119 @@ +category: base +doc: | + Constructive Solid Geometry base class, using :ref:`NXquadric` and :ref:`NXoff_geometry` +type: group +NXcsg(NXobject): + operation: + doc: | + One of the standard construction solid geometry set operations, + or if the CSG is a pointer to the geometry provided by an + :ref:`NXquadric` or an :ref:`NXoff_geometry`. Takes values: + enumeration: [UNION, INTERSECTION, DIFFERENCE, COMPLEMENT, IS_QUADRIC, IS_MESH] + a(NXcsg): + exists: ['min', '0', 'max', '1'] + doc: | + The first operand of constructive solid geometry + operation. Compulsory if 'operation' is UNION, INTERSECTION, + DIFFERENCE or COMPLEMENT. + b(NXcsg): + exists: ['min', '0', 'max', '1'] + doc: | + The second operand of constructive solid geometry + operation. Compulsory if 'operation' is UNION, INTERSECTION or + DIFFERENCE. + geometry(NX_CHAR): + exists: ['min', '0', 'max', '1'] + doc: | + Path to a field that is either an :ref:`NXquadric` (if + 'operation' = IS_QUADRIC) or an :ref:`NXoff_geometry` (if + 'operation' = IS_MESH) that defines the surface making up the + constructive solid geometry component. Compulsory if 'operation' + is IS_QUADRIC or IS_MESH. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 26b9cbb33ac382f8758dc8bda210c12a550d888e5d33c1a0e662e9671d2788db +# +# +# +# +# +# Constructive Solid Geometry base class, using :ref:`NXquadric` and :ref:`NXoff_geometry` +# +# +# One of the standard construction solid geometry set operations, +# or if the CSG is a pointer to the geometry provided by an +# :ref:`NXquadric` or an :ref:`NXoff_geometry`. Takes values: +# +# +# +# +# +# +# +# +# +# +# +# +# The first operand of constructive solid geometry +# operation. Compulsory if 'operation' is UNION, INTERSECTION, +# DIFFERENCE or COMPLEMENT. +# +# +# +# +# The second operand of constructive solid geometry +# operation. Compulsory if 'operation' is UNION, INTERSECTION or +# DIFFERENCE. +# +# +# +# +# Path to a field that is either an :ref:`NXquadric` (if +# 'operation' = IS_QUADRIC) or an :ref:`NXoff_geometry` (if +# 'operation' = IS_MESH) that defines the surface making up the +# constructive solid geometry component. Compulsory if 'operation' +# is IS_QUADRIC or IS_MESH. +# +# +# diff --git a/contributed_definitions/nyaml/NXcxi_ptycho.yaml b/contributed_definitions/nyaml/NXcxi_ptycho.yaml new file mode 100644 index 0000000000..1b68b54452 --- /dev/null +++ b/contributed_definitions/nyaml/NXcxi_ptycho.yaml @@ -0,0 +1,440 @@ +category: application +doc: | + Application definition for a ptychography experiment, compatible with CXI from version 1.6. + + This is compatible with CXI from version 1.6 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 linking, + with hdf5 Virtual Dataset being used to restructure any data that needs to be remapped. To be fully CXI compatible, all units (including energy) must be in SI units. + + 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: + doc: | + 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 +type: group +NXcxi_ptycho(NXobject): + (NXentry)entry_1: + title: + exists: ['min', '0', 'max', '1'] + start_time(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + end_time(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + definition(NX_CHAR): + exists: ['min', '1', 'max', '1'] + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXcxi_ptycho] + (NXinstrument)instrument_1: + exists: ['min', '1', 'max', '1'] + (NXsource)source_1: + exists: ['min', '1', 'max', '1'] + name(NX_CHAR): + exists: ['min', '1', 'max', '1'] + energy(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + doc: | + This is the energy of the machine, not the beamline. + probe(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + type(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + (NXbeam)beam_1: + exists: ['min', '1', 'max', '1'] + energy(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + extent(NX_FLOAT): + exists: ['min', '0', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + incident_beam_divergence(NX_FLOAT): + exists: ['min', '0', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + incident_beam_energy(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + incident_energy_spread(NX_FLOAT): + exists: ['min', '1', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + (NXdetector)detector_1: + exists: ['min', '1', 'max', '1'] + \@axes: + type: NX_CHAR + doc: | + should have value "[, data]" + \@signal: + type: NX_CHAR + doc: | + should have value "data" + (NXtransformations)transformations: + vector(NX_NUMBER): + exists: ['min', '1', 'max', '1'] + translation(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1', 'max', '1'] + doc: | + This is an array of shape (npts_x*npts_y, 3) and can be a Virtual Dataset of x and y + \@units: + type: NX_CHAR + exists: optional + \@axes: + exists: optional + type: NX_CHAR + doc: | + this should take the value "translation:$slowaxisname:$fastaxisname" + \@interpretation: + exists: optional + type: NX_CHAR + doc: | + This should be "image" + data(NX_INT): + signal: 1 + exists: ['min', '1', 'max', '1'] + dimensions: + rank: 3 for arbitrary scan, 4 for raster + dim: [[1, npts_x], [2, npts_y], [3, frame_size_x], [4, frame_size_y]] + data_1(link): + target: /NXentry/NXinstrument/NXdetector/data + doc: | + 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. + x_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + y_pixel_size(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '1', 'max', '1'] + doc: | + The distance between the detector and the sample + \@units: + type: NX_CHAR + exists: optional + beam_center_x(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + beam_center_y(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + \@units: + type: NX_CHAR + exists: optional + (NXmonitor): + exists: ['min', '0', 'max', '1'] + data(NX_FLOAT): + dimensions: + rank: 1 for arbitrary scan, 2 for raster + dim: [[1, npts_x], [2, npts_y]] + (NXdata): + exists: ['min', '1', 'max', '1'] + \@axes: + type: NX_CHAR + exists: optional + doc: | + This should be "[x,.]" for arbitrary scanning patterns, and "[x,.,.]" for raster + \@signal: + type: NX_CHAR + exists: optional + doc: | + This should be "data" + data(link): + target: /NXentry/NXinstrument/NXdetector/data + x(link): + target: /NXentry/NXsample/NXtransformations/x + y(link): + target: /NXentry/NXsample/NXtransformations/y + x_indices(NX_CHAR): + y_indices(NX_CHAR): + (NXcollection)data_1: + exists: ['min', '1', 'max', '1'] + doc: | + 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(link): + target: /NXentry/NXinstrument/NXdetector/data + translation(link): + target: /NXentry/NXinstrument/NXdetector/translation + (NXsample)sample_1: + exists: ['min', '1', 'max', '1'] + name(NX_CHAR): + exists: ['min', '0', 'max', '1'] + transformations(NXtransformations): + doc: | + 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. + \@vector: + exists: optional + type: NX_NUMBER + (NXcollection)geometry_1: + exists: ['min', '1', 'max', '1'] + translation(link): + target: /NXentry/NXinstrument/NXdetector/translation + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cc83e17501fdd8eab38f6229fd41422c15a196db1698921004af9d9736c9cb83 +# +# +# +# +# +# +# These symbols will be used below to coordinate the shapes of the datasets. +# +# +# +# +# The number of points in the x direction +# +# +# +# +# +# Number of points in the y direction. +# +# +# +# +# Number of detector pixels in x +# +# +# +# +# +# Number of detector pixels in y +# +# +# +# +# +# Application definition for a ptychography experiment, compatible with CXI from version 1.6. +# +# This is compatible with CXI from version 1.6 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 linking, +# with hdf5 Virtual Dataset being used to restructure any data that needs to be remapped. To be fully CXI compatible, all units (including energy) must be in SI units. +# +# 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). +# +# +# +# +# +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# +# +# +# +# This is the energy of the machine, not the beamline. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# should have value "[, data]" +# +# +# +# +# should have value "data" +# +# +# +# +# +# +# +# This is an array of shape (npts_x*npts_y, 3) and can be a Virtual Dataset of x and y +# +# +# +# +# this should take the value "translation:$slowaxisname:$fastaxisname" +# +# +# +# +# This should be "image" +# +# +# +# +# +# +# +# +# +# +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# +# The distance between the detector and the sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should be "[x,.]" for arbitrary scanning patterns, and "[x,.,.]" for raster +# +# +# +# +# This should be "data" +# +# +# +# +# +# +# +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdac.yaml b/contributed_definitions/nyaml/NXdac.yaml new file mode 100644 index 0000000000..f0b09372b2 --- /dev/null +++ b/contributed_definitions/nyaml/NXdac.yaml @@ -0,0 +1,53 @@ +category: base +doc: | + Digital-to-analog converter component/integrated circuit. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXdac(NXobject): + value(NX_NUMBER): + unit: NX_UNITLESS + doc: | + TBD. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3126ae3b0a957ca0a5ab3d91942ccee0c849665d53ec3cf085dee4f2fc420899 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Digital-to-analog converter component/integrated circuit. +# +# +# +# TBD. +# +# +# diff --git a/contributed_definitions/nyaml/NXdata_mpes.yaml b/contributed_definitions/nyaml/NXdata_mpes.yaml new file mode 100644 index 0000000000..8a66973cd2 --- /dev/null +++ b/contributed_definitions/nyaml/NXdata_mpes.yaml @@ -0,0 +1,267 @@ +category: base +doc: | + :ref:`NXdata_mpes` describes the plottable data and related dimension scales in MPES + experiments. + + It extends the NXdata class and provides a glossary of explicitly named axis names + which are typical for MPES data. +type: group +NXdata_mpes(NXdata): + energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Calibrated energy axis. + + This could be a link to either + /entry/process/energy_calibration/calibrated_axis or + /entry/process/energy_correction/calibrated_axis. + \@type: + type: NX_CHAR + doc: | + The energy can be either stored as kinetic or as binding energy. + enumeration: + kinetic: + doc: + - | + Calibrated kinetic energy axis. + - | + xref: + spec: ISO 18115-1:2023 + term: 3.35 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + binding: + doc: + - | + Calibrated binding energy axis. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.16 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + \@energy_indices: + \@energy_depends: + kx(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + Calibrated x axis in k-space. + Units are 1/Angström. + \@kx_indices: + \@kx_depends: + ky(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + Calibrated y axis in k-space. + Units are 1/Angström + \@ky_indices: + \@ky_depends: + kz(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + Calibrated z axis in k-space. + Units are 1/Angström. + \@kz_indices: + \@kz_depends: + angular0(NX_NUMBER): + unit: NX_ANGLE + doc: | + Fast-axis angular coordinate (or second slow axis if angularly integrated). + \@angular0_indices: + \@angular0_depends: + angular1(NX_NUMBER): + unit: NX_ANGLE + doc: | + Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in + 2 dimensions) + \@angular1_indices: + \@angular1_depends: + spatial0(NX_NUMBER): + unit: NX_LENGTH + doc: | + Fast-axis spatial coordinate (or second slow axis if spatially integrated) + \@spatial0_indices: + \@spatial0_depends: + spatial1(NX_NUMBER): + unit: NX_LENGTH + doc: | + Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in + 2 dimensions) + \@spatial1_indices: + \@spatial1_depends: + delay(NX_NUMBER): + unit: NX_TIME + doc: | + Calibrated delay time. + \@delay_indices: + \@delay_depends: + polarization_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Linear polarization angle of the incoming or outgoing beam. + + Could be a link to /entry/instrument/beam/incident_polarization_angle or + /entry/instrument/beam/final_polarization_angle if they exist. + \@polarization_angle_indices: + \@polarization_angle_depends: + ellipticity(NX_FLOAT): + unit: NX_ANGLE + doc: | + Ellipticity of the incoming or outgoing beam. + + Can be any of linear polarization angle (degrees), ellipticity (arb. units). + Could be a link to /entry/instrument/beam/incident_ellipticity or + /entry/instrument/beam/final_ellipticity if they exist. + \@ellipticity_indices: + \@ellipticity_depends: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 139998aac40c149120e327c03095c7a8f4ef4a5891cdbdb6ddc0e7dcfaeca8c9 +# +# +# +# +# +# :ref:`NXdata_mpes` describes the plottable data and related dimension scales in MPES +# experiments. +# +# It extends the NXdata class and provides a glossary of explicitly named axis names +# which are typical for MPES data. +# +# +# +# Calibrated energy axis. +# +# This could be a link to either +# /entry/process/energy_calibration/calibrated_axis or +# /entry/process/energy_correction/calibrated_axis. +# +# +# +# The energy can be either stored as kinetic or as binding energy. +# +# +# +# +# Calibrated kinetic energy axis. +# +# This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. +# +# .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 +# +# +# +# +# Calibrated binding energy axis. +# +# This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. +# +# .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 +# +# +# +# +# +# +# +# +# +# Calibrated x axis in k-space. +# Units are 1/Angström. +# +# +# +# +# +# +# Calibrated y axis in k-space. +# Units are 1/Angström +# +# +# +# +# +# +# Calibrated z axis in k-space. +# Units are 1/Angström. +# +# +# +# +# +# +# Fast-axis angular coordinate (or second slow axis if angularly integrated). +# +# +# +# +# +# +# Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in +# 2 dimensions) +# +# +# +# +# +# +# Fast-axis spatial coordinate (or second slow axis if spatially integrated) +# +# +# +# +# +# +# Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in +# 2 dimensions) +# +# +# +# +# +# +# Calibrated delay time. +# +# +# +# +# +# +# Linear polarization angle of the incoming or outgoing beam. +# +# Could be a link to /entry/instrument/beam/incident_polarization_angle or +# /entry/instrument/beam/final_polarization_angle if they exist. +# +# +# +# +# +# +# Ellipticity of the incoming or outgoing beam. +# +# Can be any of linear polarization angle (degrees), ellipticity (arb. units). +# Could be a link to /entry/instrument/beam/incident_ellipticity or +# /entry/instrument/beam/final_ellipticity if they exist. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdata_mpes_detector.yaml b/contributed_definitions/nyaml/NXdata_mpes_detector.yaml new file mode 100644 index 0000000000..ccf82e6045 --- /dev/null +++ b/contributed_definitions/nyaml/NXdata_mpes_detector.yaml @@ -0,0 +1,336 @@ +category: base +doc: | + :ref:`NXdata_mpes_detector` describes the plottable data and related dimension scales + for raw detector data in MPES experiments. + + It extends the NXdata class and provides a glossary of explicitly named axis names + which are typical for raw MPES data. +type: group +NXdata_mpes_detector(NXdata): + \@signal: + enumeration: [raw] + raw(NX_NUMBER): + doc: | + Raw data before calibration. + pixel_x(NX_FLOAT): + unit: NX_ANY + doc: | + Detector pixel in x direction. + \@pixel_x_indices: + \@pixel_x_depends: + pixel_y(NX_FLOAT): + unit: NX_ANY + doc: | + Detector pixel in y direction. + \@pixel_y_indices: + \@pixel_y_depends: + energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + (Un)calibrated energy axis. + \@type: + type: NX_CHAR + doc: | + The energy can be either stored as kinetic or as binding energy. + enumeration: + kinetic: + doc: + - | + (Un)calibrated kinetic energy axis. + - | + xref: + spec: ISO 18115-1:2023 + term: 3.35 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + binding: + doc: + - | + (Un)calibrated binding energy axis. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.16 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + \@energy_indices: + \@energy_depends: + kx(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + (Un)calibrated x axis in k-space. + Units are 1/Angström. + \@kx_indices: + \@kx_depends: + ky(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + (Un)calibrated y axis in k-space. + Units are 1/Angström + \@ky_indices: + \@ky_depends: + kz(NX_NUMBER): + unit: NX_WAVENUMBER + doc: | + (Un)calibrated z axis in k-space. + Units are 1/Angström. + \@kz_indices: + \@kz_depends: + angular0(NX_NUMBER): + unit: NX_ANGLE + doc: | + Fast-axis angular coordinate (or second slow axis if angularly integrated). + \@angular0_indices: + \@angular0_depends: + angular1(NX_NUMBER): + unit: NX_ANGLE + doc: | + Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in two + dimensions) + \@angular1_indices: + \@angular1_depends: + spatial0(NX_NUMBER): + unit: NX_LENGTH + doc: | + Fast-axis spatial coordinate (or second slow axis if spatially integrated) + \@spatial0_indices: + \@spatial0_depends: + spatial1(NX_NUMBER): + unit: NX_LENGTH + doc: | + Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in two + dimensions) + \@spatial1_indices: + \@spatial1_depends: + + # exists in NXdetector base class + time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + doc: | + Total time of flight + \@time_of_flight_indices: + \@time_of_flight_depends: + time_of_flight_adc(NX_FLOAT): + unit: NX_ANY + doc: | + Time-of-flight values, analog-to-digital converted. + \@time_of_flight_adc_indices: + \@time_of_flight_adc_depends: + delay(NX_NUMBER): + unit: NX_TIME + doc: | + (Un)calibrated delay time. + \@delay_indices: + \@delay_depends: + polarization_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Linear polarization angle of the incoming or outgoing beam. + \@polarization_angle_indices: + \@polarization_angle_depends: + ellipticity(NX_FLOAT): + unit: NX_ANGLE + doc: | + Ellipticity of the incoming or outgoing beam. + \@ellipticity_indices: + \@ellipticity_depends: + external_AXIS(NX_NUMBER): + unit: NX_ANY + doc: | + Describes an axis which is coming from outside the detectors scope. + + Think of a detector just being triggered for readout by the rest of the experimental + setup - it would just know that it collected N images, which would flatten the external + parameters to one axis, too. + This can then be linked, e.g. with NXcalibration, to the appropriate fields in the instrument + and write it to the top-level NXdata. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 9428309dfa7497a26a3ea053ed9dae2d45a66d718656630be27e13e20611012d +# +# +# +# +# +# :ref:`NXdata_mpes_detector` describes the plottable data and related dimension scales +# for raw detector data in MPES experiments. +# +# It extends the NXdata class and provides a glossary of explicitly named axis names +# which are typical for raw MPES data. +# +# +# +# +# +# +# +# +# Raw data before calibration. +# +# +# +# +# Detector pixel in x direction. +# +# +# +# +# +# +# Detector pixel in y direction. +# +# +# +# +# +# +# (Un)calibrated energy axis. +# +# +# +# The energy can be either stored as kinetic or as binding energy. +# +# +# +# +# (Un)calibrated kinetic energy axis. +# +# This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. +# +# .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 +# +# +# +# +# (Un)calibrated binding energy axis. +# +# This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. +# +# .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 +# +# +# +# +# +# +# +# +# +# (Un)calibrated x axis in k-space. +# Units are 1/Angström. +# +# +# +# +# +# +# (Un)calibrated y axis in k-space. +# Units are 1/Angström +# +# +# +# +# +# +# (Un)calibrated z axis in k-space. +# Units are 1/Angström. +# +# +# +# +# +# +# Fast-axis angular coordinate (or second slow axis if angularly integrated). +# +# +# +# +# +# +# Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in two +# dimensions) +# +# +# +# +# +# +# Fast-axis spatial coordinate (or second slow axis if spatially integrated) +# +# +# +# +# +# +# Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in two +# dimensions) +# +# +# +# +# +# +# +# Total time of flight +# +# +# +# +# +# +# Time-of-flight values, analog-to-digital converted. +# +# +# +# +# +# +# (Un)calibrated delay time. +# +# +# +# +# +# +# Linear polarization angle of the incoming or outgoing beam. +# +# +# +# +# +# +# Ellipticity of the incoming or outgoing beam. +# +# +# +# +# +# +# Describes an axis which is coming from outside the detectors scope. +# +# Think of a detector just being triggered for readout by the rest of the experimental +# setup - it would just know that it collected N images, which would flatten the external +# parameters to one axis, too. +# This can then be linked, e.g. with NXcalibration, to the appropriate fields in the instrument +# and write it to the top-level NXdata. +# +# +# diff --git a/contributed_definitions/nyaml/NXdeflector.yaml b/contributed_definitions/nyaml/NXdeflector.yaml new file mode 100644 index 0000000000..874dee4304 --- /dev/null +++ b/contributed_definitions/nyaml/NXdeflector.yaml @@ -0,0 +1,43 @@ +category: base +doc: | + Deflectors as they are used e.g. in an electron analyser. +type: group +NXdeflector(NXobject): + type(NX_CHAR): + doc: | + Qualitative type of deflector with respect to the number of pole pieces. + enumeration: [dipole, quadrupole, hexapole, octupole] + name(NX_CHAR): + doc: | + Colloquial or short name for the deflector. For manufacturer names and + identifiers use respective manufacturer fields. + (NXfabrication): + description(NX_CHAR): # NXidentifier + doc: | + Ideally an identifier, persistent link, or free text which gives + further details about the deflector. + voltage(NX_NUMBER): + doc: | + Excitation voltage of the deflector. For dipoles it is a single number. + For higher order multipoles, it is an array. + unit: NX_VOLTAGE + current(NX_NUMBER): + doc: | + Excitation current of the deflector. For dipoles it is a single number. For + higher orders, it is an array. + unit: NX_CURRENT + \@depends_on(NX_CHAR): + doc: | + Specifies the position of the deflector by pointing to the last transformation + in the transformation chain in the NXtransformations group. + # discuss NXcomponent_mpes ? + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the deflector as a component in the instrument. Conventions from the + :ref:`NXtransformations` base class are used. In principle, the McStas coordinate + system is used. The first transformation has to point either to another + component of the system or . (for pointing to the reference frame) to relate it + relative to the experimental setup. Typically, the components of a system should + all be related relative to each other and only one component should relate to + the reference coordinate system. diff --git a/contributed_definitions/nyaml/NXdelocalization.yaml b/contributed_definitions/nyaml/NXdelocalization.yaml new file mode 100644 index 0000000000..77bdadd6ea --- /dev/null +++ b/contributed_definitions/nyaml/NXdelocalization.yaml @@ -0,0 +1,242 @@ +category: base +doc: | + Base class to describe the delocalization of point-like objects on a grid. + + Such a procedure is for instance used in image processing and e.g. atom probe + microscopy (APM) to discretize a point cloud onto a grid to enable e.g. + computing of point density, composition, or concentration values, obtain + scalar fields, and compute gradients of these fields. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_p: | + Number of points/objects. + n_m: | + Number of mark data per point/object. + n_atoms: | + Number of atoms in the whitelist. + n_isotopes: | + Number of isotopes in the whitelist. +type: group +NXdelocalization(NXobject): + grid: + doc: | + Reference or link to the grid on which the delocalization is applied. + objects: + doc: | + Reference or link to the points which are delocalized on the grid. + + # for APM the speciality is nothing but: + # each point marks the location of an ion (object) in the tomographic reconstruction + # there is a boolean mask which filters which ions, i.e. points are considered + # plus there is a weight interpretation model, specifically in atom probe + # if a (molecular) ion is decomposed into its atoms or isotopes + # plus, given there is such a weight interpretation model, there is a weight + # associated, specifically an integer >= 1 with each considered ion and 0 for + # all ions which are not considered, + # this weight is the multiplicity with respect to the interpretation model + # i.e. a C:2 molecular ion has a multiplicity of 2 if the ion is considered + # and the interpretation model that to consider carbon atoms or carbon ions + weighting_model: + doc: | + The weighting model specifies how mark data are mapped to a weight per point. + For atom probe microscopy (APM) as an example, different models are used which + account differently for the multiplicity of an ion/atom: + + * default, points all get the same weight 1.; + for APM this is equivalent to ion species + * atomic_decomposition, points get as much weight as they have atoms + of a type in element_whitelist, + * isotope_decomposition, points get as much weight as they have + isotopes of a type in isotope_whitelist. + + This description shows an example that could be reinterpreted for + similar such data processing steps in other fields of science. + enumeration: [default, atomic_decomposition, isotope_decomposition] + + # other + # can one conditionally set a field required if a weighting_model has a + # specific value, + # i.e. if atomic_decomposition is set element_whitelist t is required + # i.e. if isotope_decomposition is set isotope_whitelist is required? + element_whitelist(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of elements (via proton number) to consider for the atomic_decomposition + weighting model. Elements must exist in the periodic table of elements. + dimensions: + rank: 1 + dim: [[1, n_atoms]] + isotope_whitelist(NX_UINT): + unit: NX_UNITLESS + doc: | + A list of isotopes to consider for the isotope_decomposition weighting model. + Isotopes must exist in the nuclid table. Entries in the fastest changing + dimension should be the pair of proton (first entry) and neutron number + (second entry). + dimensions: + rank: 2 + dim: [[1, n_isotopes], [2, 2]] + mark(NX_NUMBER): + doc: | + Attribute data for each member of the point cloud. For APM these are the + ion species labels generated via ranging. The number of mark data per + point is 1 in the case for atom probe. + dimensions: + rank: 2 + dim: [[1, n_p], [2, n_m]] + weight(NX_NUMBER): + doc: | + Weighting factor with which the integrated intensity per grid cell is + multiplied specifically for each point. For APM the weight are positive + integer values, specifically the multiplicity of the ion, + according to the details of the weighting_model. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 38d91286faad0b8ce9904853bb66690d59cd3f393af678be595bd38812c6845d +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of points/objects. +# +# +# +# +# Number of mark data per point/object. +# +# +# +# +# Number of atoms in the whitelist. +# +# +# +# +# Number of isotopes in the whitelist. +# +# +# +# +# Base class to describe the delocalization of point-like objects on a grid. +# +# Such a procedure is for instance used in image processing and e.g. atom probe +# microscopy (APM) to discretize a point cloud onto a grid to enable e.g. +# computing of point density, composition, or concentration values, obtain +# scalar fields, and compute gradients of these fields. +# +# +# +# Reference or link to the grid on which the delocalization is applied. +# +# +# +# +# Reference or link to the points which are delocalized on the grid. +# +# +# +# +# +# The weighting model specifies how mark data are mapped to a weight per point. +# For atom probe microscopy (APM) as an example, different models are used which +# account differently for the multiplicity of an ion/atom: +# +# * default, points all get the same weight 1.; +# for APM this is equivalent to ion species +# * atomic_decomposition, points get as much weight as they have atoms +# of a type in element_whitelist, +# * isotope_decomposition, points get as much weight as they have +# isotopes of a type in isotope_whitelist. +# +# This description shows an example that could be reinterpreted for +# similar such data processing steps in other fields of science. +# +# +# +# +# +# +# +# +# +# +# A list of elements (via proton number) to consider for the atomic_decomposition +# weighting model. Elements must exist in the periodic table of elements. +# +# +# +# +# +# +# +# A list of isotopes to consider for the isotope_decomposition weighting model. +# Isotopes must exist in the nuclid table. Entries in the fastest changing +# dimension should be the pair of proton (first entry) and neutron number +# (second entry). +# +# +# +# +# +# +# +# +# Attribute data for each member of the point cloud. For APM these are the +# ion species labels generated via ranging. The number of mark data per +# point is 1 in the case for atom probe. +# +# +# +# +# +# +# +# +# Weighting factor with which the integrated intensity per grid cell is +# multiplied specifically for each point. For APM the weight are positive +# integer values, specifically the multiplicity of the ion, +# according to the details of the weighting_model. +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersion.yaml b/contributed_definitions/nyaml/NXdispersion.yaml new file mode 100644 index 0000000000..cd0be114f2 --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersion.yaml @@ -0,0 +1,52 @@ +category: base +doc: | + A dispersion denoting a sum of different dispersions. + All NXdispersion_table and NXdispersion_function groups will be added together + to form a single dispersion. +type: group +NXdispersion(NXobject): + model_name(NX_CHAR): + doc: | + The name of the composite model. + (NXdispersion_table): + (NXdispersion_function): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5382258a260b96c72eca642ef6d4c506d5a29926787e0cd5f66dafc96f75fef2 +# +# +# +# +# +# A dispersion denoting a sum of different dispersions. +# All NXdispersion_table and NXdispersion_function groups will be added together +# to form a single dispersion. +# +# +# +# The name of the composite model. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersion_function.yaml b/contributed_definitions/nyaml/NXdispersion_function.yaml new file mode 100644 index 0000000000..da0740742a --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersion_function.yaml @@ -0,0 +1,205 @@ +category: base +doc: | + This describes a dispersion function for a material or layer +symbols: + n_repetitions: | + The number of repetitions for the repeated parameters +type: group +NXdispersion_function(NXobject): + model_name(NX_CHAR): + doc: | + The name of this dispersion model. + formula(NX_CHAR): + doc: | + This should be a python parsable function. + Here we should provide which keywords are available + and a BNF of valid grammar. + convention(NX_CHAR): + doc: | + The sign convention being used (n + or - ik) + enumeration: [n + ik, n - ik] + energy_identifier(NX_CHAR): + doc: | + The identifier used to represent energy + in the formula. It is recommended to use `E`. + energy_min(NX_NUMBER): + unit: NX_ENERGY + doc: | + The minimum energy value at which this formula is valid. + energy_max(NX_NUMBER): + unit: NX_ENERGY + doc: | + The maximum energy value at which this formula is valid. + energy_unit(NX_NUMBER): + unit: NX_ENERGY + doc: | + The energy unit used in the formula. + The field value is a scaling factor for the units attribute. + It is recommeded to set the field value to 1 and carry all the unit + scaling information in the units attribute. + wavelength_identifier(NX_CHAR): + doc: | + The identifier useed to represent wavelength + in the formula. It is recommended to use `lambda`. + wavelength_unit(NX_NUMBER): + unit: NX_LENGTH + doc: | + The wavelength unit used in the formula. + The field value is a scaling factor for the units attribute. + It is recommeded to set the field value to 1 and carry all the unit + scaling information in the units attribute. + wavelength_min(NX_NUMBER): + unit: NX_LENGTH + doc: | + The minimum wavelength value at which this formula is valid. + wavelength_max(NX_NUMBER): + unit: NX_LENGTH + doc: | + The maximum wavelength value at which this formula is valid. + representation(NX_CHAR): + doc: | + Which representation does the formula evaluate to. + This may either be n for refractive index or eps for dielectric function. + The appropriate token is then to be used inside the formula. + enumeration: [n, eps] + (NXdispersion_single_parameter): + (NXdispersion_repeated_parameter): + parameter_units: + dimensions: + rank: 1 + dim: [[1, n_repetitions]] + values(NX_NUMBER): + dimensions: + rank: 1 + dim: [[1, n_repetitions]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c0b64c8c239e3f7d61b847ae27ab22bb5aa9c642e5ad6f3439cbacfde217e996 +# +# +# +# +# +# +# +# The number of repetitions for the repeated parameters +# +# +# +# +# This describes a dispersion function for a material or layer +# +# +# +# The name of this dispersion model. +# +# +# +# +# This should be a python parsable function. +# Here we should provide which keywords are available +# and a BNF of valid grammar. +# +# +# +# +# The sign convention being used (n + or - ik) +# +# +# +# +# +# +# +# +# The identifier used to represent energy +# in the formula. It is recommended to use `E`. +# +# +# +# +# The minimum energy value at which this formula is valid. +# +# +# +# +# The maximum energy value at which this formula is valid. +# +# +# +# +# The energy unit used in the formula. +# The field value is a scaling factor for the units attribute. +# It is recommeded to set the field value to 1 and carry all the unit +# scaling information in the units attribute. +# +# +# +# +# The identifier useed to represent wavelength +# in the formula. It is recommended to use `lambda`. +# +# +# +# +# The wavelength unit used in the formula. +# The field value is a scaling factor for the units attribute. +# It is recommeded to set the field value to 1 and carry all the unit +# scaling information in the units attribute. +# +# +# +# +# The minimum wavelength value at which this formula is valid. +# +# +# +# +# The maximum wavelength value at which this formula is valid. +# +# +# +# +# Which representation does the formula evaluate to. +# This may either be n for refractive index or eps for dielectric function. +# The appropriate token is then to be used inside the formula. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersion_repeated_parameter.yaml b/contributed_definitions/nyaml/NXdispersion_repeated_parameter.yaml new file mode 100644 index 0000000000..409661bce9 --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersion_repeated_parameter.yaml @@ -0,0 +1,99 @@ +category: base +doc: | + A repeated parameter for a dispersion function +symbols: + n_repetitions: | + The number of parameter repetitions +type: group +NXdispersion_repeated_parameter(NXobject): + name(NX_CHAR): + doc: | + The name of the parameter + description(NX_CHAR): + doc: | + A description of what this parameter represents + parameter_units(NX_CHAR): + doc: | + A unit array associating a unit with each parameter. + The first element should be equal to values/@unit. + The values should be SI interpretable standard units + with common prefixes (e.g. mikro, nano etc.) or their + short-hand notation (e.g. nm, mm, kHz etc.). + dimensions: + rank: 1 + dim: [[1, n_repetitions]] + values(NX_NUMBER): + unit: NX_ANY + doc: | + The value of the parameter + dimensions: + rank: 1 + dim: [[1, n_repetitions]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3333e10082e0d2c7f774ca993b5f12377856ab5887a0b088ab8b1a064991ab80 +# +# +# +# +# +# +# +# The number of parameter repetitions +# +# +# +# +# A repeated parameter for a dispersion function +# +# +# +# The name of the parameter +# +# +# +# +# A description of what this parameter represents +# +# +# +# +# A unit array associating a unit with each parameter. +# The first element should be equal to values/@unit. +# The values should be SI interpretable standard units +# with common prefixes (e.g. mikro, nano etc.) or their +# short-hand notation (e.g. nm, mm, kHz etc.). +# +# +# +# +# +# +# +# The value of the parameter +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersion_single_parameter.yaml b/contributed_definitions/nyaml/NXdispersion_single_parameter.yaml new file mode 100644 index 0000000000..7a06de9bfe --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersion_single_parameter.yaml @@ -0,0 +1,61 @@ +category: base +doc: | + A single parameter for a dispersion function +type: group +NXdispersion_single_parameter(NXobject): + name(NX_CHAR): + doc: | + The name of the parameter + description(NX_CHAR): + doc: | + A description of what this parameter represents + value(NX_NUMBER): + unit: NX_ANY + doc: | + The value of the parameter + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# f6f6c5dec785743e0c0f8b5fb70942367b1a4a0ccfe010705015f22bd95c204c +# +# +# +# +# +# A single parameter for a dispersion function +# +# +# +# The name of the parameter +# +# +# +# +# A description of what this parameter represents +# +# +# +# +# The value of the parameter +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersion_table.yaml b/contributed_definitions/nyaml/NXdispersion_table.yaml new file mode 100644 index 0000000000..862c88718a --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersion_table.yaml @@ -0,0 +1,140 @@ +category: base +doc: | + A dispersion table denoting energy, dielectric function tabulated values. +symbols: + doc: | + The symbols in this schema to denote the dimensions + n_points: | + The number of energy and dielectric function points +type: group +NXdispersion_table(NXobject): + model_name(NX_CHAR): + doc: | + The name of this dispersion model. + convention(NX_CHAR): + doc: | + The sign convention being used (n + or - ik) + enumeration: [n + ik, n - ik] + wavelength(NX_NUMBER): + unit: NX_LENGTH + doc: | + The wavelength array of the tabulated dataset. + This is essentially a duplicate of the energy field. + There should be one or both of them present. + dimensions: + rank: 1 + dim: [[1, n_points]] + energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + The energy array of the tabulated dataset. + This is essentially a duplicate of the wavelength field. + There should be one or both of them present. + dimensions: + rank: 1 + dim: [[1, n_points]] + refractive_index(NX_COMPLEX): + unit: NX_DIMENSIONLESS + doc: | + The refractive index array of the tabulated dataset. + dimensions: + rank: 1 + dim: [[1, n_points]] + dielectric_function(NX_COMPLEX): + unit: NX_DIMENSIONLESS + doc: | + The dielectric function of the tabulated dataset. + dimensions: + rank: 1 + dim: [[1, n_points]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 48116286e10a8ebd5f05be03756160d199447b78a8e587616d23061a3e1c8c50 +# +# +# +# +# +# +# The symbols in this schema to denote the dimensions +# +# +# +# The number of energy and dielectric function points +# +# +# +# +# A dispersion table denoting energy, dielectric function tabulated values. +# +# +# +# The name of this dispersion model. +# +# +# +# +# The sign convention being used (n + or - ik) +# +# +# +# +# +# +# +# +# The wavelength array of the tabulated dataset. +# This is essentially a duplicate of the energy field. +# There should be one or both of them present. +# +# +# +# +# +# +# +# The energy array of the tabulated dataset. +# This is essentially a duplicate of the wavelength field. +# There should be one or both of them present. +# +# +# +# +# +# +# +# The refractive index array of the tabulated dataset. +# +# +# +# +# +# +# +# The dielectric function of the tabulated dataset. +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdispersive_material.yaml b/contributed_definitions/nyaml/NXdispersive_material.yaml new file mode 100644 index 0000000000..8a62ad66f1 --- /dev/null +++ b/contributed_definitions/nyaml/NXdispersive_material.yaml @@ -0,0 +1,409 @@ +category: application +doc: | + NXdispersion +type: group +NXdispersive_material(NXobject): + (NXentry): + definition: + doc: | + An application definition for a dispersive material. + \@version: + doc: | + Version number to identify which definition of this application definition was + used for this entry/data. + \@url: + doc: | + URL where to find further material (documentation, examples) relevant to the + application definition + enumeration: [NXdispersive_material] + sample(NXsample): + chemical_formula(NX_CHAR): + atom_types(NX_CHAR): + exists: optional + doc: | + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + colloquial_name(NX_CHAR): + exists: optional + doc: | + The colloquial name of the material, e.g. graphite or diamond for carbon. + material_phase(NX_CHAR): + exists: optional + doc: | + The phase of the material + enumeration: [gas, liquid, solid, other] + material_phase_comment(NX_CHAR): + exists: optional + doc: | + Additional information about the phase if the + material phase is other. + additional_phase_information(NX_CHAR): + exists: recommended + doc: | + This field may be used to denote additional phase information, + such as crystalin phase of a crystal (e.g. 4H or 6H for SiC) or + if a measurement was done on a thin film or bulk material. + dispersion_type(NX_CHAR): + exists: recommended + doc: | + Denotes whether the dispersion is calculated or derived from an experiment + enumeration: [measured, simulated] + REFERENCES(NXcite): + exists: recommended + text: + doc: | + A text description of this reference, e.g. + `E. Example et al, The mighty example, An example journal 50 (2023), 100` + doi: + dispersion_x(NXdispersion): + doc: | + The dispersion along the optical axis of the material. + This should be the only dispersion available for isotropic materials. + For uniaxial materials this denotes the ordinary axis. + For biaxial materials this denotes the x axis or epsilon 11 tensor element + of the diagionalized permittivity tensor. + model_name(NX_CHAR): + doc: | + The name of this dispersion model. + (NXdispersion_table): + exists: recommended + model_name: + convention: + wavelength(NX_NUMBER): + dielectric_function(NX_COMPLEX): + exists: recommended + refractive_index(NX_COMPLEX): + exists: recommended + (NXdispersion_function): + exists: recommended + model_name: + formula: + convention: + energy_identifier: + exists: recommended + energy_unit(NX_NUMBER): + exists: recommended + wavelength_identifier: + exists: recommended + wavelength_unit(NX_NUMBER): + exists: recommended + representation: + (NXdispersion_single_parameter): + name: + value(NX_NUMBER): + (NXdispersion_repeated_parameter): + name: + values(NX_NUMBER): + plot(NXdata): + exists: recommended + dispersion_y(NXdispersion): + exists: optional + doc: | + This should only be filled for biaxial materials. + It denotes the epsilon 22 direction of the diagionalized + permittivity tensor. + model_name(NX_CHAR): + doc: | + The name of this dispersion model. + (NXdispersion_table): + exists: recommended + model_name: + convention: + wavelength(NX_NUMBER): + dielectric_function(NX_COMPLEX): + exists: recommended + refractive_index(NX_COMPLEX): + exists: recommended + (NXdispersion_function): + exists: recommended + model_name: + formula: + convention: + energy_identifier: + exists: recommended + energy_unit(NX_NUMBER): + exists: recommended + wavelength_identifier: + exists: recommended + wavelength_unit(NX_NUMBER): + exists: recommended + representation: + (NXdispersion_single_parameter): + name: + value(NX_NUMBER): + (NXdispersion_repeated_parameter): + name: + values(NX_NUMBER): + plot(NXdata): + exists: recommended + dispersion_z(NXdispersion): + exists: optional + doc: | + This should only be filled for uniaxial or biaxial materials. + For uniaxial materials this denotes the extraordinary axis. + For biaxial materials this denotes the epsilon 33 tensor element + of the diagionalized perimittivty tensor. + model_name(NX_CHAR): + doc: | + The name of this dispersion model. + (NXdispersion_table): + exists: recommended + model_name: + convention: + wavelength(NX_NUMBER): + dielectric_function(NX_COMPLEX): + exists: recommended + refractive_index(NX_COMPLEX): + exists: recommended + (NXdispersion_function): + exists: recommended + model_name: + formula: + convention: + energy_identifier: + exists: recommended + energy_unit(NX_NUMBER): + exists: recommended + wavelength_identifier: + exists: recommended + wavelength_unit(NX_NUMBER): + exists: recommended + representation: + (NXdispersion_single_parameter): + name: + value(NX_NUMBER): + (NXdispersion_repeated_parameter): + name: + values(NX_NUMBER): + plot(NXdata): + exists: recommended + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4f3fc95aec07d53a2d94428b85e9d688d916fc69844200218b2202ad3fb0f5b0 +# +# +# +# +# +# NXdispersion +# +# +# +# +# An application definition for a dispersive material. +# +# +# +# Version number to identify which definition of this application definition was +# used for this entry/data. +# +# +# +# +# URL where to find further material (documentation, examples) relevant to the +# application definition +# +# +# +# +# +# +# +# +# +# +# List of comma-separated elements from the periodic table +# that are contained in the sample. +# If the sample substance has multiple components, all +# elements from each component must be included in `atom_types`. +# +# +# +# +# The colloquial name of the material, e.g. graphite or diamond for carbon. +# +# +# +# +# The phase of the material +# +# +# +# +# +# +# +# +# +# +# Additional information about the phase if the +# material phase is other. +# +# +# +# +# This field may be used to denote additional phase information, +# such as crystalin phase of a crystal (e.g. 4H or 6H for SiC) or +# if a measurement was done on a thin film or bulk material. +# +# +# +# +# +# Denotes whether the dispersion is calculated or derived from an experiment +# +# +# +# +# +# +# +# +# +# A text description of this reference, e.g. +# `E. Example et al, The mighty example, An example journal 50 (2023), 100` +# +# +# +# +# +# +# The dispersion along the optical axis of the material. +# This should be the only dispersion available for isotropic materials. +# For uniaxial materials this denotes the ordinary axis. +# For biaxial materials this denotes the x axis or epsilon 11 tensor element +# of the diagionalized permittivity tensor. +# +# +# +# The name of this dispersion model. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should only be filled for biaxial materials. +# It denotes the epsilon 22 direction of the diagionalized +# permittivity tensor. +# +# +# +# The name of this dispersion model. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# This should only be filled for uniaxial or biaxial materials. +# For uniaxial materials this denotes the extraordinary axis. +# For biaxial materials this denotes the epsilon 33 tensor element +# of the diagionalized perimittivty tensor. +# +# +# +# The name of this dispersion model. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXdistortion.yaml b/contributed_definitions/nyaml/NXdistortion.yaml new file mode 100644 index 0000000000..94c3d6b0a1 --- /dev/null +++ b/contributed_definitions/nyaml/NXdistortion.yaml @@ -0,0 +1,177 @@ +category: base +doc: | + Subclass of NXprocess to describe post-processing distortion correction. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays + nsym: | + Number of symmetry points used for distortion correction + ndx: | + Number of points of the matrix distortion field (x direction) + ndy: | + Number of points of the matrix distortion field (y direction) +type: group +NXdistortion(NXobject): + last_process(NX_CHAR): + doc: | + Indicates the name of the last operation applied in the NXprocess sequence. + applied(NX_BOOLEAN): + doc: | + Has the distortion correction been applied? + symmetry(NX_INT): + unit: NX_UNITLESS + doc: | + For `symmetry-guided distortion correction`_, + where a pattern of features is mapped to the regular geometric structure expected + from the symmetry. Here we record the number of elementary symmetry operations. + + .. _symmetry-guided distortion correction: https://www.sciencedirect.com/science/article/abs/pii/S0304399118303474?via%3Dihub + original_centre(NX_FLOAT): + unit: NX_UNITLESS + doc: | + For symmetry-guided distortion correction. Here we record the coordinates of the + symmetry centre point. + dimensions: + rank: 1 + dim: [[1, 2]] + original_points(NX_FLOAT): + unit: NX_UNITLESS + doc: | + For symmetry-guided distortion correction. Here we record the coordinates of the + relevant symmetry points. + dimensions: + rank: 2 + dim: [[1, nsym], [2, 2]] + cdeform_field(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Column deformation field for general non-rigid distortion corrections. 2D matrix + holding the column information of the mapping of each original coordinate. + dimensions: + rank: 2 + dim: [[1, ndx], [2, ndy]] + rdeform_field(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Row deformation field for general non-rigid distortion corrections. 2D matrix + holding the row information of the mapping of each original coordinate. + dimensions: + rank: 2 + dim: [[1, ndx], [2, ndy]] + description(NX_CHAR): + doc: | + Description of the procedures employed. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8d4b961fbf0bfa0b579d13fcab264f3fba21c80b001620180e08bd4991d19fb1 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays +# +# +# +# Number of symmetry points used for distortion correction +# +# +# +# +# Number of points of the matrix distortion field (x direction) +# +# +# +# +# Number of points of the matrix distortion field (y direction) +# +# +# +# +# Subclass of NXprocess to describe post-processing distortion correction. +# +# +# +# Indicates the name of the last operation applied in the NXprocess sequence. +# +# +# +# +# Has the distortion correction been applied? +# +# +# +# +# For `symmetry-guided distortion correction`_, +# where a pattern of features is mapped to the regular geometric structure expected +# from the symmetry. Here we record the number of elementary symmetry operations. +# +# .. _symmetry-guided distortion correction: https://www.sciencedirect.com/science/article/abs/pii/S0304399118303474?via%3Dihub +# +# +# +# +# For symmetry-guided distortion correction. Here we record the coordinates of the +# symmetry centre point. +# +# +# +# +# +# +# +# For symmetry-guided distortion correction. Here we record the coordinates of the +# relevant symmetry points. +# +# +# +# +# +# +# +# +# Column deformation field for general non-rigid distortion corrections. 2D matrix +# holding the column information of the mapping of each original coordinate. +# +# +# +# +# +# +# +# +# Row deformation field for general non-rigid distortion corrections. 2D matrix +# holding the row information of the mapping of each original coordinate. +# +# +# +# +# +# +# +# +# Description of the procedures employed. +# +# +# diff --git a/contributed_definitions/nyaml/NXebeam_column.yaml b/contributed_definitions/nyaml/NXebeam_column.yaml new file mode 100644 index 0000000000..141250e339 --- /dev/null +++ b/contributed_definitions/nyaml/NXebeam_column.yaml @@ -0,0 +1,60 @@ +category: base +doc: | + Base class for a set of components providing a controllable electron beam. +# symbols: +# doc: The symbols used in the schema to specify e.g. variables. +type: group +# NXebeam_column is an NXobject instead of an NXcomponent_em to make that +# part "an electron gun" reusable in other context +NXebeam_column(NXobject): + (NXchamber): + (NXfabrication): + electron_source(NXsource): + doc: | + The source which creates the electron beam. + name(NX_CHAR): + doc: | + Given name/alias. + (NXfabrication): + voltage(NX_NUMBER): + doc: | + Voltage relevant to compute the energy of the electrons + immediately after they left the gun. + unit: NX_VOLTAGE + probe(NX_CHAR): + doc: | + Type of radiation. + enumeration: [electron] + emitter_type(NX_CHAR): + doc: | + Emitter type used to create the beam. + + If the emitter type is other, give further details + in the description field. + enumeration: [filament, schottky, cold_cathode_field_emitter, other] + emitter_material(NX_CHAR): + doc: | + Material of which the emitter is build, e.g. the filament material. + #MK could be made an instance of NXsample + description(NX_CHAR): # NXidentifier + doc: | + Ideally, a (globally) unique persistent identifier, link, + or text to a resource which gives further details. + # NEW ISSUE: details about the life/up-time of the source + # relevant from maintenance point of view + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. + (NXaperture_em): + (NXlens_em): + (NXcorrector_cs): + (NXscanbox_em): + (NXsensor): + (NXbeam): + doc: | + Individual characterization results for the position, shape, + and characteristics of the electron beam. + + :ref:`NXtransformations` should be used to specify the location + of the position at which the beam was probed. diff --git a/contributed_definitions/nyaml/NXelectron_level.yaml b/contributed_definitions/nyaml/NXelectron_level.yaml new file mode 100644 index 0000000000..ed9149e2fd --- /dev/null +++ b/contributed_definitions/nyaml/NXelectron_level.yaml @@ -0,0 +1,1465 @@ +category: base +doc: | + Electronic level probed in X-ray spectroscopy or resonance experiments. +type: group +NXelectron_level(NXobject): + element: + doc: | + Symbol of the chemical element. + + For each, the atomic number, common English name, and standard atomic weight are also given. + enumeration: + H: + doc: | + Z=1, name="hydrogen", standard_atomic_weight=1.0078 + He: + doc: | + Z=2, name="helium", standard_atomic_weight=4.0026 + Li: + doc: | + Z=3, name="lithium", standard_atomic_weight=6.94 + Be: + doc: | + Z=4, name="beryllium", standard_atomic_weight=9.0122 + B: + doc: | + Z=5, name="boron", standard_atomic_weight=10.81 + C: + doc: | + Z=6, name="carbon", standard_atomic_weight=12.011 + N: + doc: | + Z=7, name="nitrogen", standard_atomic_weight=14.007 + O: + doc: | + Z=8, name="oxygen", standard_atomic_weight=15.999 + F: + doc: | + Z=9, name="fluorine", standard_atomic_weight=18.9984 + Ne: + doc: | + Z=10, name="neon", standard_atomic_weight=20.1797 + Na: + doc: | + Z=11, name="sodium", standard_atomic_weight=22.9898 + Mg: + doc: | + Z=12, name="magnesium", standard_atomic_weight=24.305 + Al: + doc: | + Z=13, name="aluminum", standard_atomic_weight=26.9815 + Si: + doc: | + Z=14, name="silicon", standard_atomic_weight=28.085 + P: + doc: | + Z=15, name="phosphorus", standard_atomic_weight=30.9738 + S: + doc: | + Z=16, name="sulfur", standard_atomic_weight=32.06 + Cl: + doc: | + Z=17, name="chlorine", standard_atomic_weight=35.453 + Ar: + doc: | + Z=18, name="argon", standard_atomic_weight=39.948 + K: + doc: | + Z=19, name="potassium", standard_atomic_weight=39.0983 + Ca: + doc: | + Z=20, name="calcium", standard_atomic_weight=40.078 + Sc: + doc: | + Z=21, name="scandium", standard_atomic_weight=44.9559 + Ti: + doc: | + Z=22, name="titanium", standard_atomic_weight=47.867 + V: + doc: | + Z=23, name="vanadium", standard_atomic_weight=50.9415 + Cr: + doc: | + Z=24, name="chromium", standard_atomic_weight=51.996 + Mn: + doc: | + Z=25, name="manganese", standard_atomic_weight=54.938 + Fe: + doc: | + Z=26, name="iron", standard_atomic_weight=55.845 + Co: + doc: | + Z=27, name="cobalt", standard_atomic_weight=58.9332 + Ni: + doc: | + Z=28, name="nickel", standard_atomic_weight=58.6934 + Cu: + doc: | + Z=29, name="copper", standard_atomic_weight=63.546 + Zn: + doc: | + Z=30, name="zinc", standard_atomic_weight=65.38 + Ga: + doc: | + Z=31, name="gallium", standard_atomic_weight=69.72 + Ge: + doc: | + Z=32, name="germanium", standard_atomic_weight=72.63 + As: + doc: | + Z=33, name="arsenic", standard_atomic_weight=74.9216 + Se: + doc: | + Z=34, name="selenium", standard_atomic_weight=78.971 + Br: + doc: | + Z=35, name="bromine", standard_atomic_weight=79.904 + Kr: + doc: | + Z=36, name="krypton", standard_atomic_weight=83.798 + Rb: + doc: | + Z=37, name="rubidium", standard_atomic_weight=85.4678 + Sr: + doc: | + Z=38, name="strontium", standard_atomic_weight=87.62 + Y: + doc: | + Z=39, name="yttrium", standard_atomic_weight=88.9058 + Zr: + doc: | + Z=40, name="zirconium", standard_atomic_weight=91.224 + Nb: + doc: | + Z=41, name="niobium", standard_atomic_weight=92.9064 + Mo: + doc: | + Z=42, name="molybdenum", standard_atomic_weight=95.95 + Tc: + doc: | + Z=43, name="technetium", standard_atomic_weight=97.907 + Ru: + doc: | + Z=44, name="ruthenium", standard_atomic_weight=101.07 + Rh: + doc: | + Z=45, name="rhodium", standard_atomic_weight=102.906 + Pd: + doc: | + Z=46, name="palladium", standard_atomic_weight=106.42 + Ag: + doc: | + Z=47, name="silver", standard_atomic_weight=107.868 + Cd: + doc: | + Z=48, name="cadmium", standard_atomic_weight=112.414 + In: + doc: | + Z=49, name="indium", standard_atomic_weight=114.818 + Sn: + doc: | + Z=50, name="tin", standard_atomic_weight=118.71 + Sb: + doc: | + Z=51, name="antimony", standard_atomic_weight=121.76 + Te: + doc: | + Z=52, name="tellurium", standard_atomic_weight=127.6 + I: + doc: | + Z=53, name="iodine", standard_atomic_weight=126.905 + Xe: + doc: | + Z=54, name="xenon", standard_atomic_weight=131.293 + Cs: + doc: | + Z=55, name="cesium", standard_atomic_weight=132.905 + Ba: + doc: | + Z=56, name="barium", standard_atomic_weight=137.327 + La: + doc: | + Z=57, name="lanthanum", standard_atomic_weight=138.905 + Ce: + doc: | + Z=58, name="cerium", standard_atomic_weight=140.116 + Pr: + doc: | + Z=59, name="praseodymium", standard_atomic_weight=140.908 + Nd: + doc: | + Z=60, name="neodymium", standard_atomic_weight=144.242 + Pm: + doc: | + Z=61, name="promethium", standard_atomic_weight=145.0 + Sm: + doc: | + Z=62, name="samarium", standard_atomic_weight=150.36 + Eu: + doc: | + Z=63, name="europium", standard_atomic_weight=151.96 + Gd: + doc: | + Z=64, name="gadolinium", standard_atomic_weight=157.25 + Tb: + doc: | + Z=65, name="terbium", standard_atomic_weight=158.925 + Dy: + doc: | + Z=66, name="dysprosium", standard_atomic_weight=162.5 + Ho: + doc: | + Z=67, name="holmium", standard_atomic_weight=164.93 + Er: + doc: | + Z=68, name="erbium", standard_atomic_weight=167.259 + Tm: + doc: | + Z=69, name="thulium", standard_atomic_weight=168.934 + Yb: + doc: | + Z=70, name="ytterbium", standard_atomic_weight=173.045 + Lu: + doc: | + Z=71, name="lutetium", standard_atomic_weight=174.967 + Hf: + doc: | + Z=72, name="hafnium", standard_atomic_weight=178.49 + Ta: + doc: | + Z=73, name="tantalum", standard_atomic_weight=180.948 + W: + doc: | + Z=74, name="tungsten", standard_atomic_weight=183.84 + Re: + doc: | + Z=75, name="rhenium", standard_atomic_weight=186.207 + Os: + doc: | + Z=76, name="osmium", standard_atomic_weight=190.23 + Ir: + doc: | + Z=77, name="iridium", standard_atomic_weight=192.217 + Pt: + doc: | + Z=78, name="platinum", standard_atomic_weight=195.084 + Au: + doc: | + Z=79, name="gold", standard_atomic_weight=196.967 + Hg: + doc: | + Z=80, name="mercury", standard_atomic_weight=200.592 + Tl: + doc: | + Z=81, name="thallium", standard_atomic_weight=204.383 + Pb: + doc: | + Z=82, name="lead", standard_atomic_weight=207.2 + Bi: + doc: | + Z=83, name="bismuth", standard_atomic_weight=208.98 + Po: + doc: | + Z=84, name="polonium", standard_atomic_weight=209.0 + At: + doc: | + Z=85, name="astatine", standard_atomic_weight=210.0 + Rn: + doc: | + Z=86, name="radon", standard_atomic_weight=222.0 + Fr: + doc: | + Z=87, name="francium", standard_atomic_weight=223.0 + Ra: + doc: | + Z=88, name="radium", standard_atomic_weight=226.0 + Ac: + doc: | + Z=89, name="actinium", standard_atomic_weight=227.0 + Th: + doc: | + Z=90, name="thorium", standard_atomic_weight=232.038 + Pa: + doc: | + Z=91, name="protactinium", standard_atomic_weight=231.036 + U: + doc: | + Z=92, name="uranium", standard_atomic_weight=238.029 + Np: + doc: | + Z=93, name="neptunium", standard_atomic_weight=237.048 + Pu: + doc: | + Z=94, name="plutonium", standard_atomic_weight=239.052 + Am: + doc: | + Z=95, name="americium", standard_atomic_weight=243.0 + Cm: + doc: | + Z=96, name="curium", standard_atomic_weight=247.0 + Bk: + doc: | + Z=97, name="berkelium", standard_atomic_weight=247.0 + Cf: + doc: | + Z=98, name="californium", standard_atomic_weight=251.0 + Es: + doc: | + Z=99, name="einsteinium", standard_atomic_weight=252 + Fm: + doc: | + Z=100, name="fermium", standard_atomic_weight=257 + Md: + doc: | + Z=101, name="mendelevium", standard_atomic_weight=258 + "No": + doc: | + Z=102, name="nobelium", standard_atomic_weight=259 + Lr: + doc: | + Z=103, name="lawrencium", standard_atomic_weight=266 + Rf: + doc: | + Z=104, name="rutherfordium", standard_atomic_weight=267 + Db: + doc: | + Z=105, name="dubnium", standard_atomic_weight=268 + Sg: + doc: | + Z=106, name="seaborgium", standard_atomic_weight=269 + Bh: + doc: | + Z=107, name="bohrium", standard_atomic_weight=270 + Hs: + doc: | + Z=108, name="hassium", standard_atomic_weight=269 + Mt: + doc: | + Z=109, name="meitnerium", standard_atomic_weight=278 + Ds: + doc: | + Z=110, name="darmstadtium", standard_atomic_weight=281 + Rg: + doc: | + Z=111, name="roentgenium", standard_atomic_weight=282 + Cn: + doc: | + Z=112, name="copernicium", standard_atomic_weight=285 + Nh: + doc: | + Z=113, name="nihonium", standard_atomic_weight=286 + Fl: + doc: | + Z=114, name="flerovium", standard_atomic_weight=289 + Mc: + doc: | + Z=115, name="moscovium", standard_atomic_weight=290 + Lv: + doc: | + Z=116, name="livermorium", standard_atomic_weight=293 + Ts: + doc: | + Z=117, name="tennessine", standard_atomic_weight=294 + Og: + doc: | + Z=118, name="oganesson", standard_atomic_weight=294 + level_iupac: + doc: | + IUPAC symbol of the electronic level. + For each level, the electronic orbital configuration is also given + + For reference, see Jenkins, R., Manne, R., Robin, R., & Senemaud, C. (1991). + IUPAC—nomenclature system for x-ray spectroscopy. X-Ray Spectrometry, 20(3), 149-155. + enumeration: + K: + doc: | + same as 1s in level_xray + L1: + doc: | + 2s + L2: + doc: | + 2p_{1/2} + L3: + doc: | + 2p_{3/2} + M1: + doc: | + 3s + M2: + doc: | + 3p_{1/2} + M3: + doc: | + 3p_{3/2} + M4: + doc: | + 3d_{3/2} + M5: + doc: | + 3d_{5/2} + N1: + doc: | + 4s + N2: + doc: | + 4p_{1/2} + N3: + doc: | + 4p_{3/2} + N4: + doc: | + 4d_{3/2} + N5: + doc: | + 4d_{5/2} + N6: + doc: | + 4f_{5/2} + N7: + doc: | + 4f_{7/2} + O1: + doc: | + 5s + O2: + doc: | + 5p_{1/2} + O3: + doc: | + 5p_{3/2} + O4: + doc: | + 5d_{3/2} + O5: + doc: | + 5d_{5/2} + O6: + doc: | + 5f_{5/2} + O7: + doc: | + 5f_{7/2} + P1: + doc: | + 6s + P2: + doc: | + 6p_{1/2} + P3: + doc: | + 6p_{3/2} + level_electron_config: + doc: | + Electronic orbital configuration of the electronic level. + enumeration: + 1s: + doc: | + same as K in level_xray + 2s: + doc: | + L1 + 2p1/2: + doc: | + L3 + 3s: + doc: | + M1 + 3p1/2: + doc: | + M2 + 3p3/2: + doc: | + M3 + 3d3/2: + doc: | + M4 + 3d5/2: + doc: | + M5 + 4s: + doc: | + N1 + 4p1/2: + doc: | + N2 + 4p3/2: + doc: | + N3 + 4d3/2: + doc: | + N4 + 4d5/2: + doc: | + N5 + 4f5/2: + doc: | + N6 + 4f7/2: + doc: | + N7 + 5s: + doc: | + O1 + 5p1/2: + doc: | + O2 + 5p3/2: + doc: | + O3 + 5d3/2: + doc: | + O4 + 5d5/2: + doc: | + O5 + 5f5/2: + doc: | + O6 + 5f7/2: + doc: | + O7 + 6s: + doc: | + P1 + 6p1/2: + doc: | + P2 + 6p3/2: + doc: | + P3 + \@description: + doc: | + description of X-ray electronic level + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# f15a465a52ff8afca9ae40f5a19eaaa00cf0defe098ab7a0b76a3692acd4bc29 +# +# +# +# +# +# Electronic level probed in X-ray spectroscopy or resonance experiments. +# +# +# +# Symbol of the chemical element. +# +# For each, the atomic number, common English name, and standard atomic weight are also given. +# +# +# +# +# Z=1, name="hydrogen", standard_atomic_weight=1.0078 +# +# +# +# +# Z=2, name="helium", standard_atomic_weight=4.0026 +# +# +# +# +# Z=3, name="lithium", standard_atomic_weight=6.94 +# +# +# +# +# Z=4, name="beryllium", standard_atomic_weight=9.0122 +# +# +# +# +# Z=5, name="boron", standard_atomic_weight=10.81 +# +# +# +# +# Z=6, name="carbon", standard_atomic_weight=12.011 +# +# +# +# +# Z=7, name="nitrogen", standard_atomic_weight=14.007 +# +# +# +# +# Z=8, name="oxygen", standard_atomic_weight=15.999 +# +# +# +# +# Z=9, name="fluorine", standard_atomic_weight=18.9984 +# +# +# +# +# Z=10, name="neon", standard_atomic_weight=20.1797 +# +# +# +# +# Z=11, name="sodium", standard_atomic_weight=22.9898 +# +# +# +# +# Z=12, name="magnesium", standard_atomic_weight=24.305 +# +# +# +# +# Z=13, name="aluminum", standard_atomic_weight=26.9815 +# +# +# +# +# Z=14, name="silicon", standard_atomic_weight=28.085 +# +# +# +# +# Z=15, name="phosphorus", standard_atomic_weight=30.9738 +# +# +# +# +# Z=16, name="sulfur", standard_atomic_weight=32.06 +# +# +# +# +# Z=17, name="chlorine", standard_atomic_weight=35.453 +# +# +# +# +# Z=18, name="argon", standard_atomic_weight=39.948 +# +# +# +# +# Z=19, name="potassium", standard_atomic_weight=39.0983 +# +# +# +# +# Z=20, name="calcium", standard_atomic_weight=40.078 +# +# +# +# +# Z=21, name="scandium", standard_atomic_weight=44.9559 +# +# +# +# +# Z=22, name="titanium", standard_atomic_weight=47.867 +# +# +# +# +# Z=23, name="vanadium", standard_atomic_weight=50.9415 +# +# +# +# +# Z=24, name="chromium", standard_atomic_weight=51.996 +# +# +# +# +# Z=25, name="manganese", standard_atomic_weight=54.938 +# +# +# +# +# Z=26, name="iron", standard_atomic_weight=55.845 +# +# +# +# +# Z=27, name="cobalt", standard_atomic_weight=58.9332 +# +# +# +# +# Z=28, name="nickel", standard_atomic_weight=58.6934 +# +# +# +# +# Z=29, name="copper", standard_atomic_weight=63.546 +# +# +# +# +# Z=30, name="zinc", standard_atomic_weight=65.38 +# +# +# +# +# Z=31, name="gallium", standard_atomic_weight=69.72 +# +# +# +# +# Z=32, name="germanium", standard_atomic_weight=72.63 +# +# +# +# +# Z=33, name="arsenic", standard_atomic_weight=74.9216 +# +# +# +# +# Z=34, name="selenium", standard_atomic_weight=78.971 +# +# +# +# +# Z=35, name="bromine", standard_atomic_weight=79.904 +# +# +# +# +# Z=36, name="krypton", standard_atomic_weight=83.798 +# +# +# +# +# Z=37, name="rubidium", standard_atomic_weight=85.4678 +# +# +# +# +# Z=38, name="strontium", standard_atomic_weight=87.62 +# +# +# +# +# Z=39, name="yttrium", standard_atomic_weight=88.9058 +# +# +# +# +# Z=40, name="zirconium", standard_atomic_weight=91.224 +# +# +# +# +# Z=41, name="niobium", standard_atomic_weight=92.9064 +# +# +# +# +# Z=42, name="molybdenum", standard_atomic_weight=95.95 +# +# +# +# +# Z=43, name="technetium", standard_atomic_weight=97.907 +# +# +# +# +# Z=44, name="ruthenium", standard_atomic_weight=101.07 +# +# +# +# +# Z=45, name="rhodium", standard_atomic_weight=102.906 +# +# +# +# +# Z=46, name="palladium", standard_atomic_weight=106.42 +# +# +# +# +# Z=47, name="silver", standard_atomic_weight=107.868 +# +# +# +# +# Z=48, name="cadmium", standard_atomic_weight=112.414 +# +# +# +# +# Z=49, name="indium", standard_atomic_weight=114.818 +# +# +# +# +# Z=50, name="tin", standard_atomic_weight=118.71 +# +# +# +# +# Z=51, name="antimony", standard_atomic_weight=121.76 +# +# +# +# +# Z=52, name="tellurium", standard_atomic_weight=127.6 +# +# +# +# +# Z=53, name="iodine", standard_atomic_weight=126.905 +# +# +# +# +# Z=54, name="xenon", standard_atomic_weight=131.293 +# +# +# +# +# Z=55, name="cesium", standard_atomic_weight=132.905 +# +# +# +# +# Z=56, name="barium", standard_atomic_weight=137.327 +# +# +# +# +# Z=57, name="lanthanum", standard_atomic_weight=138.905 +# +# +# +# +# Z=58, name="cerium", standard_atomic_weight=140.116 +# +# +# +# +# Z=59, name="praseodymium", standard_atomic_weight=140.908 +# +# +# +# +# Z=60, name="neodymium", standard_atomic_weight=144.242 +# +# +# +# +# Z=61, name="promethium", standard_atomic_weight=145.0 +# +# +# +# +# Z=62, name="samarium", standard_atomic_weight=150.36 +# +# +# +# +# Z=63, name="europium", standard_atomic_weight=151.96 +# +# +# +# +# Z=64, name="gadolinium", standard_atomic_weight=157.25 +# +# +# +# +# Z=65, name="terbium", standard_atomic_weight=158.925 +# +# +# +# +# Z=66, name="dysprosium", standard_atomic_weight=162.5 +# +# +# +# +# Z=67, name="holmium", standard_atomic_weight=164.93 +# +# +# +# +# Z=68, name="erbium", standard_atomic_weight=167.259 +# +# +# +# +# Z=69, name="thulium", standard_atomic_weight=168.934 +# +# +# +# +# Z=70, name="ytterbium", standard_atomic_weight=173.045 +# +# +# +# +# Z=71, name="lutetium", standard_atomic_weight=174.967 +# +# +# +# +# Z=72, name="hafnium", standard_atomic_weight=178.49 +# +# +# +# +# Z=73, name="tantalum", standard_atomic_weight=180.948 +# +# +# +# +# Z=74, name="tungsten", standard_atomic_weight=183.84 +# +# +# +# +# Z=75, name="rhenium", standard_atomic_weight=186.207 +# +# +# +# +# Z=76, name="osmium", standard_atomic_weight=190.23 +# +# +# +# +# Z=77, name="iridium", standard_atomic_weight=192.217 +# +# +# +# +# Z=78, name="platinum", standard_atomic_weight=195.084 +# +# +# +# +# Z=79, name="gold", standard_atomic_weight=196.967 +# +# +# +# +# Z=80, name="mercury", standard_atomic_weight=200.592 +# +# +# +# +# Z=81, name="thallium", standard_atomic_weight=204.383 +# +# +# +# +# Z=82, name="lead", standard_atomic_weight=207.2 +# +# +# +# +# Z=83, name="bismuth", standard_atomic_weight=208.98 +# +# +# +# +# Z=84, name="polonium", standard_atomic_weight=209.0 +# +# +# +# +# Z=85, name="astatine", standard_atomic_weight=210.0 +# +# +# +# +# Z=86, name="radon", standard_atomic_weight=222.0 +# +# +# +# +# Z=87, name="francium", standard_atomic_weight=223.0 +# +# +# +# +# Z=88, name="radium", standard_atomic_weight=226.0 +# +# +# +# +# Z=89, name="actinium", standard_atomic_weight=227.0 +# +# +# +# +# Z=90, name="thorium", standard_atomic_weight=232.038 +# +# +# +# +# Z=91, name="protactinium", standard_atomic_weight=231.036 +# +# +# +# +# Z=92, name="uranium", standard_atomic_weight=238.029 +# +# +# +# +# Z=93, name="neptunium", standard_atomic_weight=237.048 +# +# +# +# +# Z=94, name="plutonium", standard_atomic_weight=239.052 +# +# +# +# +# Z=95, name="americium", standard_atomic_weight=243.0 +# +# +# +# +# Z=96, name="curium", standard_atomic_weight=247.0 +# +# +# +# +# Z=97, name="berkelium", standard_atomic_weight=247.0 +# +# +# +# +# Z=98, name="californium", standard_atomic_weight=251.0 +# +# +# +# +# Z=99, name="einsteinium", standard_atomic_weight=252 +# +# +# +# +# Z=100, name="fermium", standard_atomic_weight=257 +# +# +# +# +# Z=101, name="mendelevium", standard_atomic_weight=258 +# +# +# +# +# Z=102, name="nobelium", standard_atomic_weight=259 +# +# +# +# +# Z=103, name="lawrencium", standard_atomic_weight=266 +# +# +# +# +# Z=104, name="rutherfordium", standard_atomic_weight=267 +# +# +# +# +# Z=105, name="dubnium", standard_atomic_weight=268 +# +# +# +# +# Z=106, name="seaborgium", standard_atomic_weight=269 +# +# +# +# +# Z=107, name="bohrium", standard_atomic_weight=270 +# +# +# +# +# Z=108, name="hassium", standard_atomic_weight=269 +# +# +# +# +# Z=109, name="meitnerium", standard_atomic_weight=278 +# +# +# +# +# Z=110, name="darmstadtium", standard_atomic_weight=281 +# +# +# +# +# Z=111, name="roentgenium", standard_atomic_weight=282 +# +# +# +# +# Z=112, name="copernicium", standard_atomic_weight=285 +# +# +# +# +# Z=113, name="nihonium", standard_atomic_weight=286 +# +# +# +# +# Z=114, name="flerovium", standard_atomic_weight=289 +# +# +# +# +# Z=115, name="moscovium", standard_atomic_weight=290 +# +# +# +# +# Z=116, name="livermorium", standard_atomic_weight=293 +# +# +# +# +# Z=117, name="tennessine", standard_atomic_weight=294 +# +# +# +# +# Z=118, name="oganesson", standard_atomic_weight=294 +# +# +# +# +# +# +# IUPAC symbol of the electronic level. +# For each level, the electronic orbital configuration is also given +# +# For reference, see Jenkins, R., Manne, R., Robin, R., & Senemaud, C. (1991). +# IUPAC—nomenclature system for x-ray spectroscopy. X-Ray Spectrometry, 20(3), 149-155. +# +# +# +# +# same as 1s in level_xray +# +# +# +# +# 2s +# +# +# +# +# 2p_{1/2} +# +# +# +# +# 2p_{3/2} +# +# +# +# +# 3s +# +# +# +# +# 3p_{1/2} +# +# +# +# +# 3p_{3/2} +# +# +# +# +# 3d_{3/2} +# +# +# +# +# 3d_{5/2} +# +# +# +# +# 4s +# +# +# +# +# 4p_{1/2} +# +# +# +# +# 4p_{3/2} +# +# +# +# +# 4d_{3/2} +# +# +# +# +# 4d_{5/2} +# +# +# +# +# 4f_{5/2} +# +# +# +# +# 4f_{7/2} +# +# +# +# +# 5s +# +# +# +# +# 5p_{1/2} +# +# +# +# +# 5p_{3/2} +# +# +# +# +# 5d_{3/2} +# +# +# +# +# 5d_{5/2} +# +# +# +# +# 5f_{5/2} +# +# +# +# +# 5f_{7/2} +# +# +# +# +# 6s +# +# +# +# +# 6p_{1/2} +# +# +# +# +# 6p_{3/2} +# +# +# +# +# +# +# Electronic orbital configuration of the electronic level. +# +# +# +# +# same as K in level_xray +# +# +# +# +# L1 +# +# +# +# +# L3 +# +# +# +# +# M1 +# +# +# +# +# M2 +# +# +# +# +# M3 +# +# +# +# +# M4 +# +# +# +# +# M5 +# +# +# +# +# N1 +# +# +# +# +# N2 +# +# +# +# +# N3 +# +# +# +# +# N4 +# +# +# +# +# N5 +# +# +# +# +# N6 +# +# +# +# +# N7 +# +# +# +# +# O1 +# +# +# +# +# O2 +# +# +# +# +# O3 +# +# +# +# +# O4 +# +# +# +# +# O5 +# +# +# +# +# O6 +# +# +# +# +# O7 +# +# +# +# +# P1 +# +# +# +# +# P2 +# +# +# +# +# P3 +# +# +# +# +# +# +# description of X-ray electronic level +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# diff --git a/contributed_definitions/nyaml/NXelectronanalyser.yaml b/contributed_definitions/nyaml/NXelectronanalyser.yaml new file mode 100644 index 0000000000..848bca0254 --- /dev/null +++ b/contributed_definitions/nyaml/NXelectronanalyser.yaml @@ -0,0 +1,492 @@ +category: base +doc: +- | + Basic class for describing a electron analyzer. +- | + xref: + spec: ISO 18115-1:2023 + term: 12.59 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.59 +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays + nfa: | + Number of fast axes (axes acquired simultaneously, without scanning a + physical quantity) + nsa: | + Number of slow axes (axes acquired scanning a physical quantity) + n_transmission_function: | + Number of data points in the transmission function. +type: group +NXelectronanalyser(NXobject): + description(NX_CHAR): + doc: | + Free text description of the type of the detector + name(NX_CHAR): + doc: | + Name or model of the equipment + \@short_name: + type: NX_CHAR + doc: | + Acronym or other shorthand name + work_function(NX_FLOAT): + unit: NX_ENERGY + doc: | + Work function of the electron analyser. + + The work function of a uniform surface of a conductor is the minimum energy required to remove + an electron from the interior of the solid to a vacuum level immediately outside the solid surface. + + The kinetic energy :math:`E_K` of a photoelectron emitted from an energy-level with binding energy + :math:`E_B` below the Fermi level is given by :math:`E_K = h\nu - E_B - W = h\nu - E_B - e \phi_{\mathrm{sample}}`. + Here, :math:`W = e \phi_{\mathrm{sample}}` is the work function of the sample surface (with the potential difference :math:`\phi_{\mathrm{sample}}` + between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the vacuum just outside the surface). + + In PES measurements, the sample and the spectrometer (with work function :math:`\phi_{\mathrm{spectr.}}`) + are electrically connected and therefore their Fermi levels are aligned. Due to the difference in local + vacuum level between the sample and spectrometer, there exists an electric potential difference (contact potential) + :math:`\Delta\phi = \phi_{\mathrm{sample}} - \phi_{\mathrm{spectr.}}`. The measured kinetic energy of + a photoelectron in PES is therefore given by + :math:`E_K^{\mathrm{meas.}} = h\nu - E_B + \Delta \phi = h\nu - E_B - e \phi_{\mathrm{spectr.}}`. + As a result, the measured kinetic energy :math:`E_K^{\mathrm{meas.}}` of a photoelectron is `independent` + of the sample work function. Nonetheless, the work function :math:`\phi_s` needs to be known to + accurately determine the binding energy scale. + voltage_energy_range(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Energy range of the voltage supplies. This influences the noise of the supplies, + and thereby the energy resolution. + energy_resolution(NXresolution): + doc: + - | + Energy resolution of the analyser with the current setting. May be linked from an + NXcalibration. + - | + xref: + spec: ISO 18115-1:2023 + term: 10.24 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 + physical_quantity: + enumeration: [energy] + resolution(NX_FLOAT): + unit: NX_ENERGY + resolution_errors(NX_FLOAT): + unit: NX_ENERGY + momentum_resolution(NXresolution): + doc: | + Momentum resolution of the electron analyser (FWHM) + physical_quantity: + enumeration: [momentum] + resolution(NX_FLOAT): + unit: NX_WAVENUMBER + resolution_errors(NX_FLOAT): + unit: NX_WAVENUMBER + angular_resolution(NXresolution): + doc: | + Angular resolution of the electron analyser (FWHM) + physical_quantity: + enumeration: [angle] + resolution(NX_FLOAT): + unit: NX_ANGLE + resolution_errors(NX_FLOAT): + unit: NX_ANGLE + spatial_resolution(NXresolution): + doc: + - | + Spatial resolution of the electron analyser (Airy disk radius) + - | + xref: + spec: ISO 18115-1:2023 + term: 10.15 ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.15 + physical_quantity: + enumeration: [length] + resolution(NX_FLOAT): + unit: NX_LENGTH + resolution_errors(NX_FLOAT): + unit: NX_LENGTH + fast_axes(NX_CHAR): + doc: | + List of the axes that are acquired simultaneously by the detector. + These refer only to the experimental variables recorded by the electron analyser. + Other variables such as temperature, manipulator angles etc. are labeled as fast or slow in the data. + + .. csv-table:: Examples + :header: "Mode", "fast_axes", "slow_axes" + + Hemispherical in ARPES mode, "['energy', 'kx']","" + "Hemispherical with channeltron, sweeping energy mode", "", [\"energy\"] + "Tof", "['energy', 'kx', 'ky']","" + "Momentum microscope, spin-resolved", "['energy', 'kx', 'ky']", "['spin up-down', 'spin left-right']" + + Axes may be less abstract than this, i.e. ['detector_x', 'detector_y']. + If energy_scan_mode=sweep, fast_axes: ['energy', 'kx']; slow_axes: ['energy'] is allowed. + dimensions: + rank: 1 + dim: [[1, nfa]] + slow_axes(NX_CHAR): + doc: | + List of the axes that are acquired by scanning a physical parameter, listed in + order of decreasing speed. See fast_axes for examples. + dimensions: + rank: 1 + dim: [[1, nsa]] + transmission_function(NXdata): + doc: + - | + Transmission function of the electron analyser. + - | + The transmission function (TF) specifies the detection efficiency per solid angle for electrons of + different kinetic energy passing through the electron analyser. It depends on the spectrometer + geometry as well as operation settings such as lens mode and pass energy. + The transmission function is usually given as relative intensity vs. kinetic energy. + - | + The TF is used for calibration of the intensity scale in quantitative XPS. Without proper + transmission correction, a comparison of results measured from the same sample using different + operating modes for an instrument would show significant variations in atomic + concentrations. + - | + xref: + spec: ISO 18115-1:2023 + term: 7.15 ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.15 + \@signal: + enumeration: [relative_intensity] + \@axes: + enumeration: [kinetic_energy] + kinetic_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Kinetic energy values + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + relative_intensity(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Relative transmission efficiency for the given kinetic energies + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + depends_on(NX_CHAR): + doc: | + Refers to the last transformation specifying the position of the electron analyser + in the NXtransformations chain. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the electron analyser as a component in the instrument. Conventions + from the NXtransformations base class are used. In principle, the McStas + coordinate system is used. The first transformation has to point either to + another component of the system or "." (for pointing to the reference frame) to + relate it relative to the experimental setup. Typically, the components of a + system should all be related relative to each other and only one component + should relate to the reference coordinate system. + (NXcollectioncolumn): + doc: | + Describes the electron collection (spatial and momentum imaging) column + (NXenergydispersion): + doc: | + Describes the energy dispersion section + (NXspindispersion): + doc: | + Describes the spin dispersion section + (NXdetector): + doc: | + Describes the electron detector + (NXdeflector): + doc: | + Deflectors outside the main optics ensembles described by the subclasses + (NXlens_em): + doc: | + Individual lenses outside the main optics ensembles described by the subclasses + (NXfabrication): + (NXresolution): + doc: | + Any other resolution not explicitly named in this base class. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a713eabad7ec1246a1ceba9da426fd1188b23ddbd16fe7db6271b823ca6dbcd7 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays +# +# +# +# Number of fast axes (axes acquired simultaneously, without scanning a +# physical quantity) +# +# +# +# +# Number of slow axes (axes acquired scanning a physical quantity) +# +# +# +# +# Number of data points in the transmission function. +# +# +# +# +# Basic class for describing a electron analyzer. +# +# This concept is related to term `12.59`_ of the ISO 18115-1:2023 standard. +# +# .. _12.59: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.59 +# +# +# +# Free text description of the type of the detector +# +# +# +# +# Name or model of the equipment +# +# +# +# Acronym or other shorthand name +# +# +# +# +# +# Work function of the electron analyser. +# +# The work function of a uniform surface of a conductor is the minimum energy required to remove +# an electron from the interior of the solid to a vacuum level immediately outside the solid surface. +# +# The kinetic energy :math:`E_K` of a photoelectron emitted from an energy-level with binding energy +# :math:`E_B` below the Fermi level is given by :math:`E_K = h\nu - E_B - W = h\nu - E_B - e \phi_{\mathrm{sample}}`. +# Here, :math:`W = e \phi_{\mathrm{sample}}` is the work function of the sample surface (with the potential difference :math:`\phi_{\mathrm{sample}}` +# between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the vacuum just outside the surface). +# +# In PES measurements, the sample and the spectrometer (with work function :math:`\phi_{\mathrm{spectr.}}`) +# are electrically connected and therefore their Fermi levels are aligned. Due to the difference in local +# vacuum level between the sample and spectrometer, there exists an electric potential difference (contact potential) +# :math:`\Delta\phi = \phi_{\mathrm{sample}} - \phi_{\mathrm{spectr.}}`. The measured kinetic energy of +# a photoelectron in PES is therefore given by +# :math:`E_K^{\mathrm{meas.}} = h\nu - E_B + \Delta \phi = h\nu - E_B - e \phi_{\mathrm{spectr.}}`. +# As a result, the measured kinetic energy :math:`E_K^{\mathrm{meas.}}` of a photoelectron is `independent` +# of the sample work function. Nonetheless, the work function :math:`\phi_s` needs to be known to +# accurately determine the binding energy scale. +# +# +# +# +# Energy range of the voltage supplies. This influences the noise of the supplies, +# and thereby the energy resolution. +# +# +# +# +# Energy resolution of the analyser with the current setting. May be linked from an +# NXcalibration. +# +# This concept is related to term `10.24`_ of the ISO 18115-1:2023 standard. +# +# .. _10.24: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 +# +# +# +# +# +# +# +# +# +# +# +# Momentum resolution of the electron analyser (FWHM) +# +# +# +# +# +# +# +# +# +# +# +# Angular resolution of the electron analyser (FWHM) +# +# +# +# +# +# +# +# +# +# +# +# Spatial resolution of the electron analyser (Airy disk radius) +# +# This concept is related to term `10.15 ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _10.15 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.15 +# +# +# +# +# +# +# +# +# +# +# +# List of the axes that are acquired simultaneously by the detector. +# These refer only to the experimental variables recorded by the electron analyser. +# Other variables such as temperature, manipulator angles etc. are labeled as fast or slow in the data. +# +# .. csv-table:: Examples +# :header: "Mode", "fast_axes", "slow_axes" +# +# Hemispherical in ARPES mode, "['energy', 'kx']","" +# "Hemispherical with channeltron, sweeping energy mode", "", [\"energy\"] +# "Tof", "['energy', 'kx', 'ky']","" +# "Momentum microscope, spin-resolved", "['energy', 'kx', 'ky']", "['spin up-down', 'spin left-right']" +# +# Axes may be less abstract than this, i.e. ['detector_x', 'detector_y']. +# If energy_scan_mode=sweep, fast_axes: ['energy', 'kx']; slow_axes: ['energy'] is allowed. +# +# +# +# +# +# +# +# List of the axes that are acquired by scanning a physical parameter, listed in +# order of decreasing speed. See fast_axes for examples. +# +# +# +# +# +# +# +# Transmission function of the electron analyser. +# +# The transmission function (TF) specifies the detection efficiency per solid angle for electrons of +# different kinetic energy passing through the electron analyser. It depends on the spectrometer +# geometry as well as operation settings such as lens mode and pass energy. +# The transmission function is usually given as relative intensity vs. kinetic energy. +# +# The TF is used for calibration of the intensity scale in quantitative XPS. Without proper +# transmission correction, a comparison of results measured from the same sample using different +# operating modes for an instrument would show significant variations in atomic +# concentrations. +# +# This concept is related to term `7.15 ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _7.15 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:7.15 +# +# +# +# +# +# +# +# +# +# +# +# +# +# Kinetic energy values +# +# +# +# +# +# +# +# Relative transmission efficiency for the given kinetic energies +# +# +# +# +# +# +# +# +# Refers to the last transformation specifying the position of the electron analyser +# in the NXtransformations chain. +# +# +# +# +# Collection of axis-based translations and rotations to describe the location and +# geometry of the electron analyser as a component in the instrument. Conventions +# from the NXtransformations base class are used. In principle, the McStas +# coordinate system is used. The first transformation has to point either to +# another component of the system or "." (for pointing to the reference frame) to +# relate it relative to the experimental setup. Typically, the components of a +# system should all be related relative to each other and only one component +# should relate to the reference coordinate system. +# +# +# +# +# Describes the electron collection (spatial and momentum imaging) column +# +# +# +# +# Describes the energy dispersion section +# +# +# +# +# Describes the spin dispersion section +# +# +# +# +# Describes the electron detector +# +# +# +# +# Deflectors outside the main optics ensembles described by the subclasses +# +# +# +# +# Individual lenses outside the main optics ensembles described by the subclasses +# +# +# +# +# +# Any other resolution not explicitly named in this base class. +# +# +# diff --git a/contributed_definitions/nyaml/NXelectrostatic_kicker.yaml b/contributed_definitions/nyaml/NXelectrostatic_kicker.yaml new file mode 100644 index 0000000000..821e7c9324 --- /dev/null +++ b/contributed_definitions/nyaml/NXelectrostatic_kicker.yaml @@ -0,0 +1,105 @@ +category: base +doc: | + definition for a electrostatic kicker. +type: group +NXelectrostatic_kicker(NXobject): + description(NX_CHAR): + doc: | + extended description of the kicker. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + timing(NX_FLOAT): + unit: NX_TIME + exists: ['min', '0', 'max', '1'] + doc: | + kicker timing as defined by ``description`` attribute + \@description: + type: NX_CHAR + set_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on supply. + read_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from supply. + value: + unit: NX_CURRENT + set_voltage(NX_FLOAT): + unit: NX_VOLTAGE + exists: ['min', '0', 'max', '1'] + doc: | + volage set on supply. + read_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8bc323e93c7d175eab0c362d716d4ca617041ffaf2f420a386d92ab7cb75d595 +# +# +# +# +# definition for a electrostatic kicker. +# +# extended description of the kicker. +# +# +# define position of beamline element relative to production target +# +# +# kicker timing as defined by ``description`` attribute +# +# +# +# current set on supply. +# +# +# current read from supply. +# +# +# +# volage set on supply. +# +# +# voltage read from supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXellipsometry.yaml b/contributed_definitions/nyaml/NXellipsometry.yaml new file mode 100644 index 0000000000..9e6d9d0c10 --- /dev/null +++ b/contributed_definitions/nyaml/NXellipsometry.yaml @@ -0,0 +1,596 @@ +category: application +doc: | + Ellipsometry, complex systems, up to variable angle spectroscopy. + + Information on ellipsometry is provided, e.g. in: + + * H. Fujiwara, Spectroscopic ellipsometry: principles and applications, + John Wiley & Sons, 2007. + * R. M. A. Azzam and N. M. Bashara, Ellipsometry and Polarized Light, + North-Holland Publishing Company, 1977. + * H. G. Tompkins and E. A. Irene, Handbook of Ellipsometry, + William Andrew, 2005. + + Open access sources: + + * https://www.angstromadvanced.com/resource.asp + * https://pypolar.readthedocs.io/en/latest/ + + Review articles: + + * T. E. Jenkins, "Multiple-angle-of-incidence ellipsometry", + J. Phys. D: Appl. Phys. 32, R45 (1999), + https://doi.org/10.1088/0022-3727/32/9/201 + * D. E. Aspnes, "Spectroscopic ellipsometry - Past, present, and future", + Thin Solid Films 571, 334-344 (2014), + https://doi.org/10.1016/j.tsf.2014.03.056 + * R. M. A. Azzam, "Mueller-matrix ellipsometry: a review", + Proc. SPIE 3121, Polarization: Measurement, Analysis, and Remote Sensing, + (3 October 1997), + https://doi.org/10.1117/12.283870 + * E. A. Irene, "Applications of spectroscopic ellipsometry to microelectronics", + Thin Solid Films 233, 96-111 (1993), + https://doi.org/10.1016/0040-6090(93)90069-2 + * S. Zollner et al., "Spectroscopic ellipsometry from 10 to 700 K", + Adv. Opt. Techn., (2022), + https://doi.org/10.1515/aot-2022-0016 + +# N_p1: +# "Number of sample parameters scanned, if you varied any of the parameters +# such as temperature, pressure, or pH, the maximal length of the arrays +# specified by NXsample/environment_conditions/SENSOR/value if it exists." +# N_time: "Number of time points measured, the length of NXsample/time_points" +symbols: + doc: | + Variables used throughout the document, e.g. dimensions or parameters. + N_spectrum: | + Length of the spectrum array (e.g. wavelength or energy) of the measured + data. + N_sensors: | + Number of sensors used to measure parameters that influence the sample, + such as temperature or pressure. + N_measurements: | + Number of measurements (1st dimension of measured_data array). This is + equal to the number of parameters scanned. For example, if the experiment + was performed at three different temperatures and two different pressures + N_measurements = 2*3 = 6. + N_detection_angles: | + Number of detection angles of the beam reflected or scattered off the + sample. + N_incident_angles: | + Number of angles of incidence of the incident beam. + N_observables: | + Number of observables that are saved in a measurement. e.g. one for + intensity, reflectivity or transmittance, two for Psi and Delta etc. This + is equal to the second dimension of the data array 'measured_data' and the + number of column names. + N_time: | + Number of time points measured, the length of NXsample/time_points + +# 06/2022 +# A draft version of a NeXus application definition for ellipsometry. + +# The document has the following main elements: +# - Instrument used and is characteristics +# - Sample: Properties of the sample +# - Data: measured data, data errors +# - Derived parameters: e.g. extra parameters derived in the measurement software +type: group +NXellipsometry(NXopt): + + # symbols: + # doc: "Variables used throughout the document, e.g. dimensions and important parameters" + # N_wavelength: "Size of the energy or wavelength vector used, the length of + # NXinstrument/spectrometer/wavelength array" + # N_variables: "How many variables are saved in a measurement. e.g. 2 for Psi + # and Delta, 16 for Mueller matrix elements, 15 for normalized + # Mueller matrix, 3 for NCS, the length of NXsample/column_names" + # N_angles: "Number of incident angles used, the length of + # NXinstrument/angle_of_incidence array" + (NXentry): + doc: | + This is the application definition describing ellipsometry experiments. + + Such experiments may be as simple as identifying how a reflected + beam of light with a single wavelength changes its polarization state, + to a variable angle spectroscopic ellipsometry experiment. + + The application definition defines: + + * elements of the experimental instrument + * calibration information if available + * parameters used to tune the state of the sample + * sample description + definition: + doc: | + An application definition for ellipsometry. + \@version: + doc: | + Version number to identify which definition of this application + definition was used for this entry/data. + \@url: + doc: | + URL where to find further material (documentation, examples) relevant + to the application definition. + enumeration: [NXellipsometry] + experiment_description: + doc: | + An optional free-text description of the experiment. + + However, details of the experiment should be defined in the specific + fields of this application definition rather than in this experiment + description. + experiment_type: + doc: | + Specify the type of ellipsometry. + enumeration: [in situ spectroscopic ellipsometry, THz spectroscopic ellipsometry, infrared spectroscopic ellipsometry, ultraviolet spectroscopic ellipsometry, uv-vis spectroscopic ellipsometry, NIR-Vis-UV spectroscopic ellipsometry, imaging ellipsometry] + (NXinstrument): + doc: | + Properties of the ellipsometry equipment. + company: + exists: optional + doc: | + Name of the company which build the instrument. + construction_year(NX_DATE_TIME): + exists: optional + doc: | + ISO8601 date when the instrument was constructed. + UTC offset should be specified. + software(NXprocess): + program: + doc: | + Commercial or otherwise defined given name of the program that was + used to generate the result file(s) with measured data and metadata. + This program converts the measured signals to ellipsometry data. If + home written, one can provide the actual steps in the NOTE subfield + here. + ellipsometer_type: + doc: | + What type of ellipsometry was used? See Fujiwara Table 4.2. + enumeration: [rotating analyzer, rotating analyzer with analyzer compensator, rotating analyzer with polarizer compensator, rotating polarizer, rotating compensator on polarizer side, rotating compensator on analyzer side, modulator on polarizer side, modulator on analyzer side, dual compensator, phase modulation, imaging ellipsometry, null ellipsometry] + rotating_element_type: + doc: | + Define which element rotates, e.g. polarizer or analyzer. + enumeration: [polarizer (source side), analyzer (detector side), compensator (source side), compensator (detector side)] + (NXbeam_path): + light_source(NXsource): + doc: | + Specify the used light source. Multiple selection possible. + source_type: + enumeration: [arc lamp, halogen lamp, LED, other] + focussing_probes(NXlens_opt): + exists: optional + doc: | + If focussing probes (lenses) were used, please state if the data + were corrected for the window effects. + data_correction(NX_BOOLEAN): + doc: | + Were the recorded data corrected by the window effects of the + focussing probes (lenses)? + angular_spread(NX_NUMBER): + exists: recommended + unit: NX_ANGLE + doc: | + Specify the angular spread caused by the focussing probes. + (NXdetector): + doc: | + Properties of the detector used. Integration time is the count time + field, or the real time field. See their definition. + rotating_element(NXwaveplate): + exists: optional + doc: | + Properties of the rotating element defined in + 'instrument/rotating_element_type'. + revolutions(NX_NUMBER): + exists: optional + unit: NX_COUNT + doc: | + Define how many revolutions of the rotating element were averaged + for each measurement. If the number of revolutions was fixed to a + certain value use the field 'fixed_revolutions' instead. + fixed_revolutions(NX_NUMBER): + exists: optional + unit: NX_COUNT + doc: | + Define how many revolutions of the rotating element were taken + into account for each measurement (if number of revolutions was + fixed to a certain value, i.e. not averaged). + max_revolutions(NX_NUMBER): + exists: optional + unit: NX_COUNT + doc: | + Specify the maximum value of revolutions of the rotating element + for each measurement. + spectrometer(NXmonochromator): + exists: optional + doc: | + The spectroscope element of the ellipsometer before the detector, + but often integrated to form one closed unit. Information on the + dispersive element can be specified in the subfield GRATING. Note + that different gratings might be used for different wavelength + ranges. The dispersion of the grating for each wavelength range can + be stored in grating_dispersion. + (NXsample): + backside_roughness(NX_BOOLEAN): + doc: | + Was the backside of the sample roughened? Relevant for infrared + ellipsometry. + data_collection(NXprocess): + data_type: + doc: | + Select which type of data was recorded, for example Psi and Delta + (see: https://en.wikipedia.org/wiki/Ellipsometry#Data_acquisition). + It is possible to have multiple selections. Data types may also be + converted to each other, e.g. a Mueller matrix contains N,C,S data + as well. This selection defines how many columns (N_observables) are + stored in the data array. + enumeration: [Psi/Delta, tan(Psi)/cos(Delta), Mueller matrix, Jones matrix, N/C/S, raw data] + + # column_names: + # doc: | + # Please list in this array the column names used in your actual data. + # That is ['Psi', 'Delta'] or ['MM1', 'MM2', 'MM3', ..., 'MM16] for + # a full Mueller matrix, etc. + # dimensions: + # rank: 1 + # dim: [[1, N_observables]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e5c086ad7e50f420614c5465adc29a57a2b25cc1be09659435b3f1592c0f941a +# +# +# +# +# +# +# +# +# +# +# Variables used throughout the document, e.g. dimensions or parameters. +# +# +# +# Length of the spectrum array (e.g. wavelength or energy) of the measured +# data. +# +# +# +# +# Number of sensors used to measure parameters that influence the sample, +# such as temperature or pressure. +# +# +# +# +# Number of measurements (1st dimension of measured_data array). This is +# equal to the number of parameters scanned. For example, if the experiment +# was performed at three different temperatures and two different pressures +# N_measurements = 2*3 = 6. +# +# +# +# +# Number of detection angles of the beam reflected or scattered off the +# sample. +# +# +# +# +# Number of angles of incidence of the incident beam. +# +# +# +# +# Number of observables that are saved in a measurement. e.g. one for +# intensity, reflectivity or transmittance, two for Psi and Delta etc. This +# is equal to the second dimension of the data array 'measured_data' and the +# number of column names. +# +# +# +# +# Number of time points measured, the length of NXsample/time_points +# +# +# +# +# Ellipsometry, complex systems, up to variable angle spectroscopy. +# +# Information on ellipsometry is provided, e.g. in: +# +# * H. Fujiwara, Spectroscopic ellipsometry: principles and applications, +# John Wiley & Sons, 2007. +# * R. M. A. Azzam and N. M. Bashara, Ellipsometry and Polarized Light, +# North-Holland Publishing Company, 1977. +# * H. G. Tompkins and E. A. Irene, Handbook of Ellipsometry, +# William Andrew, 2005. +# +# Open access sources: +# +# * https://www.angstromadvanced.com/resource.asp +# * https://pypolar.readthedocs.io/en/latest/ +# +# Review articles: +# +# * T. E. Jenkins, "Multiple-angle-of-incidence ellipsometry", +# J. Phys. D: Appl. Phys. 32, R45 (1999), +# https://doi.org/10.1088/0022-3727/32/9/201 +# * D. E. Aspnes, "Spectroscopic ellipsometry - Past, present, and future", +# Thin Solid Films 571, 334-344 (2014), +# https://doi.org/10.1016/j.tsf.2014.03.056 +# * R. M. A. Azzam, "Mueller-matrix ellipsometry: a review", +# Proc. SPIE 3121, Polarization: Measurement, Analysis, and Remote Sensing, +# (3 October 1997), +# https://doi.org/10.1117/12.283870 +# * E. A. Irene, "Applications of spectroscopic ellipsometry to microelectronics", +# Thin Solid Films 233, 96-111 (1993), +# https://doi.org/10.1016/0040-6090(93)90069-2 +# * S. Zollner et al., "Spectroscopic ellipsometry from 10 to 700 K", +# Adv. Opt. Techn., (2022), +# https://doi.org/10.1515/aot-2022-0016 +# +# +# +# This is the application definition describing ellipsometry experiments. +# +# Such experiments may be as simple as identifying how a reflected +# beam of light with a single wavelength changes its polarization state, +# to a variable angle spectroscopic ellipsometry experiment. +# +# The application definition defines: +# +# * elements of the experimental instrument +# * calibration information if available +# * parameters used to tune the state of the sample +# * sample description +# +# +# +# An application definition for ellipsometry. +# +# +# +# Version number to identify which definition of this application +# definition was used for this entry/data. +# +# +# +# +# URL where to find further material (documentation, examples) relevant +# to the application definition. +# +# +# +# +# +# +# +# +# An optional free-text description of the experiment. +# +# However, details of the experiment should be defined in the specific +# fields of this application definition rather than in this experiment +# description. +# +# +# +# +# Specify the type of ellipsometry. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Properties of the ellipsometry equipment. +# +# +# +# Name of the company which build the instrument. +# +# +# +# +# ISO8601 date when the instrument was constructed. +# UTC offset should be specified. +# +# +# +# +# +# Commercial or otherwise defined given name of the program that was +# used to generate the result file(s) with measured data and metadata. +# This program converts the measured signals to ellipsometry data. If +# home written, one can provide the actual steps in the NOTE subfield +# here. +# +# +# +# +# +# What type of ellipsometry was used? See Fujiwara Table 4.2. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Define which element rotates, e.g. polarizer or analyzer. +# +# +# +# +# +# +# +# +# +# +# +# Specify the used light source. Multiple selection possible. +# +# +# +# +# +# +# +# +# +# +# +# +# If focussing probes (lenses) were used, please state if the data +# were corrected for the window effects. +# +# +# +# Were the recorded data corrected by the window effects of the +# focussing probes (lenses)? +# +# +# +# +# Specify the angular spread caused by the focussing probes. +# +# +# +# +# +# Properties of the detector used. Integration time is the count time +# field, or the real time field. See their definition. +# +# +# +# +# Properties of the rotating element defined in +# 'instrument/rotating_element_type'. +# +# +# +# Define how many revolutions of the rotating element were averaged +# for each measurement. If the number of revolutions was fixed to a +# certain value use the field 'fixed_revolutions' instead. +# +# +# +# +# Define how many revolutions of the rotating element were taken +# into account for each measurement (if number of revolutions was +# fixed to a certain value, i.e. not averaged). +# +# +# +# +# Specify the maximum value of revolutions of the rotating element +# for each measurement. +# +# +# +# +# +# The spectroscope element of the ellipsometer before the detector, +# but often integrated to form one closed unit. Information on the +# dispersive element can be specified in the subfield GRATING. Note +# that different gratings might be used for different wavelength +# ranges. The dispersion of the grating for each wavelength range can +# be stored in grating_dispersion. +# +# +# +# +# +# +# +# Was the backside of the sample roughened? Relevant for infrared +# ellipsometry. +# +# +# +# +# +# +# Select which type of data was recorded, for example Psi and Delta +# (see: https://en.wikipedia.org/wiki/Ellipsometry#Data_acquisition). +# It is possible to have multiple selections. Data types may also be +# converted to each other, e.g. a Mueller matrix contains N,C,S data +# as well. This selection defines how many columns (N_observables) are +# stored in the data array. +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXem.yaml b/contributed_definitions/nyaml/NXem.yaml new file mode 100644 index 0000000000..7ce0b9b4d9 --- /dev/null +++ b/contributed_definitions/nyaml/NXem.yaml @@ -0,0 +1,384 @@ +category: application +doc: | + Application definition for normalized representation of electron microscopy research. + + In line with the idea of NeXus application definitions, this schema is a + specialized version of NXem_base in that fields and groups are specifically + constrained. This has the effect that some quantities are required, so + that a research data management system (RDMS) can rely on the existence of + these pieces of information without demanding that RDMS to implement further + verification in its own source code or further harmonization or normalization + what each piece of information means conceptually. + + This application definition is thus an example of a general description + with which to normalize specific pieces of information and data collected + within electron microscopy research. + + This application definition is also a blueprint which shows how users + can build specific application definitions by reusing - instead of completely + reimplementing the wheel from scratch - em-specific base classes - and thus + represent electron-microscopy-specific content. + + The constraints of all these application definitions might be different + than for the here exemplified application definition NXem. + + Nevertheless, the key benefit remains: Many pieces of information are still + conceptually the same, named in the same way and found in the same place + in the hierarchy. This supports interoperability of electron microscopy data + and is advantageous compared to having everybody using own formatting and + conceptually not harmonized terms for describing their electron microscopy + research. + + For the detailed rationale and explanation of the concept behind the + NeXus electron microscopy class definitions please consult the preamble + of the NXem_base base class. +type: group +NXem(NXem_base): + # composing from NXem_base should work because NXem_base is composed from NXroot + # just list what is required or recommended or optional + # overwrite which known building blocks should get a different meaning + # and add specific fields for which there is not yet a base class + # this also strenghtens that people write base classes instead of + # highly customized and deeply overwriting application definitions + # other than for base classes the default existentiality constraint is + # exists: required therefore spelling this out is omitted for convenience + # a releasing of this default constraint is possible with writing exists: + \@NX_class: + \@file_time(NX_DATE_TIME): + \@file_name(NX_CHAR): + \@file_update_time(NX_DATE_TIME): + \@NeXus_version(NX_CHAR): + \@HDF5_Version(NX_CHAR): + \@h5py_version(NX_CHAR): + \@default(NX_CHAR): + (NXprogram): # understood by default as PROGRAM(NXprogram), i.e. program1, program2, ... + doc: | + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software which writes these NXprogram instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library `_ + which is used by the `NOMAD `_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + exists: [min, 0, max, infty] + # each NeXus file instance should have a default plot + # however as there are cases when this cannot be assured we cannot + # make the default required, one example is e.g. a NeXus instance + # where scientists just store conventions without a default plot + cs_profiling(NXcs_profiling): + doc: | + The configuration of the I/O writer software (e.g. `pynxtools `_) + which was used to generate this NeXus file instance. + command_line_call: + (NXentry): # means ENTRY(NXentry) + exists: [min, 1, max, infty] + \@version(NX_CHAR): + definition(NX_CHAR): + enumeration: [NXem] + experiment_identifier(NXidentifier): + exists: recommended + service(NX_CHAR): + identifier(NX_CHAR): + is_persistent(NX_BOOLEAN): + experiment_alias(NX_CHAR): + doc: | + Either an identifier or an alias that is human-friendly so that + scientist find that experiment again + experiment_description(NX_CHAR): + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + exists: recommended + (NXcite): + exists: [min, 0, max, infty] + (NXprogram): # no docstring overwritten means accepting it as it is defined in NXem_base + exists: [min, 1, max, infty] + program(NX_CHAR): + \@version(NX_CHAR): + # \@url: + (NXserialized): + exists: [min, 0, max, infty] + type(NX_CHAR): + path(NX_CHAR): + checksum(NX_CHAR): + algoritm(NX_CHAR): + (NXuser): + exists: [min, 1, max, infty] + name(NX_CHAR): + identifier(NXidentifier): + exists: recommended + service(NX_CHAR): + identifier(NX_CHAR): + is_persistent(NX_BOOLEAN): + # all other fields are optional but clearly defined in NXem_base + sample(NXsample): + method(NX_CHAR): + identifier(NXidentifier): + exists: recommended + service(NX_CHAR): + identifier(NX_CHAR): + is_persistent(NX_BOOLEAN): + parent_identifier(NXidentifier): + exists: recommended + service(NX_CHAR): + identifier(NX_CHAR): + is_persistent(NX_BOOLEAN): + preparation_date(NX_DATE_TIME): + name: + exists: recommended + atom_types(NX_CHAR): + # again all other fields are optional + (NXcoordinate_system_set): + exists: [min, 1, max, 1] + (NXcoordinate_system): + exists: [min, 1, max, infty] + origin(NX_CHAR): + alias(NX_CHAR): + type(NX_CHAR): + handedness(NX_CHAR): + x_direction(NX_CHAR): + y_direction(NX_CHAR): + z_direction(NX_CHAR): + # the description can be so lean because we do not need + # to overwrite here s.th. as everything is defined already + # in NXem_base and we also do not wish to overwrite the datatype + # of fields, we just say hey we need the above-mentioned fields + # in the way they are defined in the respective composed base classes + # and they have to be defined + # we also should not need to specify the value type like R, NX_POSINT + # because anyway within a group all field names have to be unique + # so there must not be any name conflict and this we can take to our + # advantage + measurement(NXem_msr): + exists: optional + em_lab(NXinstrument): + instrument_name(NX_CHAR): + exists: recommended + location(NX_CHAR): + exists: recommended + (NXfabrication): + vendor(NX_CHAR): + model(NX_CHAR): + (NXdetector): + exists: [min, 0, max, infty] + (NXfabrication): + vendor(NX_CHAR): + model(NX_CHAR): + (NXebeam_column): + electron_source(NXsource): + emitter_type(NX_CHAR): + probe(NX_CHAR): + (NXibeam_column): + exists: optional + ion_source(NXsource): + probe(NXion): + # voltage(NX_NUMBER): + # does not have to be written out unless that field should be required! + # like all other sub-graphs in the NXibeam_column base class and all + # the fields they can be used + (NXevent_data_em_set): + exists: [min, 0, max, 1] + # an instance must not have an NXevent_data_em_set but if it has one it must not be more than 1 ! + (NXevent_data_em): + exists: [min, 0, max, infty] + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + (NXimage_r_set): + exists: [min, 0, max, infty] + (NXprocess): + source(NXserialized): + exists: recommended + type(NX_CHAR): + path(NX_CHAR): + checksum(NX_CHAR): + algorithm(NX_CHAR): + detector_identifier(NX_CHAR): + stack(NXdata): + exists: optional + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_INT): + \@long_name(NX_CHAR): + title(NX_CHAR): + intensity(NX_NUMBER): + \@long_name(NX_CHAR): + axis_image_identifier(NX_INT): + \@long_name(NX_CHAR): + axis_y(NX_NUMBER): + \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + \@long_name(NX_CHAR): + (NXimage_c_set): + exists: [min, 0, max, infty] + (NXprocess): + source(NXserialized): + exists: recommended + type(NX_CHAR): + path(NX_CHAR): + checksum(NX_CHAR): + algorithm(NX_CHAR): + detector_identifier(NX_CHAR): + stack(NXdata): + exists: optional + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_CHAR): + \@long_name(NX_CHAR): + title: + real(NX_NUMBER): + \@long_name(NX_CHAR): + imag(NX_NUMBER): + \@long_name(NX_CHAR): + axis_image_identifier(NX_INT): + \@long_name(NX_CHAR): + axis_j(NX_NUMBER): + \@long_name(NX_CHAR): + axis_i(NX_NUMBER): + \@long_name(NX_CHAR): + hyperstack(NXdata): + exists: optional + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_CHAR): + \@long_name(NX_CHAR): + title: + real(NX_NUMBER): + \@long_name(NX_CHAR): + imag(NX_NUMBER): + \@long_name(NX_CHAR): + axis_image_identifier(NX_INT): + \@long_name(NX_CHAR): + axis_k(NX_NUMBER): + \@long_name(NX_CHAR): + axis_j(NX_NUMBER): + \@long_name(NX_CHAR): + axis_i(NX_NUMBER): + \@long_name(NX_CHAR): + (NXspectrum_set): + exists: [min, 0, max, infty] + (NXprocess): + source(NXserialized): + exists: recommended + type(NX_CHAR): + path(NX_CHAR): + checksum(NX_CHAR): + algorithm(NX_CHAR): + detector_identifier(NX_CHAR): + stack(NXdata): + exists: optional + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_INT): + \@long_name(NX_CHAR): + title(NX_CHAR): + intensity(NX_NUMBER): + \@long_name(NX_CHAR): + axis_y(NX_NUMBER): + \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + \@long_name(NX_CHAR): + axis_energy(NX_NUMBER): + \@long_name(NX_CHAR): + summary(NXdata): + exists: recommended + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_INT): + \@long_name(NX_CHAR): + title(NX_CHAR): + axis_energy(NX_NUMBER): + \@long_name(NX_CHAR): + em_lab(NXinstrument): + (NXebeam_column): + electron_source(NXsource): + voltage(NX_NUMBER): + (NXibeam_column): + exists: optional + ion_source(NXsource): + probe(NXion): + voltage(NX_NUMBER): + # why at all do we need to add here (NXinstrument) ? + # nyaml2nxdl could query the NXem_msr base class definition + # and check if an identifier named em_lab exists in this case + # it assumes it is em_lab(NXinstrument) and continues. + simulation(NXem_sim): + exists: optional + # remains to be discussed based on examples + # relevant research result post-processed for specific community methods + # but normalized in its representation ready to be consumed for a + # research data management system + (NXroi): + exists: [min, 0, max, infty] + doc: | + A region-of-interest analyzed either during or after the session. + For which specific processed data of the measured or simulated + data are available. + # as soon as one entry is here constrained further + # an RDM can be sure to find specific pieces of information in a + # specific way but then every user of this application definition + # is required to provide such information in this way! + se(NXem_img): + exists: optional + # remains to be discussed based on examples + bse(NXem_img): + exists: optional + # remains to be discussed based on examples + ebsd(NXem_ebsd): + exists: optional + # remains to be discussed based on examples + eds(NXem_eds): + exists: optional + # remains to be discussed based on examples + adf(NXem_adf): + exists: optional + # remains to be discussed based on examples + eels(NXem_eels): + exists: optional + # remains to be discussed based on examples + # cl(NXem_cl): + # exists: optional + correlation(NXem_correlation): + exists: optional + # remains to be discussed based on examples + +# finally an example how to map e.g. a simple flat schema to NXem: +# https://www.zenodo.org/record/6513745, source path mapped on (->) target path +# for all source paths /SEM/ is the src path prefix +# for all target paths /entry1/ is the trg path prefix +# ID -> experiment_identifier +# External/alias ID -> none +# User -> map on NXuser instances +# Date -> use start_time and end_time respectively +# Affiliation -> map on NXuser instances +# DOIs -> none, map on NXcite instances +# Temperature (of what?) -> be more specific and add as property of group of relevance +# Relative humidity (of what? likely lab like temperature) -> NXsample +# Environmental gas -> NXsample +# Operator -> map on NXuser with specific role +# Instrument ID -> map on best matching field from NXfabrication in em_lab +# Sample ID -> NXsample/identifier +# Parent sample ID -> NXsample/sample_history +# Any dataset to be linked with this experiment (too vague for the I in FAIR) -> none +# Environmental protection during sample processing -> NXsample +# Pre-treatment -> own appdef and connect to NXsample/sample_history +# Measurement position (the example is totally unclear) -> NXstage_lab, coordinate system etc. +# Detector IDs -> NXdetector/identifier +# Accelerating voltage -> electron_source/voltage +# Current -> much more possibilities electron_source and NXoptical_system_em +# Magnification -> use NXoptical_system_em +# Image width -> implicit in roi/NXdata instances +# Image size -> see image width +# Acquisition mode (too vague) -> map on more expressive fields of NXem_base +# Storage tilt (what is this) for tilt see NXstage_lab +# Measurement date (how is it different from Date? +# Comments -> any of the description fields, in both cases not fair +# the respective TEM group has pixel coordinates, which is all much cleaner +# described using NXem_conventions, NXcoordinate_system, etc... \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXem_adf.yaml b/contributed_definitions/nyaml/NXem_adf.yaml new file mode 100644 index 0000000000..b7011639e5 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_adf.yaml @@ -0,0 +1,28 @@ +category: base +doc: | + Base class method-specific for annular dark field imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXem_adf(NXem_method): + IMAGE_R_SET(NXimage_r_set): + half_angle_interval(NX_NUMBER): + doc: | + Annulus inner (first value) and outer (second value) half angle. + unit: NX_ANGLE + dim: (2,) + # all information about annular dark field images is composed from + # the NXimage_r_set_em base class diff --git a/contributed_definitions/nyaml/NXem_base.yaml b/contributed_definitions/nyaml/NXem_base.yaml new file mode 100644 index 0000000000..2de8081a8c --- /dev/null +++ b/contributed_definitions/nyaml/NXem_base.yaml @@ -0,0 +1,297 @@ +category: base +# template to be used for an application definition +doc: | + Blue-print of a generic appdef for electron microscopy research formulated as a deep base class. + + This base class combines a method-specific and technical-design-level base class + instance to provide a template for storing parameterized descriptions of + pieces of information collected when performing electron microscopy research. + + The base class here shows all possible branches without making any statements + as to which of these have to be used in an instance. Thereby, the base class + provides a template how to name and structure concepts in a hierarchy + to support finding information and reducing the need for renaming and + restructuring information for a research field where many scientists perform + very specific research but who all also share commonalities like usage of + controlled electron beams, a focus on studies of electron beam matter interaction + to explore physical mechanisms and phenomena, or the desire to characterize materials + using electron microscopy. +# flesh out the description of that to read the docs, because currently the +# description on the NeXus front-page is overwhelming +# considering what we learned from the diataxis workshop we write here a +# specification neither a how to nor a tutorial which explains all the context +# because we address here developers of software +type: group +NXem_base(NXroot): + (NXprogram): + doc: | + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software that writes these :ref:`NXprogram` instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library `_ + which is used by the `NOMAD `_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + # each NeXus file instance should have a default plot + # however as there are cases when this cannot be assured we cannot + # make the default required, one example is e.g. a NeXus instance + # where scientists just store conventions without a default plot + cs_profiling(NXcs_profiling): + doc: | + The configuration of the I/O writer software (e.g. `pynxtools `_) + which was used to generate this NeXus file instance. + (NXentry): # means ENTRY(NXentry) + \@version(NX_CHAR): + doc: | + An at least as strong as SHA256 hashvalue of the file + which specifies the application definition. + definition(NX_CHAR): + doc: | + NeXus NXDL schema to which this file conforms. + enumeration: [NXem] + experiment_identifier(NXidentifier): + doc: | + Ideally, a (globally) unique persistent identifier + for referring to this experiment. + + An experiment should be understood in that this can be an experiment + in reality or a computer simulation because also the latter is an + experiment (see the Cambridge Dictionary experiment: + *a test done in order to find out something, eg if an idea is correct*). + + The identifier is usually issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments/simulations to e.g. proposals. + experiment_description(NX_CHAR): + doc: | + Free-text description about the experiment. + + Users are strongly advised to parameterize their description of the + experiment by using the respective base classes instead of writing prose + into this field. + + The reason is that such free-text field is difficult to machine-interpret. + The motivation behind keeping this field for now is to learn through + the information entered in this field in how far the current base + classes are incomplete. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information included + when the microscope session started. If the application demands that time + codes in this section of the application definition should only be used + for specifying when the experiment was performed - and the exact + duration is not relevant - this start_time field should be used. + + Often though it is useful to specify a time interval via setting both + a start_time and an end_time because this enables software tools and + users to collect a more detailed bookkeeping of the experiment. + + The user should be aware that even with having both time instances specified, + it may not be possible to infer how long the experiment took or for how + long data were acquired. + + More detailed timing data over the course of the experiment have + to be collected to compute this. These computations can take + advantage of individual time stamps start_time and end_time + in :ref:`NXevent_data_em` instances. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC included when + the microscope session ended. See docstring of the start_time field + to see how the start_time and end_time should be used together. + (NXcite): + (NXprogram): + doc: | + The program and eventual software libraries used with which the + NeXus instance was created. For the NOMAD OASIS research data + management system e.g. pynxtools and eventually all modules + if desired. + # the above-description overwrites the default description of the NXprogram base class + # this is composed from the NXprogram base class + # program: + # \@version: + # \@url: + # NXnote and thumbnail dropped for the reason that these are + # arbitrary binary containers without any clear provenance. + (NXserialized): + doc: | + Possibility to store a collection of data artifacts + associated with the experiment. + # using NXserialized here instead of NXnote as the former is more specific + (NXuser): + doc: | + Contact information and eventually details of at least one person + who performed or was involved in the session. This can be the + principle investigator who performed this experiment or the student + who performed the simulation. + Adding multiple users if relevant is recommended. + name(NX_CHAR): + doc: | + Given (first) name and surname of the user. + affiliation(NX_CHAR): + doc: | + Name of the affiliation of the user at the point in time + when the experiment was performed. + address(NX_CHAR): + doc: | + Postal address of the affiliation. + email(NX_CHAR): + doc: | + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + identifier(NXidentifier): + doc: | + Service as another mean of identification of a user than by the name. + Examples could be details about an ORCID or social media account of + the user. + telephone_number(NX_CHAR): + doc: | + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + role(NX_CHAR): + doc: | + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope, student, postdoc, principle investigator, or guest + are common examples. + sample(NXsample): + # NEW ISSUE: inject the conclusion from the discussion with Andrea + # according to SAMPLE.yaml 0f8df14 2022/06/15 + # ID: -> maps to name + # name: -> short_title + # user: -> not matched right now + # citation: doi ->why relevant, should be solved by RDMS + doc: | + A description of the material characterized in the experiment. + Sample and specimen are threaded as de facto synonyms. + Samples can be real specimens or virtual (see method). + method(NX_CHAR): + doc: | + A qualifier whether the sample is a real one or a + virtual one (in a computer simulation) + enumeration: [experiment, simulation] + # MK:: declared_by_vendor I would rather expect this for a substance + # COMPONENT.yaml + # SUBSTANCE: + # QUANTIFY + identifier(NXidentifier): + doc: | + Ideally, (globally) unique persistent identifier which distinguishes + the specimen from all others and especially the predecessor/origin + from where the specimen was cut. + + This field must not be used for an alias! Instead, use name. + + In cases where multiple specimens were loaded into the microscope, + the identifier has to resolve the specific sample, whose results are + stored by this :ref:`NXentry` instance, because a single NXentry should be + used only for the characterization of a single specimen. + + Details about the specimen preparation should be + stored in resources referring to parent_identifier. + parent_identifier(NXidentifier): + doc: | + Identifier of the sample from which the sample was cut or the string + *None*. The purpose of this field is to support functionalities + for tracking sample provenance via a research data management system. + preparation_date(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. Ideally, this + matches the last timestamp that is mentioned in the digital resource + pointed to by parent_identifier. + + Knowing when the specimen was exposed to e.g. specific atmosphere is + especially required for environmentally sensitive material such as + hydrogen charged specimens or experiments including tracers with a + short half time. Additional time stamps prior to preparation_date + should better be placed in resources which describe but which do not pollute + the description here with prose. Resolving these connected pieces of information + is considered within the responsibility of the research data management + system. + name(NX_CHAR): + doc: | + An alias used to refer to the specimen to please readability for humans. + atom_types(NX_CHAR): + doc: | + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + `atom_types`. + + The purpose of the field is to offer research data management systems an + opportunity to parse the relevant elements without having to interpret + these from the resources pointed to by parent_identifier or walk through + eventually deeply nested groups in data instances. + # NEW ISSUE: use Andrea and MarkusK groups for describing the geometry of the sample + thickness(NX_NUMBER): + doc: | + (Measured) sample thickness. + + The information is recorded to qualify if the beam used was likely + able to shine through the specimen. For scanning electron microscopy, + in many cases the specimen is typically thicker than what is + illuminatable by the electron beam. + + In this case the value should be set to the actual thickness of + the specimen viewed for an illumination situation where the nominal + surface normal of the specimen is parallel to the optical axis. + unit: NX_LENGTH + # \@units: nm + # NEW ISSUE: error estimates of the thickness and origin, i.e. how the value was obtained would be useful + # NEW ISSUE: error model + # NEW ISSUE: the KIT/SCC SEM, TEM schemata further qualify samples whether they are conductive e/ibeam sensitive + # etc. The problem with this is that beam sensitivity is too vague but spatiotemporal electron dose integral dependent + # KIT/SCC distinguish further conductivity and magnetic properties. While the motivation is clear, making + # it thus simple is likely problematic when the data entered in such fields remaining qualitative. + # what are good or bad properties, it would make sense though to quantify these values + # this includes the description of eventual plasma cleaning steps, + # just knowing that a sample was plasma cleaned is insufficient, maybe it was not cleaned long enough + # if plasma cleaning is done outside the EM than its certainly history, if it happens inside the EM + # are the ibeam description capabilities not sufficient enough? + density(NX_NUMBER): + # NX_MASS_PER_VOLUME + doc: | + (Measured) density of the specimen. + + For multi-layered specimens this field should only be used to describe + the density of the excited volume. For scanning electron microscopy + the usage of this field is discouraged and instead an instance of an + :ref:`NXinteraction_vol_em` within individual :ref:`NXevent_data_em` + instances can provide a cleaner description of the relevant details + why one may wish to store the density of the specimen. + unit: NX_ANY + description: + doc: | + Discouraged free-text field to provide further detail although adding + parent_identifier and having a working research data management system + should provide this contextualization. + # (NXmonitor): + (NXdata): + (NXcoordinate_system_set): + # link to an instance of an NXinstrument but that is anyway specialized for EM + measurement(NXem_msr): + simulation(NXem_sim): + (NXroi): + doc: | + A region-of-interest analyzed either during or after the session + for which specific processed data generated from the measured or the + simulated data are available. + se(NXem_img): + bse(NXem_img): + ebsd(NXem_ebsd): + eds(NXem_eds): + adf(NXem_adf): + eels(NXem_eels): + correlation(NXem_correlation): + # cl(NXem_cl): diff --git a/contributed_definitions/nyaml/NXem_conventions.yaml b/contributed_definitions/nyaml/NXem_conventions.yaml new file mode 100644 index 0000000000..7835d9a654 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_conventions.yaml @@ -0,0 +1,296 @@ +category: base +# symbols: +doc: | + Conventions for rotations and coordinate systems to interpret crystal orientation + and other data and results collected with electron microscopy research. + + Documenting explicitly all used conventions and coordinate systems is + the decisive context whereby many results from electron microscopy are + at all interpretable. + +# This base class provides several sets of such assumptions and conventions. +# Further base classes should be defined when specific techniques and methods +# demand further specifications or have specialized demands. NXem_conventions_ebsd +# is an example for such method-specific base class to summarize key conventions +# for Electron Backscatter Diffraction (EBSD). + +# What is could be a best practice for application definition developers +# who would like to describe an electron microscopy case where multiple +# methods and/or detectors are used. In this case one should define a +# method-specific base class like the template NXem_conventions_ebsd. +# Even though this may come at a cost of some duplicated information where +# the same physical detector is used in different ways, i.e. the signal collect +# from the detector is interpreted in a different way. +# As in most cases established types of signal and thus detectors are used +# (secondary electron, backscattered electron, etc.) one could equally use +# just one NXem_conventions base class instance in an application definition +# and use detector_reference_frame as a template. For each method and detector +# one then creates one NXprocess group named detector_reference_frame1, +# detector_reference_frame2, detector_reference_frame3, and so on and so forth +# and adds inside that NXprocess and use the depends_on field. + +# What is considered best practice in an application definition with multiple +# NXentry instances? In this case each NXentry instance should have an own +# NXspecimen instance and thus the NXem_conventions instance should be place +# inside that NXentry. This enables to group multiple experiments on multiple +# samples together without setting a constraint that in all these instances +# the conventions have to be the same. + +# However, best practice is the conventions should be expressed explicitly +# and they should whenever possible be as simple as possible and as few +# as possible to support users with understanding the content of the application +# definition. +type: group +NXem_conventions(NXobject): + # mandatory information about used or + # assumed reference frame and rotation conventions + rotation_conventions(NXobject): + doc: | + Mathematical conventions and materials-science-specific conventions + required for interpreting every collection of orientation data. + rotation_handedness(NX_CHAR): + doc: | + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + enumeration: [undefined, counter_clockwise, clockwise] + rotation_convention(NX_CHAR): + doc: | + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, passive, active] + euler_angle_convention(NX_CHAR): + doc: | + How are Euler angles interpreted given that there are several + choices (e.g. ZXZ, XYZ, etc.) according to convention 4 of + DOI: 10.1088/0965-0393/23/8/083501. + The most frequently used convention is ZXZ which is based on + the work of H.-J. Bunge but other conventions are possible. + enumeration: [undefined, zxz] + axis_angle_convention(NX_CHAR): + doc: | + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, rotation_angle_on_interval_zero_to_pi] + sign_convention(NX_CHAR): + doc: | + Which sign convention is followed when converting orientations + between different parameterizations/representations according + to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, p_plus_one, p_minus_one] + processing_reference_frame(NXcoordinate_system): + doc: | + Details about eventually relevant named directions that may + give reasons for anisotropies. The classical example is cold-rolling + where one has to specify which directions (rolling, transverse, and normal) + align how with the direction of the base vectors of the sample_reference_frame. + type(NX_CHAR): + doc: | + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of coordinate system. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Location of the origin of the processing_reference_frame. + This specifies the location Xp = 0, Yp = 0, Zp = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. rolling direction. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the y-axis base vector, + e.g. transverse direction. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the z-axis base vector, + e.g. normal direction. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the processing_reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + sample_reference_frame(NXcoordinate_system): + doc: | + Details about the sample/specimen reference frame. + type(NX_CHAR): + doc: | + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + The reference frame for the sample surface reference is used for + identifying positions on a (virtual) image which is formed by + information collected from an electron beam scanning the + sample surface. We assume the configuration is inspected by + looking towards the sample surface from a position that is + located behind the detector. + Reference DOI: 10.1016/j.matchar.2016.04.008 + The sample surface reference frame has coordinates Xs, Ys, Zs. + In three dimensions these coordinates are not necessarily + located on the surface of the sample as there are multiple + faces/sides of the sample. Most frequently though the coordinate + system here is used to define the surface which the electron + beam scans. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Location of the origin of the sample surface reference frame. + This specifies the location Xs = 0, Ys = 0, Zs = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. longest edge. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the y-axis base vector, + e.g. long edge. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the z-axis base vector, + e.g. shortest edge. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + detector_reference_frameID(NXcoordinate_system): + doc: | + Details about the detector reference frame for a specific detector. + \@depends_on(NX_CHAR): + doc: | + Reference to the specifically named :ref:`NXdetector` instance + for which these conventions in this :ref:`NXprocess` group apply + (e.g. /entry1/instrument/detector1). + type(NX_CHAR): + doc: | + Type of coordinate system/reference frame used for + identifying positions in detector space Xd, Yd, Zd, + according to DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Where is the origin of the detector space reference + frame located. This is the location of Xd = 0, Yd = 0, Zd = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. longest edge as some landmark on the detector. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. long edge as some landmark on the detector. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. short edge as some landmark on the detector. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + # conventions specific for EBSD + (NXem_conventions_ebsd): \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml b/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml new file mode 100644 index 0000000000..1ec180e23f --- /dev/null +++ b/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml @@ -0,0 +1,125 @@ +category: base +# symbols: +doc: | + Base class for method-specific conventions EBSD. + + This base class is expected to be used with :ref:`NXem_conventions`. + + This is the main issue which currently is not in all cases documented + and thus limits the interoperability and value of collected EBSD data. + Not communicating EBSD data with such contextual pieces of information + and the use of file formats which do not store this information is the + key unsolved problem. +type: group +NXem_conventions_ebsd(NXem_conventions): + gnomonic_projection_reference_frame(NXcoordinate_system): + doc: | + Details about the gnomonic projection reference frame. + type(NX_CHAR): + doc: | + Type of coordinate system/reference frame used for identifying + positions in the gnomonic projection space Xg, Yg, Zg + according to DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of coordinate system. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Is the origin of the gnomonic coordinate system located + where we assume the location of the pattern centre. + This is the location Xg = 0, Yg = 0, Zg = 0 according to + reference DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, in_the_pattern_centre] + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" x-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" y-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" z-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + pattern_centre(NXprocess): + doc: | + Details about the definition of the pattern centre + as a special point in the gnomonic projection reference frame. + x_boundary_convention(NX_CHAR): + doc: | + From which border of the EBSP (in the detector reference frame) + is the pattern centre's x-position (PCx) measured? + Keywords assume the region-of-interest is defined by + a rectangle. We observe this rectangle and inspect the + direction of the outer-unit normals to the edges of + this rectangle. + enumeration: [undefined, top, right, bottom, left] + x_normalization_direction(NX_CHAR): + doc: | + In which direction are positive values for PCx measured from + the specified boundary. Keep in mind that the gnomonic space + is in virtually all cases embedded in the detector space. + Specifically, the XgYg plane is defined such that it is + embedded/laying inside the XdYd plane (of the detector + reference frame). + When the normalization direction is the same as e.g. the + detector x-axis direction, we state that we effectively + normalize in fractions of the width of the detector. + + The issue with terms like width and height is that these + degenerate if the detector region-of-interest is square-shaped. + This is why we should better avoid talking about width and height but + state how we would measure distances practically with a ruler and + how we then measure positive distances. + enumeration: [undefined, north, east, south, west] + y_boundary_convention(NX_CHAR): + doc: | + From which border of the EBSP (in the detector reference + frame) is the pattern centre's y-position (PCy) measured? + For further details inspect the help button of + xaxis_boundary_convention. + enumeration: [undefined, top, right, bottom, left] + y_normalization_direction(NX_CHAR): + doc: | + In which direction are positive values for PCy measured from + the specified boundary. + For further details inspect the help button of + xaxis_normalization_direction. + enumeration: [undefined, north, east, south, west] + + # distance_convention: + # doc: | + # How is the third of the three pattern centre parameter values, + # the (distance) parameter DD, normalized. Which convention + # is followed. We are aware that specifying one of the options here + # also implicitly comes with conventions for some of the parameter + # requested in this ELN. For now we would rather like to ask + # the users though to be specific also to learn how such an ELN + # will be used in practice. + # enumeration: [undefined, Bruker, JEOL, FEI, Oxford] diff --git a/contributed_definitions/nyaml/NXem_correlation.yaml b/contributed_definitions/nyaml/NXem_correlation.yaml new file mode 100644 index 0000000000..2acf65ec86 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_correlation.yaml @@ -0,0 +1,191 @@ +category: base +doc: | + Base class to combine different method-specific data in electron microscopy. + + This base class represent a template for documenting correlations + (spatial, temporal) between different method-specific results. +type: group +NXem_correlation(NXem_method): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): + indexing(NXprocess): + doc: | + Details about correlated or logically connected EBSD datasets. + + One important class of such correlated experiments are the so-called + (quasi) in-situ experiments. In this case the same or nearly the same ROI + gets analyzed via a repetitive sequence of thermomechanical treatment, + sample preparation, measurement, on-the-fly-indexing. Phenomena + investigated are recrystallization, strain accumulation, material damage. + Post-processing is required to correlate and reidentify eventual + microstructural features or local ROIs across several orientation maps. + + Another important class of correlated experiments are the so-called + serial-sectioning experiments. Here the same sample is measured + repetitively after polishing each time, to create a stack of + orientation data which can be reconstructed to a + three-dimensional volume ROI. + + Data can be correlated in time, position (spatial), or both (spatiotemporal). + + Spatial correlations between repetitively characterized regions-of-interests + are typically correlated using image registration and alignment algorithms. + For this typically so-called landmarks are used. These can be grains with + a very large size or specific shape, i.e. grains which are qualitatively + different enough to be used as a guide how images are shifted relative to + one another. Other commonly used landmarks are fiducial marks which are + milled into the specimen surface using focus-ion beam milling and/or various + types of indentation methods. + + As far as the same physical region-of-interest is just measured several times, + the additional issue of the depth increment is not a concern. However, correct + assumptions for the depth increment, amount of material removed along the milling + direction is relevant for accurate and precise three-dimensional (serial-sectioning) + correlations. For these studies it can be tricky though to assume or estimate + useful depth increments. Different strategies have been proposed like + calibrations, wedged-shaped landmarks and computer simulation assisted + assumption making. + + Despite the use of landmarks, there are many practical issues which make the + processing of correlations imprecise and inaccurate. Among these are drift + and shift of the specimen, instabilities of the holder, the beam, irrespective + of the source of the drift, charging effects, here specifically causing local + image distortions and rotations which may require special processing algorithms + to reduce such imprecisions. + + Time correlations face all of the above-mentioned issues surplus the challenge + that specific experimental protocols have to be used to ensure the material state + is observed at specific physical time. The example of quasi in-situ characterization + of crystal growth phenomena, a common topic in engineering or modern catalysis research + makes it necessary to consider that e.g. the target value for the desired annealing + temperature is not just gauged based on macroscopic arguments but considers + that transient effects take place. Heating or quenching a sample might thus might + not have been executed under conditions in the interaction volume as they are + documented and/or assumed. + + These issue cause that correlations have an error margin as to how accurately + respective datasets were not only just synced based on the geometry of the + region-of-interests and the time markers but also to asssure which physical + conditions the specimen experienced over the course of the measurements. + + The fourth example of the em_om reference implementation explores the use of the + correlation group with a serial-sectioning datasets that was collected by the + classical Inconel 100 dataset collected by M. D. Uchic and colleagues + (M. Groeber M, Haley BK, Uchic MD, Dimiduk DM, Ghosh S 3d reconstruction and + characterization of polycrystalline microstructures using a fib-sem system data set. + Mater Charac 2006, 57 259–273. 10.1016/j.matchar.2006.01.019M). + + This dataset was specifically relevant in driving forward the implementation + of the DREAM.3D software. DREAM.3D is an open-source software project for + post-processing and reconstructing, i.e. correlating sets of orientation + microscopy data foremost spatially. One focus of the software is the + (post-)processing of EBSD datasets. Another cutting edge tool with similar + scope but a commercial solution by Bruker is QUBE which was developed by + P. Konijnenberg and coworkers. + + Conceptually, software like DREAM.3D supports users with creating linear + workflows of post-processing tasks. Workflows can be instructed via the + graphical user interface or via so-called pipeline processing via command line + calls. DREAM.3D is especially useful because its internal system documents all + input, output, and parameter of the processing steps. This makes DREAM.3D a + good candidate to interface with tools like em_om parser. Specifically, DREAM.3D + documents numerical results via a customized HDF5 file format called DREAM3D. + Workflow steps and settings are stored as nested dictionaries in JSON syntax + inside a supplementary JSON file or alongside the data in the DREAM3D file. + DREAM.3D has a few hundred algorithms implemented. These are called filters + in DREAM.3D terminology. + + Users configure a workflow which instructs DREAM.3D to send the data through + a chain of predefined and configured filters. Given that for each analysis + the filter is documented via its version tags surplus its parameter and setting + via a controlled vocabulary, interpreting the content of a DREAM3D HDF5 file + is possible in an automated manner using a parser. This makes DREAM.3D analyses + repeatable and self-descriptive. A key limitation though is that most frequently + the initial set of input data come from commercial files like ANG. + This missing link between the provenance of these input files, their associated + creation as electron microscope session, is also what NXem_ebsd solves. + + Nevertheless, as this can be solved with e.g. NXem_ebsd we are convinced that + the DREAM.3D and the em_om parser can work productively together to realize + RDMS-agnostic parsing of serial-section analyses. + + The internal documentation of the DREAM.3D workflow also simplifies the + provenance tracking represented by an instance of NXem_ebsd as not every + intermediate results has to be stored. Therefore, the fourth example + focuses on the key result obtained from DREAM.3D - the reconstructed + and aligned three-dimensional orientation map. + + Usually, this result is the starting point for further post-processing + and characterization of structural features. As here orientation microscopy + is insofar scale invariant using DREAM.3D, NXem_ebsd, and em_om should + be useful for different characterization methods, such as EBSD, Transmission + Kikuchi Diffraction (TKD), Automated Crystal Orientation Mapping (ACOM), + Nanobeam Electron Diffraction (using commercial systems like NanoMegas ASTAR) + or open-source implementations of these techniques (such as via pyxem/orix). + + The result of orientation microscopy methods are maps of local orientation + and thermodynamic phase (crystal structure) pieces of information. Virtually + all post-processing of such results for structural features includes again + a workflow of steps which are covered though by the NXms partner application + definition. The respective source of the data in an instance of NXms can + again be a link or reference to an instance of NXem_ebsd to complete the + chain of provenance. + (NXcrystal_structure): + roi(NXdata): + descriptor: + doc: | + Descriptor representing the image contrast. + # \@signal: # data + # \@axes: # [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + # \@signal: + # \@axes: + # \@AXISNAME_indices: + # \@long_name: + title: + doc: | + Title of the default plot. + data(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Descriptor values displaying the ROI. + dim: (n_z, n_y, n_x) + # n_0 slowest 3, n_1 slow 2, n_2 fast 1, rgb triplet is fastest 0 + # in axes fast to fastest + # while for _indices fastest to fast + \@long_name: + doc: | + Descriptor values. + axis_z(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the z-axis. + dim: (n_z,) + \@long_name: + doc: | + Label for the z axis + axis_y(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the y-axis. + dim: (n_y,) + \@long_name: + doc: | + Label for the y axis + axis_x(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the x-axis. + dim: (n_x,) + \@long_name: + doc: | + Label for the x axis + # NEW ISSUE: implement support for filters eventually many of them + # NEW ISSUE: for now only show that data from DREAM3D can be loaded. + # NEW ISSUE: how to handle landmarks + # NEW ISSUE: again an entire set of workflows such as rigid or non-rigid + # image registration etc. + # sequence_index(N0): diff --git a/contributed_definitions/nyaml/NXem_ebsd.yaml b/contributed_definitions/nyaml/NXem_ebsd.yaml new file mode 100644 index 0000000000..7811a8845d --- /dev/null +++ b/contributed_definitions/nyaml/NXem_ebsd.yaml @@ -0,0 +1,415 @@ +category: base +doc: | + Base class method-specific for Electron Backscatter Diffraction (EBSD). + + The general procedure of an EBSD experiment is as follows: + Users load the specimen, collect first a coarse image of the surface. + Next, they set an approximate value for the calibrated working distance and + tilt the stage to set the desired diffraction conditions. + + Users then typically configure the microscope for collecting higher quality data + and push in the EBSD detector. Subsequently, they fine tune the illumination + and aberration corrector settings and select one or multiple ROIs for + the microscope to machine off automatically. They configure on-the-fly + indexing parameter and start the measurement queue. + + Nowadays, this is in most cases an automated process. The pattern + collection runs during the allocated microscope session until the + queue finishes or gets interrupted by errors or the next user terminates + sessions which run over time. + + Kikuchi pattern surplus eventually multi-modal detector signals are + collected and usually indexed on-the-fly. Patterns may be stored or not + so one should not assume that raw data are always stored. + + Results are stored in files, which afterwards are typically copied + automatically or manual for archival purposes to certain storage + locations or further consumption. The result of such an EBSD + measurement/experiment is a set of usually proprietary or open files + from technology partners. + + This :ref:`NXem_ebsd` base class is a proposal how to represent method-specific + data, metadata, and connections between these for the research field of + electron microscopy. + + More specifically, exemplified here for electron backscatter diffraction (EBSD) + we show how NeXus can be used to solve two key documentation issues so far + missing in the field of EBSD. + + Firstly, an instance of NXem_ebsd (such as a NeXus/HDF5 file which is formatted + according to NXem_ebsd) stores the connection between the microscope session and + the key datasets which are considered typically results of the various processing + steps involved when working with EBSD data. + + Different groups in NXem_ebsd make connections to data artifacts which were collected + when working with electron microscopes via the NXem application definition. + Using a file which stores information according to the NXem application definition + has the benefit that it connects the sample, references to the sample processing, + the user operating the microscope, details about the microscope session, + and details about the acquisition and eventual indexing of Kikuchi pattern, + associated overview images, like secondary electron or backscattered electron + images of the region-of-interest probed and many more pieces of information. + + Secondly, NXem_ebsd connects and stores the conventions and reference frames + which were used and which are the key to a correct mathematical interpretation + of every EBSD result. Otherwise, results would be ripped out of their context, + as it is the current situation with many traditional studies where EBSD data + were indexed on-the-fly and shared with the community only via sharing + the strongly processed results file in some technology-partner-specific file + format but without communicating all conventions or relying on the assumptions + that colleagues likely know these conventions even though multiple definitions + are possible. + + NXem_ebsd covers experiments with one-, two-dimensional, and so-called three- + dimensional EBSD datasets. The third dimension is either time (in the case of + quasi in-situ experiments) or space (in the case of serial-sectioning) methods + where a combination of mechanical or ion milling is used repetitively to measure + the same region-of-interest at different depth increments. Material removal + can be achieved with electron or ion polishing, using manual + steps or using automated equipment like a robot system. + + Three-dimensional experiments require to follow a sequence of specimen, surface + preparation, and data collection steps. By nature these methods are destructive + in that they either require the removal of the previously measured material region + or that the sample surface can degrade due to e.g. contamination or other + electron-matter interaction. + + For three-dimensional EBSD, multiple two-dimensional EBSD orientation mappings are + combined into one reconstructed stack. That is serial-sectioning is mainly a + computational workflow. Users collect data for each serial sectioning step + via an experiment. This assures that data for associated microscope sessions + and steps of data processing stay connected and contextualized. + + Eventual tomography methods also use such a workflow because first diffraction + images are collected (e.g. with X-ray) and then these imagres are indexed and + computed into a 3D orientation mapping. The here proposed NXem_ebsd application + definition contains conceptual ideas how this splitting between measurement and + post-processing can be granularized also for such X-ray-based techniques, whether + it be 3DXRD or HEDM. +symbols: + n_op: | + Number of arguments per orientation for given parameterization. + n_sc: | + Number of scan points. + n_z: | + Number of pixel along the slowest changing dimension for a rediscretized, + i.e. standardized default plot orientation mapping. + n_y: | + Number of pixel along slow changing dimension for a rediscretized i.e. + standardized default plot orientation mapping. + n_x: | + Number of pixel along fast changing dimension for a rediscretized i.e. + standardized default plot orientation mapping. +type: group +NXem_ebsd(NXem_method): + conventions(NXem_conventions): + # either we have simulated data or we have a set of measured data + # in every case data are Kikuchi diffraction pattern and their metadata + measurement(NXprocess): + doc: | + This group documents relevant details about the conditions and the tools + used for measuring a stack of Kikuchi diffraction pattern with an + electron microscope. + + The most frequently collected EBSD data are captured for rectangular + regions-of-interested which are sampled with regular square or + hexagon-shaped pixels. + time(NX_NUMBER): + doc: | + Physical time since the beginning of a timestamp that is required to be + same for all experiments in the set. The purpose of this marker is + to identify how all experiments in the set have have to be arranged + sequentially based on the time elapsed. + The time is relevant to sort e.g. experiments of consecutive quasi + in-situ experiments where a measurement was e.g. taken after 0 minutes + of annealing, 30 minutes, 6 hours, or 24 hours of annealing. + unit: NX_TIME + \@depends_on(NX_CHAR): + doc: | + Timestamp relative to which time was counted to aid + converting between time and timestamp. + # (NXtransformations): + # doc: | + # Transformation which details where the region-of-interest described under + # indexing is located in absolute coordinates and rotation with respect + # to which coordinate system. + # pattern_available(NX_BOOLEAN): + # doc: | + # True if pattern were stored and are retrieveable via depends_on or source. + \@depends_on(NX_CHAR): + doc: | + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXdata` where the pattern are stored. + source(NXserialized): + doc: | + Reference (e.g. path and filename) to an existent data artifact which + stores either the measured pattern or input (already processed EBSD data). + simulation(NXprocess): + doc: | + This group documents relevant details about the conditions and the tools + used for simulating a stack of Kikuchi diffraction pattern with some + physical model. + + This group should not be confused with a group named simulation that + is however an instance of NXem_sim. Instead, the simulation group here + should be used if (e.g. instead of a measurement) a stack of pattern + were simulated that one wishes to use for indexing patterns. + + In many practical cases where pattern are analyzed on-the-fly and dictionary + indexing strategies are used, so-called master pattern(s) are used to compare + measured or simulated pattern with the master pattern. In this case, + master pattern are the result of a computer simulation and thus should + be stored using an own properly documented entry within a simulation + group as an instance of :ref:`NXem_sim`. + \@depends_on(NX_CHAR): + doc: | + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXimage_r_set_diff` + where the simulated pattern are stored. + source(NXserialized): + doc: | + Reference (e.g. path and filename) to an existent digital resource which + stores either the pattern or input (already processed EBSD data) + which is now processed further as described by this NXem_ebsd instance. + calibration(NXprocess): + doc: | + The EBSD system, including components like the electron gun, pole-piece, + stage tilting, EBSD detector, and the gnomonic projection have to be + calibrated to achieve reliable indexing results. + + Specifically, the gnomonic projection has to be calibrated. + Typically, silicon or quartz crystals are used for this purpose. + + Considering a system is well-calibrated, it is much more frequently the + case in practice that users assume the system is calibrated (and thus usable) + vs. they perform the calibration of the EBSD system. + + In the first case, the user assumes that the principle geometry of the + hardware components and the settings in the control and EBSD pattern + acquisition software has been calibrated. Consequently, users pick from + an existent library of phase candidates, i.e. + :ref:`NXcrystal_structure` instances. Examples are + reflector models as stored in CRY files (HKL/Channel 5/Flamenco). + + In the second case, users calibrate the system during the session + using standards (silicon, quartz, or other common specimens). + There is usually one person in each lab responsible for doing such + calibrations. Often this person or technician is also in charge of + configuring the graphical user interface and software with which most + users control and perform their analyses. + + For EBSD this has key implications: Taking TSL OIM/EDAX as an example, + the conventions how orientations are stored is affected by how the + reference frames are configured and this setup is made at the level + of the GUI software. + + Unfortunately, these pieces of information are not necessarily stored + in the results files. In effect, key conventions become disconnected + from the data so it remains the users' obligation to remember these + settings or write these down in a lab notebook. Otherwise, these metadata + get lost. All these issues are a motivation and problem which + :ref:`NXem_ebsd` solves in that all conventions can be specified explicitly. + \@depends_on(NX_CHAR): + doc: | + If available and it is stored in an instance of an application definition + this field gives the path of an :ref:`NXem_msr` where the calibration is + stored. + source(NXserialized): + doc: | + Reference to a digital resource where the calibration is stored. + indexing(NXprocess): + doc: | + Indexing is a data processing step performed either after or while + (on-the-fly) the beam scans the specimen. The resulting method is also + known as orientation imaging microscopy (OIM). + + Different algorithms can be used to index EBSD pattern. Common to them + is the computational step where simulated reference pattern are compared + with measured or simulated patterns. These latter patterns are referred + to via the measurement or simulation groups of this base class. + + Quality descriptors are defined based on which an indexing algorithm + yields a quantitative measure of how similar measured and reference + pattern are, and thus if no, one, or multiple so-called solutions + were found. + + Assumed or simulated pattern are simulated using kinematic or dynamical + theory of electron diffraction delivering master pattern. + + The Hough transform is essentially a discretized Radon transform (for details see `M. van Ginkel et al. `_). + Recently, dictionary-based indexing methods are increasingly becoming used + partly driven by the interest to use artificial intelligence algorithms. + source(NXserialized): + doc: | + This group enables to establish a logical connection between previous + processing steps or on-the-fly-performed indexing of the EBSD map. + Typically these processing steps are performed with commercial software. + Therefore, in many cases a results file from this indexing is often + all that is communicated and saved. These are typically files in a format + specific to the instrument and its configuration. + + Typical file formats are CPR/CRC, ANG, OSC, HDF5, H5EBSD, EDAXH5. + method(NX_CHAR): + doc: | + Principal algorithm used for indexing. + enumeration: [undefined, hough_transform, dictionary, radon_transform, other] + background_correction(NXprocess): + doc: | + Details about the background correction applied to each Kikuchi pattern. + binning(NXprocess): + doc: | + Binning i.e. downsampling of the pattern. + parameter(NXprocess): + doc: | + Specific parameter relevant only for certain algorithms used. + phaseID(NXcrystal_structure): + doc: | + Details for each phase used as a model with which the patterns were + indexed. Instances of :ref:`NXcrystal_structure` in this group must + have the group name prefix phase. The identifier in the name is an + integer. We start counting from 1 because the value 0 is reserved for + the special phase that is the null-model, i.e. the null phase, notIndexed. + status(NX_UINT): + doc: | + Which return value did the indexing algorithm yield for each scan point. + Practically useful is to use an uint8 mask. + + * 0 - Not analyzed + * 1 - Too high angular deviation + * 2 - No solution + * 100 - Success + * 255 - Unexpected errors + unit: NX_UNITLESS + dim: (n_sc,) + n_phases_per_scan_point(NX_INT): + doc: | + How many phases i.e. crystal structure models were used to index each + scan point if any? Let's assume an example to explain how this field + should be used: In the simplest case users collected one pattern for + each scan point and have indexed using one phase, i.e. one instance + of an NXem_ebsd_crystal_structure_model. + + In another example users may have skipped some scan points (not indexed) + them at all) and/or used differing numbers of phases for different scan + points. + + The cumulated of this array decodes how phase_identifier and phase_matching + arrays have to be interpreted. In the simplest case (one pattern per scan + point, and all scan points indexed using that same single phase model), + phase_identifier has as many entries as scan points + and phase_matching has also as many entries as scan points. + unit: NX_UNITLESS + dim: (n_sc,) + phase_identifier(NX_INT): + doc: | + The array n_phases_per_scan_point details how the phase_identifier + and the phase_matching arrays have to be interpreted. + + For the example with a single phase phase_identifier has trivial + values either 0 (no solution) or 1 (solution matching + sufficiently significant with the model for phase 1). + + When there are multiple phases, it is possible (although not frequently + needed) that a pattern matches eventually (not equally well) sufficiently + significant with multiple pattern. This can especially happen in cases of + pseudosymmetry and more frequently with an improperly calibrated system + or false or inaccurate phase models e.g. (ferrite, austenite). + Having such field is especially relevant for recent machine learning + or dictionary based indexing schemes because in combination with + phase_matching these fields communicate the results in a model-agnostic + way. + + Depending on the n_phases_per_scan_point value phase_identifier and + phase_matching arrays represent a collection of concatenated tuples, + which are organized in sequence: The solutions for the 0-th scan point, + the 1-th scan point, the n_sc - 1 th scan point and omitting tuples + for those scan points with no phases according to n_phases_per_scan_point + unit: NX_UNITLESS + dim: (i,) + phase_matching(NX_INT): + doc: | + One-dimensional array, pattern by pattern labelling the solutions found. + The array n_phases_per_scan_point has to be specified because it details + how the phase_identifier and the phase_matching arrays have to be interpreted. + See documentation of phase_identifier for further details. + unit: NX_UNITLESS + dim: (i,) + phase_matching_descriptor(NX_CHAR): + doc: | + Phase_matching is a descriptor for how well the solution matches or not. + Examples can be confidence_index, mean_angular_deviation, some AI-based + matching probability (other), i.e. the details are implementation-specific. + enumeration: [undefined, confidence_index, mean_angular_deviation, other] + rotation_set(NXrotation_set): + scan_point_positions(NX_NUMBER): + # we make this only required as people may not yet be so happy with + # having to walk a graph from measurement -> path -> NXevent_data_em + # -> em_lab/ebeam_deflector to retrieve the actual scan positions + # although this would be cleaner, also scan_point_positions could be + # an instance of NXcg_point_set with a depends_on pointing + # to sample_reference_frame + doc: | + Calibrated center positions of each scan point + in the sample surface reference system. + # px is no one of the following two calibrated i) is not px*stepsize or ii) is not px*stepsize + offset + unit: NX_LENGTH + dim: (n_sc, 2) + indexing_rate(NX_NUMBER): + doc: | + Fraction of successfully indexed pattern with a phase + not the null-phase vs the number_of_scan_points. + unit: NX_DIMENSIONLESS + number_of_scan_points(NX_UINT): + doc: | + Number of scan points in the original mapping. + unit: NX_UNITLESS + odf(NXms_odf_set): + pf(NXms_pf_set): + microstructureID(NXms_recon): + # overview over the entire map, rediscretized on a tight aabb + roi(NXdata): + doc: | + An overview of the entire ROI. + descriptor: + doc: | + Descriptor representing the image contrast. + # taking two examples (CTF and H5OINA choked completely of possibility to find s.th. conceptually common to plot + enumeration: [normalized_band_contrast, normalized_confidence_index, normalized_mean_angular_deviation] + # \@signal: # data + # \@axes: # [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + # \@signal: + # \@axes: + # \@AXISNAME_indices: + # \@long_name: + title(NX_CHAR): + doc: | + Title of the default plot. + data(NX_NUMBER): + doc: | + Descriptor values displaying the ROI. + unit: NX_UNITLESS + dim: (n_y, n_x) + # n_0 slow 2, n_1 fast 1, rgb triplet is fastest 0 + # in axes fast to fastest + # while for _indices fastest to fast + \@long_name(NX_CHAR): + doc: | + Descriptor values. + axis_y(NX_NUMBER): + doc: | + Calibrated coordinate along the y-axis. + unit: NX_LENGTH + dim: (n_y,) + \@long_name(NX_CHAR): + doc: | + Label for the y axis + axis_x(NX_NUMBER): + doc: | + Calibrated coordinate along the x-axis. + unit: NX_LENGTH + dim: (n_x,) + \@long_name(NX_CHAR): + doc: | + Label for the x axis diff --git a/contributed_definitions/nyaml/NXem_eds.yaml b/contributed_definitions/nyaml/NXem_eds.yaml new file mode 100644 index 0000000000..9a5a97fcd0 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_eds.yaml @@ -0,0 +1,80 @@ +category: base +doc: | + Base class method-specific for energy-dispersive X-ray spectroscopy (EDS/EDX). + + `IUPAC instead of Siegbahn notation `_ should be used. + +# NEW ISSUE: use computational geometry to offer arbitrary scan pattern +# NEW ISSUE: make the binning flexible per scan point +symbols: + # n_p: Number of scan points + n_y: | + Number of pixel along the y direction, the slow direction + n_x: | + Number of pixel along the x direction, the fast direction + n_photon_energy: | + Number of X-ray photon energy (bins), the fastest direction. + n_elements: | + Number of identified elements + n_peaks: | + Number of peaks detected +type: group +NXem_eds(NXem_method): + # NXprocess is composed from NXem_method base class + # SPECTRUM_SET(NXspectrum_set) is composed from NXem_method base class + # for post-processing of/with the above-defined data entries + # including feedback from Christoph Pauly (from MX Uni Saarland, NFDI-MatWerk), + # Sabine Bergmann and Sebastian Brückner (both from FAIRmat, IKZ), + # and Adrien Teutrie, Cecile Hebert (EPFL) + indexing(NXprocess): + doc: | + Details about computational steps how peaks were indexed as elements. + (NXprogram): + doc: | + The program with which the indexing was performed. + PEAK(NXpeak): + doc: | + Name and location of each X-ray line which was indexed as a known ion. + For each ion, an NXion instance should be created which specifies + the origin of the signal. For each ion also the relevant IUPAC notation + X-ray lines should be specified. + (NXion): + energy_range(NX_NUMBER): + doc: | + Associated lower :math:`[e_{min}, e_{max}]` bounds of the + energy which is assumed associated with this peak. + unit: NX_ENERGY + dim: (2,) + energy(NX_NUMBER): + doc: | + Theoretical energy of the line according to IUPAC. + unit: NX_ENERGY + iupac_line_names(NX_CHAR): + doc: | + IUPAC notation identifier of the line which the peak represents. + + This can be a list of IUPAC notations for (the seldom) case that + multiple lines are grouped with the same peak. + dim: (i,) + element_names(NX_CHAR): + doc: | + List of the names of identified elements. + dim: (n_elements,) + IMAGE_R_SET(NXimage_r_set): + doc: | + Individual element-specific EDS/EDX/EDXS/SXES mapping + + A composition map is an image whose intensities for each pixel are the + accumulated X-ray quanta *under the curve(s)* of a set of peaks. + + These element-specific EDS maps are NXimage_r_set instances + and need to be named with the name of the element from the + element_names field. + (NXprocess): + peaks(NX_CHAR): + doc: | + A list of NXpeak instance names whose X-ray quanta + where accumulated for each pixel which yields an element-specific + EDS map. + dim: (n_peaks,) + # everything else is composed from NXimage_r_set diff --git a/contributed_definitions/nyaml/NXem_eels.yaml b/contributed_definitions/nyaml/NXem_eels.yaml new file mode 100644 index 0000000000..4e5c69fe4a --- /dev/null +++ b/contributed_definitions/nyaml/NXem_eels.yaml @@ -0,0 +1,39 @@ +category: base +doc: | + Base class method-specific for Electron Energy Loss Spectroscopy (EELS). +symbols: + n_energy_loss: | + Number of electron energy loss bins. +type: group +NXem_eels(NXem_method): + # NXem_method can offers to keep a SPECTRUM_SET + # NXem_method also has an NXprocess which in this base class can be + # specialized to include EELS-specific post-processing + SPECTRUM_SET(NXspectrum_set): + doc: | + NXspectrum_set_em specialized for EELS. + stack(NXdata): + # \@signal: data_counts + # \@axes: [axis_y, axis_x, axis_energy_loss] + # \@energy_loss_indices: 2 + # \@axis_x_indices: 1 + # \@axis_y_indices: 0 + axis_energy_loss(NX_NUMBER): + unit: NX_ENERGY + dim: (n_energy_loss,) + \@long_name(NX_CHAR): + doc: | + Energy loss. + summary(NXdata): + # \@signal: data_counts + # \@axes: [axis_energy_loss] + # \@energy_loss_indices: 0 + axis_energy_loss(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy loss. + dim: (n_energy_loss,) + \@long_name(NX_CHAR): + doc: | + Energy loss. + # collection if needed can be composed from NXspectrum_set diff --git a/contributed_definitions/nyaml/NXem_img.yaml b/contributed_definitions/nyaml/NXem_img.yaml new file mode 100644 index 0000000000..8c257d121a --- /dev/null +++ b/contributed_definitions/nyaml/NXem_img.yaml @@ -0,0 +1,25 @@ +category: base +doc: | + Base class for method-specific generic imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXem_img(NXem_method): + imaging_mode(NX_CHAR): + doc: | + Which imaging mode was used? + enumeration: [secondary_electron, backscattered_electron] + IMAGE_R_SET(NXimage_r_set): diff --git a/contributed_definitions/nyaml/NXem_method.yaml b/contributed_definitions/nyaml/NXem_method.yaml new file mode 100644 index 0000000000..afe91de973 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_method.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Base class to describe specific analysis methods in electron microscopy. + + This base class represent a template how specialized, deep, and method-specific + base classes can be defined with which an (NXem) application + definition gets equipped with specific groups to document method-specific + processing steps and report analyzed quantities. + + The template base class name :ref:`NXem_method` needs to be changed for each + method e.g. :ref:`NXem_adf`, :ref:`NXem_ebsd`, :ref:`NXem_eels`, :ref:`NXem_eds`. +# :ref:`NXem_se`, :ref:`NXem_bse`. +type: group +NXem_method(NXobject): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): + IMAGE_R_SET(NXimage_r_set): + IMAGE_C_SET(NXimage_c_set): + SPECTRUM_SET(NXspectrum_set): diff --git a/contributed_definitions/nyaml/NXem_msr.yaml b/contributed_definitions/nyaml/NXem_msr.yaml new file mode 100644 index 0000000000..16c349ca58 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_msr.yaml @@ -0,0 +1,63 @@ +category: base +doc: | + Base class for collecting a session with a real electron microscope. + + For collecting data and experiments which are simulations of an + electron microscope use the :ref:`NXem_sim` base class. +type: group +NXem_msr(NXem_method): + em_lab(NXinstrument): + doc: | + (Meta)data of the microscope and the lab in which it stands. + + This em_lab group differs from potential em_lab groups inside + :ref:`NXevent_data_em` instances in that here the more static descriptions + are kept while changing, i.e. time-dependent pieces of information are + logged, via the em_lab group inside the desired number of instances + of NXevent_data_em. + + While using an :ref:`NXevent_data_em` instance, users should store only those + settings about a component which are relevant to understand the current + state of the component. Here, current means for the time interval which + the event covers (as it is detailed via start_time and end_time) timestamps. + + For example it is not relevant to store in each :ref:`NXevent_data_em` + electron_source group again the details of the gun type and the manufacturer + but only the high-voltage value and that only if it is different from the value + that is specified in the em_lab section for the static settings. + + In effect, this defines an information inference hierarchy which starts + in an individual :ref:`NXevent_data_em` instance followed by a probing of the + static section. + instrument_name(NX_CHAR): + doc: | + Given name of the microscope at the hosting institution. + This is an alias. Examples could be NionHermes, Titan, JEOL, + Gemini, etc. + location(NX_CHAR): + doc: | + Location of the lab or place where the instrument is installed. + Using GEOREF is preferred. + (NXfabrication): + (NXchamber): + (NXebeam_column): + (NXibeam_column): + (NXoptical_system_em): + (NXdetector): + doc: | + Description of the type of the detector. + + Electron microscopes have typically multiple detectors. + Different technologies are in use like CCD, scintillator, + direct electron, CMOS, or image plate to name but a few. + local_name(NX_CHAR): + doc: | + Instrument-specific alias/name + # it is unfortunate that for NXdetector there are already many places + # how one can specify details which could equally end up in fabrications + # we should give better guidance which option to use, pr to niac + # (NXfabrication): + (NXpump): + (NXstage_lab): + (NXevent_data_em_set): +# (NXevent_data_em): diff --git a/contributed_definitions/nyaml/NXem_sim.yaml b/contributed_definitions/nyaml/NXem_sim.yaml new file mode 100644 index 0000000000..81fe20db1b --- /dev/null +++ b/contributed_definitions/nyaml/NXem_sim.yaml @@ -0,0 +1,34 @@ +category: base +doc: | + Base class for simulating electron microscopy relevant beam-matter interaction. + + The concept behind this base class is to keep it as generic as possible + that simulations of electron/ion beam interaction with matter can be + represented. This base class is envisioned as the twin of the :ref:`NXem_msr` + base class. + + It is an attempt to test the idea if at some point one might even use the + same base class template to describe measurements and computer simulations + of electron microscopy. This idea is attractive because the only practical + difference between a description of a measurement with a microscope and a + computer simulation is that the latter is typically a substantially simplified + representation of the real microscope surplus the focus of the research + in such cases on specific questions. + + Such simplification can be with respect to the optical setup, typically the + ignoring of the fact that the electron beam is produced by a complex setup + of lenses while in simulations often single Einzel lenses are considered. + Dynamics of the environment like temperature fluctuation in a lab, vibrations, + users, and multiple detectors are typically either ignored or reduced in + complexity and number and coming with idealizations to keep the simulations + focused on the specific reason questions and efficiently numerically executable. +# abTEM and other simulation packages, TEMgym, etc. +type: group +NXem_sim(NXem_method): + simulation(NXprocess): + doc: | + Details about the simulation. + # sequence_index(N): + (NXprogram): + (NXcg_geodesic_mesh): + (NXimage_r_set_diff): diff --git a/contributed_definitions/nyaml/NXenergydispersion.yaml b/contributed_definitions/nyaml/NXenergydispersion.yaml new file mode 100644 index 0000000000..2a6e317062 --- /dev/null +++ b/contributed_definitions/nyaml/NXenergydispersion.yaml @@ -0,0 +1,316 @@ +category: base +doc: | + Subclass of NXelectronanalyser to describe the energy dispersion section of a + photoelectron analyser. +type: group +NXenergydispersion(NXobject): + scheme(NX_CHAR): + doc: | + Energy dispersion scheme employed, for example: tof, hemispherical, cylindrical, + mirror, retarding grid, etc. + pass_energy(NX_FLOAT): + unit: NX_ENERGY + doc: + - | + Energy of the electrons on the mean path of the analyser. Pass energy for + hemispherics, drift energy for tofs. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.63 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.63 + center_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Center of the energy window + energy_interval(NX_FLOAT): + unit: NX_ENERGY + doc: | + The interval of transmitted energies. It can be two different things depending + on whether the scan is fixed or swept. With a fixed scan it is a 2 vector + containing the extrema of the transmitted energy window (smaller number first). + With a swept scan of m steps it is a 2xm array of windows one for each + measurement point. + diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Diameter of the dispersive orbit + energy_scan_mode(NX_CHAR): + doc: | + Way of scanning the energy axis + enumeration: + fixed_analyser_transmission: + doc: + - | + constant :math:`\Delta E` mode, where the electron retardation (i.e., the fraction of pass energy to + kinetic energy, :math:`R = (E_K - W/E_p)`, is scanned, but the pass energy :math:`E_p` is kept constant. + Here, :math:`W = e \phi` is the spectrometer work function (with the potential difference :math:`\phi_{\mathrm{sample}}` + between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the + vacuum just outside the surface). + - | + This mode is often used in XPS/UPS because the energy resolution does not change with + changing energy (due to the constant pass energy). + - | + Synonyms: constant :math:`\Delta E` mode, constant analyser energy mode, CAE + mode, FAT mode + - | + xref: + spec: ISO 18115-1:2023 + term: 12.64 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.64 + fixed_retardation_ratio: + doc: + - | + constant :math:`\Delta E/E` mode, where the pass energy is scanned such that the electron retardation + ratio is constant. In this mode, electrons of all energies are decelerated with this same + fixed factor. Thus, the pass energy is proportional to the kinetic energy. This mode is often + used in Auger electron spectroscopy (AES) to improve S/N for high-KE electrons, but this + leads to a changing energy resolution (:math:`\Delta E \sim E_p`) at different kinetic energies. + It can however also be used in XPS. + - | + Synonyms: constant :math:`\Delta E/E` mode, constant retardation ratio mode, CRR + mode, FRR mode + - | + xref: + spec: ISO 18115-1:2023 + term: 12.66 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.66 + fixed_energy: + doc: | + In the fixed energy (FE) mode, the intensity for one single kinetic energy is measured for a + specified time. This mode is particulary useful during setup or alignment of the + electron analyzer, for analysis of stability of the excitation source or for sample + alignment. + + Since the mode measures intensity as a function of time, the difference in channel signals + is not of interest. Therefore, the signals from all channels are summed. + + Synonyms: FE mode + snapshot: + doc: | + Snapshot mode does not involve an energy scan and instead collects data from all channels of + the detector without averaging. The resulting spectrum reflects the energy distribution of + particles passing through the analyzer using the current settings. This mode is commonly used + to position the detection energy at the peak of a peak and record the signal, enabling faster + data acquisition within a limited energy range compared to FAT. Snapshot measurements are + particularly suitable for CCD and DLD detectors, which have multiple channels and can accurately + display the peak shape. While five or nine-channel detectors can also be used for snapshot + measurements, their energy resolution is relatively lower. + dither: + doc: | + In dither acquisition mode, the kinetic energy of the analyzer is randomly varied by a small value + around a central value and at fixed pass energy. This allows reducing or removing inhomogeneities + of the detector efficiency, such as e.g. imposed by a mesh in front of the detector. + Mostly relevant for CCD/DLD type of detectors. + tof_distance(NX_FLOAT): + unit: NX_LENGTH + doc: | + Length of the tof drift electrode + (NXaperture): + doc: | + Size, position and shape of a slit in dispersive analyzer, e.g. entrance and + exit slits. + (NXdeflector): + doc: | + Deflectors in the energy dispersive section + (NXlens_em): + doc: | + Individual lenses in the energy dispersive section + (NXfabrication): + depends_on(NX_CHAR): + doc: | + Specifies the position of the energy dispesive elemeent by pointing to the last + transformation in the transformation chain in the NXtransformations group. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the energy dispersive element as a component in the instrument. + Conventions from the NXtransformations base class are used. In principle, + the McStas coordinate system is used. The first transformation has to point + either to another component of the system or . (for pointing to the reference frame) + to relate it relative to the experimental setup. Typically, the components of a system + should all be related relative to each other and only one component should relate to + the reference coordinate system. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e084c20fefdccbc249b32694d11fe8411402d9470fd37fb15b410d3af6fa0fd8 +# +# +# +# +# +# Subclass of NXelectronanalyser to describe the energy dispersion section of a +# photoelectron analyser. +# +# +# +# Energy dispersion scheme employed, for example: tof, hemispherical, cylindrical, +# mirror, retarding grid, etc. +# +# +# +# +# Energy of the electrons on the mean path of the analyser. Pass energy for +# hemispherics, drift energy for tofs. +# +# This concept is related to term `12.63`_ of the ISO 18115-1:2023 standard. +# +# .. _12.63: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.63 +# +# +# +# +# Center of the energy window +# +# +# +# +# The interval of transmitted energies. It can be two different things depending +# on whether the scan is fixed or swept. With a fixed scan it is a 2 vector +# containing the extrema of the transmitted energy window (smaller number first). +# With a swept scan of m steps it is a 2xm array of windows one for each +# measurement point. +# +# +# +# +# Diameter of the dispersive orbit +# +# +# +# +# Way of scanning the energy axis +# +# +# +# +# constant :math:`\Delta E` mode, where the electron retardation (i.e., the fraction of pass energy to +# kinetic energy, :math:`R = (E_K - W/E_p)`, is scanned, but the pass energy :math:`E_p` is kept constant. +# Here, :math:`W = e \phi` is the spectrometer work function (with the potential difference :math:`\phi_{\mathrm{sample}}` +# between the electrochemical potential of electrons in the bulk and the electrostatic potential of an electron in the +# vacuum just outside the surface). +# +# This mode is often used in XPS/UPS because the energy resolution does not change with +# changing energy (due to the constant pass energy). +# +# Synonyms: constant :math:`\Delta E` mode, constant analyser energy mode, CAE +# mode, FAT mode +# +# This concept is related to term `12.64`_ of the ISO 18115-1:2023 standard. +# +# .. _12.64: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.64 +# +# +# +# +# constant :math:`\Delta E/E` mode, where the pass energy is scanned such that the electron retardation +# ratio is constant. In this mode, electrons of all energies are decelerated with this same +# fixed factor. Thus, the pass energy is proportional to the kinetic energy. This mode is often +# used in Auger electron spectroscopy (AES) to improve S/N for high-KE electrons, but this +# leads to a changing energy resolution (:math:`\Delta E \sim E_p`) at different kinetic energies. +# It can however also be used in XPS. +# +# Synonyms: constant :math:`\Delta E/E` mode, constant retardation ratio mode, CRR +# mode, FRR mode +# +# This concept is related to term `12.66`_ of the ISO 18115-1:2023 standard. +# +# .. _12.66: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.66 +# +# +# +# +# In the fixed energy (FE) mode, the intensity for one single kinetic energy is measured for a +# specified time. This mode is particulary useful during setup or alignment of the +# electron analyzer, for analysis of stability of the excitation source or for sample +# alignment. +# +# Since the mode measures intensity as a function of time, the difference in channel signals +# is not of interest. Therefore, the signals from all channels are summed. +# +# Synonyms: FE mode +# +# +# +# +# Snapshot mode does not involve an energy scan and instead collects data from all channels of +# the detector without averaging. The resulting spectrum reflects the energy distribution of +# particles passing through the analyzer using the current settings. This mode is commonly used +# to position the detection energy at the peak of a peak and record the signal, enabling faster +# data acquisition within a limited energy range compared to FAT. Snapshot measurements are +# particularly suitable for CCD and DLD detectors, which have multiple channels and can accurately +# display the peak shape. While five or nine-channel detectors can also be used for snapshot +# measurements, their energy resolution is relatively lower. +# +# +# +# +# In dither acquisition mode, the kinetic energy of the analyzer is randomly varied by a small value +# around a central value and at fixed pass energy. This allows reducing or removing inhomogeneities +# of the detector efficiency, such as e.g. imposed by a mesh in front of the detector. +# Mostly relevant for CCD/DLD type of detectors. +# +# +# +# +# +# +# Length of the tof drift electrode +# +# +# +# +# Size, position and shape of a slit in dispersive analyzer, e.g. entrance and +# exit slits. +# +# +# +# +# Deflectors in the energy dispersive section +# +# +# +# +# Individual lenses in the energy dispersive section +# +# +# +# +# +# Specifies the position of the energy dispesive elemeent by pointing to the last +# transformation in the transformation chain in the NXtransformations group. +# +# +# +# +# Collection of axis-based translations and rotations to describe the location and +# geometry of the energy dispersive element as a component in the instrument. +# Conventions from the NXtransformations base class are used. In principle, +# the McStas coordinate system is used. The first transformation has to point +# either to another component of the system or . (for pointing to the reference frame) +# to relate it relative to the experimental setup. Typically, the components of a system +# should all be related relative to each other and only one component should relate to +# the reference coordinate system. +# +# +# diff --git a/contributed_definitions/nyaml/NXevent_data_em.yaml b/contributed_definitions/nyaml/NXevent_data_em.yaml new file mode 100644 index 0000000000..f070c5ceb4 --- /dev/null +++ b/contributed_definitions/nyaml/NXevent_data_em.yaml @@ -0,0 +1,139 @@ +category: base +doc: | + Base class to store state and (meta)data of events with an electron microscopy. + + Electron microscopes are dynamic. Scientists often report that microscopes + *perform differently* across sessions, that they perform differently from + one day or another. In some cases, root causes for performance differences + are unclear. Users of the instrument may consider such conditions impractical, + or *too poor*, and thus abort their session. Alternatively, users may try to + bring the microscope into a state where conditions are considered better + or of whatever high enough quality for continuing the measurement. + + In all these use cases in practice it would be useful to have a mechanism + whereby time-dependent data of the instrument state can be stored and + documented with an interoperable representation. Indeed, how a session on an + electron microscope is spent depends strongly on the research question, + the user, and the imaging modalities used. + + :ref:`NXevent_data_em` represents an instance to describe and serialize flexibly + whatever is considered a time interval during which the instrument is + considered as stable enough for performing a task with the microscope. + Examples of such tasks are the collecting of data (images and spectra) or + the calibrating of some component of the instrument. Users may wish to take + only a single scan or image and complete their microscope session thereafter. + Alternatively, users are working for much longer time at the microscope, + perform recalibrations in between and take several scans (of different + regions-of-interest of the specimen), or they explore the state of the + microscope for service or maintenance tasks. + + :ref:`NXevent_data_em` serves the harmonization and documentation of this situation + with providing three key sections: Firstly, there is a header section whose + purpose is to contextualize and identify the event instance in time. + Secondly, there is a data and metadata section where individual data collections + can be stored using a standardized representation. + Finally, there is a section called em_lab which mirrors the structure of the + em_lab(NXinstrument) section in :ref:`NXem_base`. + + The idea of the first, the event-based em_lab section, is to document the + state of the microscope as it was during the event. The idea of the other, + the NXem application based em_lab(NXinstrument) section is to keep all those + pieces of information which are static in the sense that they are the same + across multiple :ref:`NXevent_data_em` instance. This reduces the amount of pieces of + information that have to be stored repetitively. + + We are aware of the fact that given the variety how an electron microscope + is used, there is a need for a flexible and adaptive documentation system. + At the same time we are also convinced though that just because one has + different requirements for some specific aspect under the umbrella of settings + to an electron microscope, this does not necessarily warrant that one has to + cook up an own schema. + + Instead, the electron microscopy community should work towards reusing schema + components as frequently as possible. This will enable that there is at all + not only a value of harmonizing electron microscopy research content but also + the technical possibility to build services around such harmonized + pieces of information. + + Arguably it is oftentimes tricky to specify a clear time interval when the + microscope is *stable enough*. Take for instance the acquisition of an image + or a stack of spectra. Having to deal with instabilities is a common theme in + electron microscopy practice. Numerical protocols can be used during data + post-processing to correct for some of the instabilities. + A few exemplar references to provide an overview on the subject is + available in the literature: + + * `C. Ophus et al. `_ + * `B. Berkels et al. `_ + * `L. Jones et al. `_ + + For specific simulation purposes, mainly in an effort to digitally repeat + or simulate the experiment, it is tempting to consider dynamics of the instrument, + implemented as time-dependent functional descriptions of e.g. lens excitations, + beam shape functions, trajectories of groups of electrons and ions, + or detector noise models. This warrants to document the time-dependent + details of individual components of the microscope + as is implemented in :ref:`NXevent_data_em`. +type: group +NXevent_data_em(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval started. If the user wishes to specify an + interval of time that the snapshot should represent during which the instrument + was stable and configured using specific settings and calibrations, + the start_time is the start (left bound of the time interval) while + the end_time specifies the end (right bound) of the time interval. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval ended. + event_identifier(NX_INT): + doc: | + Identifier of a specific state and setting of the microscope. + unit: NX_UNITLESS + event_type(NX_CHAR): + doc: | + Which specific event/measurement type. Examples are: + + * In-lens/backscattered electron, usually has quadrants + * Secondary_electron, image, topography, fractography, overview images + * Backscattered_electron, image, Z or channeling contrast (ECCI) + * Bright_field, image, TEM + * Dark_field, image, crystal defects + * Annular dark field, image (medium- or high-angle), TEM + * Diffraction, image, TEM, or a comparable technique in the SEM + * Kikuchi, image, SEM EBSD and TEM diffraction + * X-ray spectra (point, line, surface, volume), composition EDS/EDX(S) + * Electron energy loss spectra for points, lines, surfaces, TEM + * Auger, spectrum, (low Z contrast element composition) + * Cathodoluminescence (optical spectra) + * Ronchigram, image, alignment utility specifically in TEM + * Chamber, e.g. TV camera inside the chamber, education purposes. + + This field may also be used for storing additional information + about the event. For which there is at the moment no other place. + + In the long run such free-text field description should be avoided as + they are difficult to machine-interpret. Instead, reference should be given + to refactoring these descriptions into structured metadata. + The reason why in this base class the field event_type is nonetheless kept + is to offer a place whereby practically users may enter data for + follow-up modifications to support arriving at an improved :ref:`NXevent_data_em` base class. + (NXimage_r_set_diff): + (NXimage_r_set): + (NXimage_c_set): + (NXspectrum_set): + em_lab(NXinstrument): + doc: | + (Meta)data of the dynamics and changes of the microscope during the event. + # no need to duplicate the fabrication because that should remain the + (NXchamber): + (NXebeam_column): + (NXibeam_column): + (NXoptical_system_em): + (NXdetector): + (NXpump): + (NXstage_lab): + (NXuser): + (NXinteraction_vol_em): diff --git a/contributed_definitions/nyaml/NXevent_data_em_set.yaml b/contributed_definitions/nyaml/NXevent_data_em_set.yaml new file mode 100644 index 0000000000..e6f850f011 --- /dev/null +++ b/contributed_definitions/nyaml/NXevent_data_em_set.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Base class for a set of :ref:`NXevent_data_em` instances. + + Members of the set are instances of :ref:`NXevent_data_em`. These have an associated + time interval during which the conditions were considered stable and + fit enough for purpose. + + Which temporal granularity is adequate depends on the situation and + research question. Using a model which enables a collection of events offers + the most flexible way to cater for both experiments with controlled electron + beams in a real microscope or the simulation of such experiments or + individual aspects of such experiments. +type: group +NXevent_data_em_set(NXobject): + # because it should be possible to use the application definition + # to store e.g. just some descriptions about the instrument + # to which eventually no measurements are attached + # this would enable to use nxs files also for instrument + # inventory system like offered through ELNs/or LIMS + (NXevent_data_em): diff --git a/contributed_definitions/nyaml/NXfabrication.yaml b/contributed_definitions/nyaml/NXfabrication.yaml new file mode 100644 index 0000000000..387e4a4649 --- /dev/null +++ b/contributed_definitions/nyaml/NXfabrication.yaml @@ -0,0 +1,19 @@ +category: base +doc: | + Details about a component as it is defined by its manufacturer. +type: group +NXfabrication(NXobject): + vendor(NX_CHAR): + doc: | + Company name of the manufacturer. + model(NX_CHAR): + doc: | + Version or model of the component named by the manufacturer. + identifier(NX_CHAR): + doc: | + Ideally, (globally) unique persistent identifier, i.e. + a serial number or hash identifier of the component. + capability(NX_CHAR): + doc: | + Free-text list with eventually multiple terms of + functionalities which the component offers. diff --git a/contributed_definitions/nyaml/NXfiber.yaml b/contributed_definitions/nyaml/NXfiber.yaml new file mode 100644 index 0000000000..d3f686f9d9 --- /dev/null +++ b/contributed_definitions/nyaml/NXfiber.yaml @@ -0,0 +1,358 @@ +category: base +doc: | + An optical fiber, e.g. glass fiber. + + Specify the quantities that define the fiber. Fiber optics are described in + detail [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4), for + example. +symbols: + N_spectrum_core: | + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the core material is given. + N_spectrum_clad: | + Length of the spectrum vector (e.g. wavelength or energy) for which the + refractive index of the cladding material is given. + N_spectrum_attenuation: | + Length of the spectrum vector (e.g. wavelength or energy) for which the + attenuation curve is given. + +# A draft of a new base class to describe an optical fiber (e.g. glass fiber) +type: group +NXfiber(NXobject): + description: + exists: recommended + doc: | + Descriptive name or brief description of the fiber, e.g. by stating its + dimension. The dimension of a fiber can be given as 60/100/200 which + refers to a core diameter of 60 micron, a clad diameter of 100 micron, + and a coating diameter of 200 micron. + type: + doc: | + Type/mode of the fiber. Modes of fiber transmission are shown in + Fig. 5 [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4). + enumeration: [single mode, multimode graded index, multimode step index] + dispersion_type: + doc: | + Type of dispersion. + enumeration: [modal, material, chromatic] + dispersion(NX_FLOAT): + unit: NX_TIME + doc: | + Spectrum-dependent (or refractive index-dependent) dispersion of the + fiber. Specify in ps/nm*km. + dimensions: + rank: 1 + dim: [[1, N_spectrum_core]] + core(NXsample): + doc: | + Core of the fiber, i.e. the part of the fiber which transmits the light. + core_material: + doc: | + Specify the material of the core of the fiber. + core_diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Core diameter of the fiber (e.g. given in micrometer). + core_index_of_refraction(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the fiber. Specify at given wavelength + (or energy, wavenumber etc.) values. + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum_core]] + cladding(NXsample): + doc: | + Core of the fiber, i.e. the part of the fiber which transmits the light. + clad_material: + doc: | + Specify the material of the core of the fiber. + clad_diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Clad diameter of the fiber (e.g. given in micrometer). + clad_index_of_refraction(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the fiber. Specify at given wavelength + (or energy, wavenumber etc.) values. + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum_clad]] + coating(NXsample): + doc: | + Coating of the fiber. + coating_material: + doc: | + Specify the material of the coating of the fiber. + coating_diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Outer diameter of the fiber (e.g. given in micrometer). + length(NX_FLOAT): + unit: NX_LENGTH + doc: | + Length of the fiber. + spectral_range(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + Spectral range for which the fiber is designed. Enter the minimum and + maximum values (lower and upper limit) of the wavelength range. + dimensions: + rank: 1 + dim: [[1, 2]] + \@units: + doc: | + Unit of spectral array (e.g. nanometer or angstrom for wavelength, or + electronvolt for energy etc.). + transfer_rate(NX_FLOAT): + unit: NX_ANY + doc: | + Transfer rate of the fiber (in GB per second). + \@units: + doc: | + GB/s + numerical_aperture(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Numerical aperture (NA) of the fiber. + attenuation(NX_FLOAT): + unit: NX_ANY + doc: | + Wavelength-dependent attenuation of the fiber (specify in dB/km). + dimensions: + rank: 1 + dim: [[1, N_spectrum_attenuation]] + \@units: + doc: | + Use dB/km. + enumeration: [dB/km] + power_loss(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Power loss of the fiber in percentage. + acceptance_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Acceptance angle of the fiber. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 32ddd32d6ce2c9dc1924d91bda357df9aa98cff120802974177c6095be862466 +# +# +# +# +# +# +# +# +# Length of the spectrum vector (e.g. wavelength or energy) for which the +# refractive index of the core material is given. +# +# +# +# +# Length of the spectrum vector (e.g. wavelength or energy) for which the +# refractive index of the cladding material is given. +# +# +# +# +# Length of the spectrum vector (e.g. wavelength or energy) for which the +# attenuation curve is given. +# +# +# +# +# An optical fiber, e.g. glass fiber. +# +# Specify the quantities that define the fiber. Fiber optics are described in +# detail [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4), for +# example. +# +# +# +# Descriptive name or brief description of the fiber, e.g. by stating its +# dimension. The dimension of a fiber can be given as 60/100/200 which +# refers to a core diameter of 60 micron, a clad diameter of 100 micron, +# and a coating diameter of 200 micron. +# +# +# +# +# Type/mode of the fiber. Modes of fiber transmission are shown in +# Fig. 5 [here](https://www.photonics.com/Article.aspx?AID=25151&PID=4). +# +# +# +# +# +# +# +# +# +# Type of dispersion. +# +# +# +# +# +# +# +# +# +# Spectrum-dependent (or refractive index-dependent) dispersion of the +# fiber. Specify in ps/nm*km. +# +# +# +# +# +# +# +# Core of the fiber, i.e. the part of the fiber which transmits the light. +# +# +# +# Specify the material of the core of the fiber. +# +# +# +# +# Core diameter of the fiber (e.g. given in micrometer). +# +# +# +# +# Complex index of refraction of the fiber. Specify at given wavelength +# (or energy, wavenumber etc.) values. +# +# +# +# +# +# +# +# +# +# Core of the fiber, i.e. the part of the fiber which transmits the light. +# +# +# +# Specify the material of the core of the fiber. +# +# +# +# +# Clad diameter of the fiber (e.g. given in micrometer). +# +# +# +# +# Complex index of refraction of the fiber. Specify at given wavelength +# (or energy, wavenumber etc.) values. +# +# +# +# +# +# +# +# +# +# Coating of the fiber. +# +# +# +# Specify the material of the coating of the fiber. +# +# +# +# +# Outer diameter of the fiber (e.g. given in micrometer). +# +# +# +# +# +# Length of the fiber. +# +# +# +# +# Spectral range for which the fiber is designed. Enter the minimum and +# maximum values (lower and upper limit) of the wavelength range. +# +# +# +# +# +# +# Unit of spectral array (e.g. nanometer or angstrom for wavelength, or +# electronvolt for energy etc.). +# +# +# +# +# +# Transfer rate of the fiber (in GB per second). +# +# +# +# GB/s +# +# +# +# +# +# Numerical aperture (NA) of the fiber. +# +# +# +# +# Wavelength-dependent attenuation of the fiber (specify in dB/km). +# +# +# +# +# +# +# Use dB/km. +# +# +# +# +# +# +# +# +# Power loss of the fiber in percentage. +# +# +# +# +# Acceptance angle of the fiber. +# +# +# diff --git a/contributed_definitions/nyaml/NXgraph_edge_set.yaml b/contributed_definitions/nyaml/NXgraph_edge_set.yaml new file mode 100644 index 0000000000..09bf0c0a5f --- /dev/null +++ b/contributed_definitions/nyaml/NXgraph_edge_set.yaml @@ -0,0 +1,70 @@ +category: base +doc: | + A set of (eventually directed) edges which connect nodes of a graph. + + Use as a direct child of an instance of :ref:`NXgraph_root`. + Alternatively, use depends_on to specify which instance + of :ref:`NXgraph_root` is defined by this instance. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_edges: | + The number of edges. +type: group +NXgraph_edge_set(NXobject): + \@depends_on(NX_CHAR): + doc: | + Specify which instance of :ref:`NXgraph_root` this :ref:`NXgraph_edge_set` refers to. + number_of_edges(NX_UINT): + doc: | + Total number of edges, counting eventual bidirectional edges only once. + unit: NX_UNITLESS + identifier_offset(NX_INT): + doc: | + Integer which specifies the first index to be used for distinguishing + edges. Identifiers are defined either implicitly or explicitly. + + For implicit indexing the identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + For explicit indexing use the field identifier. For implicit indexing, + consult :ref:`NXcg_primitive_set` to get guidance how to set identifier_offset. + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Integer used to distinguish edges for explicit indexing. + unit: NX_UNITLESS + dim: (n_edges,) + directionality(NX_UINT): + doc: | + Specifier whether each edge is non-directional, one-directional, + or bidirectional. Use the smallest available binary representation + which can store three different states: + + * 0 / state 0x00 is non-directional + * 1 / state 0x01 is one-directional + * 2 / state 0x02 is bi-directional + unit: NX_UNITLESS + dim: (n_edges,) + node_pair(NX_INT): + doc: | + Pairs of node/vertex identifier. Each pair represents the connection + between two nodes. The order in the pair encodes eventual directionality. + + In the case that an edge is non- or bi-directional, storing + node identifier in ascending order is preferred. + + In the case that an edge is one-directional, node identifier should be + stored such that the identifier of the source node is the first entry + and the identifier of the target is the second entry in the pair. + unit: NX_UNITLESS + dim: (n_edges, 2) + is_a(NX_CHAR): + doc: | + A human-readable qualifier which type or e.g. class instance the + edge is an instance of. + dim: (n_edges,) + label(NX_CHAR): + doc: | + A human-readable label/caption/tag of each edge. + dim: (n_edges,) diff --git a/contributed_definitions/nyaml/NXgraph_node_set.yaml b/contributed_definitions/nyaml/NXgraph_node_set.yaml new file mode 100644 index 0000000000..93e8ac08ba --- /dev/null +++ b/contributed_definitions/nyaml/NXgraph_node_set.yaml @@ -0,0 +1,61 @@ +category: base +doc: | + A set of nodes representing members of a graph. + + Use as a direct child of an instance of :ref:`NXgraph_root`. + Alternatively, use depends_on to specify which instance + of NXgraph_root is defined by this instance. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of nodes of the graph. + d: | + The dimensionality of the graph. Eventually use one for categorical. +type: group +NXgraph_node_set(NXobject): + \@depends_on(NX_CHAR): + doc: | + Specify which instance of :ref:`NXgraph_root` this :ref:`NXgraph_node_set` refers to. + space(NX_CHAR): + doc: | + About which space does the graph make statements. + enumeration: [euclidean, other] + dimensionality(NX_UINT): + doc: | + Dimensionality of the space about which the graph makes statements. + Use only when value of the field space is euclidean. + unit: NX_UNITLESS + enumeration: [1, 2, 3] + cardinality(NX_UINT): + doc: | + Number of nodes of the graph. + unit: NX_UNITLESS + identifier_offset(NX_INT): + doc: | + Integer which specifies the first index to be used for distinguishing + nodes. Identifiers are defined either implicitly or explicitly. + + For implicit indexing the identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + For explicit indexing use the field identifier. For implicit indexing, + consult :ref:`NXcg_primitive_set` to get guidance how to set identifier_offset. + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Integer used to distinguish nodes for explicit indexing. + unit: NX_UNITLESS + dim: (c,) + is_a(NX_CHAR): + doc: | + A human-readable qualifier which type or e.g. class instance the + node is an instance of. An example: a NeXus application definition is a + graph, more specifically a hierarchical directed labelled property graph. + Instances which are groups like :ref:`NXgraph_node_set` could have an is_a + qualifier reading :ref:`NXgraph_node_set`. + dim: (c,) + label(NX_CHAR): + doc: | + A human-readable label/caption/tag of each node. + dim: (c,) diff --git a/contributed_definitions/nyaml/NXgraph_root.yaml b/contributed_definitions/nyaml/NXgraph_root.yaml new file mode 100644 index 0000000000..6fce3503c9 --- /dev/null +++ b/contributed_definitions/nyaml/NXgraph_root.yaml @@ -0,0 +1,10 @@ +category: base +doc: | + An instance of a graph. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXgraph_root(NXobject): + nodes(NXgraph_node_set): + relation(NXgraph_edge_set): diff --git a/contributed_definitions/nyaml/NXibeam_column.yaml b/contributed_definitions/nyaml/NXibeam_column.yaml new file mode 100644 index 0000000000..e02716619b --- /dev/null +++ b/contributed_definitions/nyaml/NXibeam_column.yaml @@ -0,0 +1,108 @@ +category: base +doc: | + Base class for a set of components equipping an instrument with FIB capabilities. + + Focused-ion-beam (FIB) capabilities turn especially scanning electron microscopes + into specimen preparation labs. FIB is a material preparation technique whereby + portions of the sample are illuminated with a focused ion beam with controlled + intensity. The beam is intense enough and with sufficient ion momentum to + remove material in a controlled manner. + + The fact that an electron microscope with FIB capabilities has needs a + second gun with own relevant control circuits, focusing lenses, and other + components, warrants the definition of an own base class to group these + components and distinguish them from the lenses and components for creating + and shaping the electron beam. + + For more details about the relevant physics and application examples + consult the literature, for example: + + * `L. A. Giannuzzi et al. `_ + * `E. I. Preiß et al. `_ + * `J. F. Ziegler et al. `_ + * `J. Lili `_ + +# symbols: +# doc: The symbols used in the schema to specify e.g. variables. +type: group +# NXibeam_column is an NXobject instead of an NXcomponent_em to make that +# part "an ion gun" reusable in other context +NXibeam_column(NXobject): + (NXchamber): + (NXfabrication): + ion_source(NXsource): + doc: | + The source which creates the ion beam. + name(NX_CHAR): + doc: | + Given name/alias for the ion gun. + emitter_type(NX_CHAR): + doc: | + Emitter type used to create the ion beam. + + If the emitter type is other, give further + details in the description field. + enumeration: [liquid_metal, plasma, gas_field, other] + description(NX_CHAR): # NXidentifier + doc: | + Ideally, a (globally) unique persistent identifier, link, + or text to a resource which gives further details. + probe(NXion): + doc: | + Which ionized elements or molecular ions form the beam. + Examples are gallium, helium, neon, argon, krypton, + or xenon, O2+. + flux(NX_NUMBER): + doc: | + Average/nominal flux + unit: NX_ANY # 1/(area*time) + brightness(NX_NUMBER): + doc: | + Average/nominal brightness + unit: NX_ANY # 1/steradiant or area + # \@units: A/cm*sr + # NEW ISSUE: (at which location?). + current(NX_NUMBER): + doc: | + Charge current + unit: NX_CURRENT + voltage(NX_NUMBER): + doc: | + Ion acceleration voltage upon source exit and + entering the vacuum flight path. + unit: NX_VOLTAGE + ion_energy_profile(NX_NUMBER): + doc: | + To be defined more specifically. Community suggestions are welcome. + unit: NX_ENERGY + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. + # NEW ISSUE: details about the life/up-time of the source + # relevant from maintenance point of view + (NXaperture_em): + (NXlens_em): + (NXscanbox_em): + (NXsensor): + (NXbeam): + doc: | + Individual characterization results for the position, shape, + and characteristics of the ion beam. + + :ref:`NXtransformations` should be used to specify the location or position + at which details about the ion beam are probed. + # NEW ISSUE: scan_align(NXprocess): + # NEW ISSUE: milling_plan(NXprocess): + # doc: Description of the program and sequence of sample positions sputtered. + # in here we can store time-dependent quantities + # NEW ISSUE: for documentation of charge compensation + # (NXtransformation): + # doc: | + # A right-handed Cartesian coordinate system is used whose positive + # z-axis points in the direction of the ion beam, i.e. towards the + # sample. For modelling ion milling it is relevant to document the + # illumination vector. NXtransformations offers a place to store how the + # ion gun coordinate system has to be rotated to align its positive z-axis + # with the positive z-axis of e.g. the electron beam and ion beam + # respectively. diff --git a/contributed_definitions/nyaml/NXidentifier.yaml b/contributed_definitions/nyaml/NXidentifier.yaml new file mode 100644 index 0000000000..4fc57a0589 --- /dev/null +++ b/contributed_definitions/nyaml/NXidentifier.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + An identifier for a (persistent) resource, e.g., a DOI or orcid. +type: group +NXidentifier(NXobject): + service(NX_CHAR): + doc: | + The service by which the resouce can be resolved. + If the service is not in the list a simple `url` may be used. + The `url` can either be a resolving service for the `identifier` + or a fully qualified identification in itself. + enumeration: [doi, urn, hdl, purl, orcid, iso, url] + identifier(NX_CHAR): + doc: | + The unique code, IRI or hash to resolve this reference. + Typically, this is stated by the service which is considered a complete + identifier, e.g., for a DOI it's something of the form `10.1107/S1600576714027575` + or `https://doi.org/10.1107/S1600576714027575`, which are both resolvable. + is_persistent(NX_BOOLEAN): + doc: | + True if the identifier is persistent (i.e., unique and available indefinetely), False otherwise. \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXimage_c_set.yaml b/contributed_definitions/nyaml/NXimage_c_set.yaml new file mode 100644 index 0000000000..8dcd85706d --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_c_set.yaml @@ -0,0 +1,140 @@ +category: base +doc: | + Specialized base class container for reporting a set of images in reciprocal space. + + In practice, complex numbers are encoded via some formatted pair of real values. + Typically, fast Algorithms for computing Fourier Transformations (FFT) are + used to encode images in reciprocal (frequency) space. FFT libraries are used + for implementing the key functionalities of these mathematical operations. + + Different libraries use different representations and encoding of the + image computed. Details can be found in the respective sections of the + typical FFT libraries: + + * `FFTW by M. Frigo and S. G. Johnson `_ + * `Intel MKL by the Intel Co. `_ + * `cuFFT by the NVidia Co. `_ + + Users are strongly advised to inspect carefully which specific conventions + their library uses to be able to store and modify the implementation of their + code so that the serialized representations as it is detailed + here for NeXus matches with their intention. + + One- and two-dimensional FFTs should use the stack(NXdata) instances. + Three-dimensional FFTs should use the hyperstack(NXdata) instances. +symbols: + n_images: | + Number of images in the (hyper)stack. + n_k: | + Number of pixel per image in the slowest direction. + n_j: | + Number of pixel per image in the slow direction. + n_i: | + Number of pixel per image in the fast direction. +type: group +NXimage_c_set(NXimage_set): + # details about the FFT library used could for instance be stored in the + # NXprocess group which the NXimage_c_set base class can borrow from its + # NXimage_set parent base class + # process information are composable from the NXimage_set base class + stack(NXdata): + doc: | + Image stack. + real(NX_NUMBER): + doc: | + Image intensity of the real part. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + imag(NX_NUMBER): + doc: | + Image intensity of the imaginary part. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + magnitude(NX_NUMBER): + doc: | + Magnitude of the image intensity. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + # axis_k(NX_NUMBER): + # doc: | + # Pixel coordinate center along k direction. + # unit: NX_ANY # NX_RECIPROCAL_LENGTH + # dim: (n_k,) + # \@long_name(NX_CHAR): + # doc: | + # Coordinate along j direction. + axis_j(NX_NUMBER): + doc: | + Pixel coordinate center along j direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_i(NX_NUMBER): + doc: | + Pixel coordinate center along i direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Coordinate along i direction. + + hyperstack(NXdata): + doc: | + Image hyperstack. + real(NX_NUMBER): + doc: | + Image intensity of the real part. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + imag(NX_NUMBER): + doc: | + Image intensity of the imaginary part. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + magnitude(NX_NUMBER): + doc: | + Magnitude of the image intensity. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + axis_k(NX_NUMBER): + doc: | + Pixel coordinate center along k direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_k,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_j(NX_NUMBER): + doc: | + Pixel coordinate center along j direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_i(NX_NUMBER): + doc: | + Pixel coordinate center along i direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Coordinate along i direction. diff --git a/contributed_definitions/nyaml/NXimage_r_set.yaml b/contributed_definitions/nyaml/NXimage_r_set.yaml new file mode 100644 index 0000000000..f0437e6e6f --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_r_set.yaml @@ -0,0 +1,45 @@ +category: base +doc: | + Specialized base class container for reporting a set of images in real space. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXimage_r_set(NXimage_set): + # process information are composable from the NXimage_set base class + stack(NXdata): + doc: | + Image (stack). + intensity(NX_NUMBER): + doc: | + Image intensity values. + unit: NX_UNITLESS + dim: (n_images, n_y, n_x) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + axis_y(NX_NUMBER): + doc: | + Pixel coordinate center along y direction. + unit: NX_LENGTH + dim: (n_y,) + \@long_name(NX_CHAR): + doc: | + Coordinate along y direction. + axis_x(NX_NUMBER): + doc: | + Pixel coordinate center along x direction. + unit: NX_LENGTH + dim: (n_x,) + \@long_name(NX_CHAR): + doc: | + Coordinate along x direction. diff --git a/contributed_definitions/nyaml/NXimage_r_set_diff.yaml b/contributed_definitions/nyaml/NXimage_r_set_diff.yaml new file mode 100644 index 0000000000..79ca31b168 --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_r_set_diff.yaml @@ -0,0 +1,123 @@ +category: base +doc: | + Base class specialized for reporting a cuboidal stack of diffraction pattern. + + Diffraction pattern, whether they were simulated or measured are the raw data + for computational workflows to characterize the phase and orientation + of crystalline regions in matter. + + Steps of post-processing the diffraction patterns should be documented using + method-specific specialized base classes. All eventual post-processing of + resulting orientation maps (2D or 3D) should be documented via :ref:`NXms_recon`. + + To implement an example how this base class can be used we focused in FAIRmat + on Kikuchi diffraction pattern here specifically the research community + of Electron Backscatter Diffraction (EBSD). + + For this reason, this base class and related :ref:`NXem_base` classes extend the + work of `M. A. Jackson et al. `_ + (one of the developers of DREAM.3D) and the H5OINA public file format developed by + `P. Pinard et al. `_ with Oxford Instruments. + + Kikuchi pattern are typically collected with FIB/SEM microscopes, + for two- and three-dimensional orientation microscopy. + + For a detailed overview of these techniques see e.g. + + * `M. A. Groeber et al. `_ + * `A. J. Schwartz et al. `_ + * `P. A. Rottman et al. `_ + + Serial-sectioning demands a recurrent sequence of ion milling and measuring. + This suggests that each serial section is at least an own NXevent_data_em + instance. The three-dimensional characterization as such demands a computational + step where the maps for each serial section get cleaned, aligned, and registered + into an image stack. This image stack represents a digital model of the + inspected microstructural volume. Often this volume is called a (representative) + volume element (RVE). Several software packages exists for performing + these post-processing tasks. + + This example may inspire users of other types of diffraction methods. +symbols: + n_sc: | + Number of scanned points. Scan point may have none, one, or more pattern. + n_p: | + Number of diffraction pattern. + n_y: | + Number of pixel per pattern in the slow direction. + n_x: | + Number of pixel per pattern in the fast direction. +type: group +NXimage_r_set_diff(NXimage_r_set): + pattern_type(NX_CHAR): + doc: | + Category which type of diffraction pattern is reported. + enumeration: [kikuchi] + stack(NXdata): + doc: | + Collected diffraction pattern as an image stack. As raw and closest to the + first retrievable measured data as possible, i.e. do not use this + container to store already averaged, filtered or whatever post-processed + pattern unless these are generated unmodifiably in such manner by the + instrument given the way how the instrument and control software + was configured for your microscope session. + scan_point_identifier(NX_INT): + doc: | + Array which resolves the scan point to which each pattern belongs. + + Scan points are evaluated in sequence starting from scan point zero + until scan point n_sc - 1. Evaluating the cumulated of this array + decodes which pattern in intensity belongs to which scan point. + + Take an example with three scan points: The first scan point has one + pattern, the second has three pattern, the last scan point has no + pattern. In this case the scan_point_identifier are 0, 1, 1, 1. + The length of the scan_point_identifier array is four because four + pattern were measured in total. + + In most cases usually one pattern is averaged by the detector for + some amount of time and then reported as one pattern. + unit: NX_UNITLESS + dim: (n_p,) + intensity(NX_NUMBER): + doc: | + Intensity of the diffraction pattern. + unit: NX_UNITLESS + dim: (n_p, n_y, n_x) + # n_p fast 2, n_y faster 1, n_x fastest 0 + # in axes fast to fastest + # while for _indices fastest to fast + \@long_name(NX_CHAR): + doc: | + Pattern intensity + # \@signal: intensity + # \@axes: [pattern_identifier, ypos, xpos] + # \@xpos_indices: 0 + # \@ypos_indices: 1 + # \@pattern_identifier_indices: 2 + pattern_identifier(NX_INT): + doc: | + Pattern are enumerated starting from 0 to n_p - 1. + unit: NX_UNITLESS + dim: (n_p,) + \@long_name(NX_CHAR): + doc: | + Pattern identifier + # the following fields are taken from the NXimage_r_set base class + # axis_y(R): + # axis_x(R): + +# If we envision a (knowledge) graph for EBSD it consists of individual sub-graphs +# which convey information about the specimen preparation, the measurement of +# the specimen in the electron microscope, the indexing of the collected +# Kikuchi pattern stack, eventual post-processing of the indexed orientation +# images via similarity grouping algorithms to yield (grains, texture). +# Conceptually, these post-processing steps are most frequently serving +# the idea how can one reconstruct so-called microstructural features +# (grains, phases, interfaces) to infer material properties. +# In practice this calls for workflows which quantify correlations between +# the spatial arrangement of the microstructural features, the individual +# (thermodynamic, chemo-mechanical) properties of the features with the +# properties of materials at a coarser scale. +# With NXem and related NXms base classes we propose a covering +# and general solution how to handle such (meta)data with NeXus. diff --git a/contributed_definitions/nyaml/NXimage_set.yaml b/contributed_definitions/nyaml/NXimage_set.yaml new file mode 100644 index 0000000000..0bedd8d19c --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_set.yaml @@ -0,0 +1,33 @@ +category: base +doc: | + Base class for reporting a set of images. + + This class provides a base vocabulary to be used for specialized :ref:`NXimage_set` + base classes like :ref:`NXimage_r_set` and :ref:`NXimage_c_set`. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXimage_set(NXobject): + (NXprocess): + doc: | + Details how NXdata instance inside instance of (specialized) + :ref:`NXimage_set` were processed from the detector readings/raw data. + source(NXserialized): + doc: | + Resolvable data artifact (e.g. filename) from which the all values in + the :ref:`NXdata` instances in this :ref:`NXimage_set` were loaded + during parsing. + mode(NX_CHAR): + doc: | + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXimage_set` instance. + detector_identifier(NX_CHAR): + doc: | + Link or name of an :ref:`NXdetector` instance with which the data were collected. + (NXprogram): + (NXdata): diff --git a/contributed_definitions/nyaml/NXinteraction_vol_em.yaml b/contributed_definitions/nyaml/NXinteraction_vol_em.yaml new file mode 100644 index 0000000000..ce752c0dbd --- /dev/null +++ b/contributed_definitions/nyaml/NXinteraction_vol_em.yaml @@ -0,0 +1,34 @@ +category: base +doc: | + Base class for describing the interaction volume of particle-matter interaction. + + Computer models like Monte Carlo or molecular dynamics / electron- or ion-beam + interaction simulations can be used to qualify and (or) quantify the shape of + the interaction volume. Results of such simulations can be summary statistics + or single-particle resolved sets of trajectories. + + Explicit or implicit descriptions are possible. + + * An implicit description is via a set of electron/specimen interactions + represented ideally as trajectory data from the computer simulation. + * An explicit description is via an iso-contour surface using either + a simulation grid or a triangulated surface mesh of the approximated + iso-contour surface evaluated at specific threshold values. + Iso-contours could be computed from electron or particle fluxes through + an imaginary control surface (the iso-surface). + Threshold values can be defined by particles passing through a unit control + volume (electrons) or energy-levels (e.g. the case of X-rays). + Details depend on the model. + * Another explicit description is via theoretical models which may + be relevant e.g. for X-ray spectroscopy + + Further details on how the interaction volume can be quantified + is available in the literature for example: + + * `S. Richter et al. `_ + * `J. Bünger et al. `_ + * `J. F. Ziegler et al. `_ +type: group +NXinteraction_vol_em(NXobject): + (NXdata): + (NXprocess): diff --git a/contributed_definitions/nyaml/NXion.yaml b/contributed_definitions/nyaml/NXion.yaml new file mode 100644 index 0000000000..360f925566 --- /dev/null +++ b/contributed_definitions/nyaml/NXion.yaml @@ -0,0 +1,110 @@ +category: base +doc: | + Set of atoms of a molecular ion or fragment in e.g. ToF mass spectrometry. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ivecmax: | + Maximum number of atoms/isotopes allowed per (molecular) ion (fragment). + n_ranges: | + Number of mass-to-charge-state-ratio range intervals for ion type. +type: group +NXion(NXobject): + identifier(NX_CHAR): + doc: | + A unique identifier whereby such an ion can be referred to + via the service offered as described in identifier_type. + identifier_type(NX_CHAR): + doc: | + How can the identifier be resolved? + enumeration: [inchi] + ion_type(NX_UINT): + doc: | + Ion type (ion species) identifier. + + The identifier zero is reserved for the special unknown ion type. + unit: NX_UNITLESS + isotope_vector(NX_UINT): + doc: | + A vector of isotope hash values. These values have to be stored in an array, + sorted in decreasing order. The array is filled with zero hash values + indicating unused places. The individual hash values are built with the + following hash function: + + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. + + Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) `_ + unit: NX_UNITLESS + dim: (1, n_ivecmax) + nuclid_list(NX_UINT): + doc: | + A supplementary row vector which decodes the isotope_vector into + a human-readable matrix of nuclids with the following formatting: + + The first row specifies the isotope mass number, i.e. using the hashvalues + from the isotope_vector this is :math:`Z + N`. As an example for a + carbon-14 isotope the number is 14. + The second row specifies the number of protons :math:`Z`, e.g. 6 for the + carbon-14 example. This row matrix is thus mapping the notation of + using superscribed isotope mass and subscripted number of protons + to identify isotopes. + Unused places filling up to n_ivecmax need to be filled with zero. + unit: NX_UNITLESS + dim: (2, n_ivecmax) + color(NX_CHAR): + doc: | + Color code used for visualizing such ions. + volume(NX_NUMBER): + doc: | + Assumed volume of the ion. + + In atom probe microscopy this field can be used to store the reconstructed + volume per ion (average) which is typically stored in range files and will + be used when building a tomographic reconstruction of an atom probe + dataset. + unit: NX_VOLUME + charge(NX_NUMBER): + doc: | + Charge of the ion. + unit: NX_CHARGE + charge_state(NX_INT): + doc: | + Signed charge state of the ion in multiples of electron charge. + + Only positive values will be measured in atom probe microscopy as the + ions are accelerated by a negatively signed bias electric field. + In the case that the charge state is not explicitly recoverable, + the value should be set to zero. + + In atom probe microscopy this is for example the case when using + classical range file formats like RNG, RRNG for atom probe data. + These file formats do not document the charge state explicitly. + They report the number of atoms of each element per molecular ion + surplus the mass-to-charge-state-ratio interval. + With this information it is possible to recover the charge state only + for specific molecular ions as the accumulated mass of the molecular ion + is defined by the isotopes, which without knowing the charge, leads + to an underconstrained problem. + Details on ranging can be found in the literature: `M. K. Miller `_ + unit: NX_UNITLESS + name(NX_CHAR): + doc: | + Human-readable ion type name (e.g. Al +++) + The string should consists of UTF-8 characters, ideally using LaTeX + notation to specify the isotopes, ions, and charge state. + Examples are 12C + or Al +++. + + To ease automated parsing isotope_vector should be the + preferred machine-readable information used. + mass_to_charge_range(NX_NUMBER): + doc: | + Associated lower (mqmin) and upper (mqmax) bounds of the + mass-to-charge-state ratio interval(s) [mqmin, mqmax] + (boundaries inclusive). This field is primarily of interest + for documenting :ref:`NXprocess` steps of indexing a ToF/mass-to-charge + state histogram. + unit: NX_ANY # NX_DALTON + dim: (n_ranges, 2) diff --git a/contributed_definitions/nyaml/NXisocontour.yaml b/contributed_definitions/nyaml/NXisocontour.yaml new file mode 100644 index 0000000000..5f64c3c782 --- /dev/null +++ b/contributed_definitions/nyaml/NXisocontour.yaml @@ -0,0 +1,104 @@ +category: base +doc: | + Computational geometry description of isocontouring/phase-fields in Euclidean space. + + Iso-contouring algorithms such as MarchingCubes and others are frequently + used to segment d-dimensional regions into regions where intensities are + lower or higher than a threshold value, the so-called isovalue. + + Frequently in computational materials science phase-field methods are + used which generate data on discretized grids. Isocontour algorithms + are often used in such context to pinpoint the locations of microstructural + features from this implicit phase-field-variable-based description. + + One of the key intentions of this base class is to provide a starting point + for scientists from the phase-field community (condensed matter physicists, + and materials engineers) to incentivize that also phase-field simulation + data could be described with NeXus, provided base classes such as the this one + get further extend according to the liking of the phase-field community. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the description. +type: group +NXisocontour(NXobject): + dimensionality(NX_POSINT): + doc: | + The dimensionality of the space in which the isocontour is embedded. + unit: NX_UNITLESS + enumeration: [2, 3] + grid(NXcg_grid): + doc: | + The discretized grid on which the iso-contour algorithm operates. + isovalue(NX_NUMBER): + unit: NX_ANY + doc: | + The threshold or iso-contour value. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b300a7c96b0af0dc9017c870a9758dc2c5e0b922c869ae76458457db04fdcb8d +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# The dimensionality of the description. +# +# +# +# +# Computational geometry description of isocontouring/phase-fields in Euclidean space. +# +# Iso-contouring algorithms such as MarchingCubes and others are frequently +# used to segment d-dimensional regions into regions where intensities are +# lower or higher than a threshold value, the so-called isovalue. +# +# Frequently in computational materials science phase-field methods are +# used which generate data on discretized grids. Isocontour algorithms +# are often used in such context to pinpoint the locations of microstructural +# features from this implicit phase-field-variable-based description. +# +# One of the key intentions of this base class is to provide a starting point +# for scientists from the phase-field community (condensed matter physicists, +# and materials engineers) to incentivize that also phase-field simulation +# data could be described with NeXus, provided base classes such as the this one +# get further extend according to the liking of the phase-field community. +# +# +# +# +# The discretized grid on which the iso-contour algorithm operates. +# +# +# +# +# The threshold or iso-contour value. +# +# +# diff --git a/contributed_definitions/nyaml/NXiv_bias.yaml b/contributed_definitions/nyaml/NXiv_bias.yaml new file mode 100644 index 0000000000..8f53ae52fc --- /dev/null +++ b/contributed_definitions/nyaml/NXiv_bias.yaml @@ -0,0 +1,324 @@ +category: base +doc: | + Application definition for bias devices. +type: group +NXiv_bias(NXobject): + bias(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Applied a voltage between tip and sample. + tunneling_resistor(NX_NUMBER): + unit: NX_ANY + doc: | + The ratio between the tunneling current at the sample surface and the bias voltage + applied between the sample and the tip. + calibration(NX_NUMBER): + doc: | + Calibration of the Bias output (V/V). + offset(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Allows compensating for an offset in Bias. Hardware parameter offset. + modulated_signal_bias(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Sets the amplitude (in physical units of the modulated signal) of the sine + modulation. + (NXbias_spectroscopy): + doc: | + Bias sweeps while measuring arbitrary channels with I(V) curves. + channels(NX_CHAR): + doc: | + Select the channels to record. + reset_bias(NX_BOOLEAN): + doc: | + When selected, the Bias voltage returns to the initial value (before starting the sweep) at + the end of the spectroscopy measurement (default). When not selected, Bias remains at the + last value of the sweep. This is useful e.g. when combining several sweep segments. Example + for an automated measurement (using Programming Interface): switch off Z-Controller, start + spectroscopy sweep segments (only fwd sweep, no reset bias), set bias back to initial value, + switch on Z-Controller. + record_final_z(NX_BOOLEAN): + doc: | + Select whether to record the Z position during Z averaging time at the end of + the sweep (after Z control time) and store the average value in the header of + the file when saving. Using this option increases the sweep time by Z averaging + time. + lock_in_run(NX_BOOLEAN): + doc: | + Select whether to set the Lock-In to run during the measurement. When using this + feature, make sure the Lock-In is configured correctly and settling times are + set to twice the Lock-In period at least. This option is ignored when Lock-In is + already running. This option is disabled if the Sweep Mode is MLS and the flag + to configure the Lock-In per segment in the Multiline segment editor is set. + integration_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the spectroscopy data are acquired and averaged. + number_of_sweeps(NX_NUMBER): + doc: | + Number of sweeps to measure and average. + sweep_start(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The first bias values of the sweep. + sweep_end(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The last bias values of the sweep. + num_pixel(NX_NUMBER): + doc: | + Define the sweep number of points, that is, the maximum spectrum resolution eq. + Bias window divide by Num Pixel. + z_avg_time(NX_NUMBER): + unit: NX_TIME + doc: | + Duration over which the Z position is recorded and averaged before and after the + sweep (the latter only if Record final Z position is selected in the Advanced + section). After the initial Z averaging time, if Z-Controller to Hold is + selected in the Advanced section, the Z-Controller is set to hold and the tip is + placed at the previously averaged Z position (plus Z offset). + sw_filter_type(NX_CHAR): + doc: | + Select a filter to smooth the displayed data. When saving, if any filter + selected, filtered data are saved to file along with the unfiltered data. + sw_ilter_order(NX_NUMBER): + doc: | + Filter order of a dynamic filter or width (in number of points) for the gaussian + filter. + sw_filter_cutoff_frq(NX_NUMBER): + doc: | + Cutoff frequency for dynamic filters. + z_offset(NX_NUMBER): + unit: NX_LENGTH + doc: | + Offset added to the initial averaged position Zaver before starting to sweep. + This parameter is disabled when Z-Controller to Hold is deselected in the + Advanced section. The LED “Alt” next to the Z offset indicates if an alternate + Z-controller setpoint is enabled. + settling_time(NX_NUMBER): + unit: NX_TIME + doc: | + time to wait after changing the bias to the next level and before starting to + acquire data. + end_settling_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time to wait after the sweep has finished and the bias is ramped to the initial + value. + z_control_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the Z-Controller is enabled once a sweep has finished. When + averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled for this + duration between each sweep. After the last sweep, it will wait the specified + time before continuing a running scan. This ensures each sweep reliably starts + from the same position. This parameter is disabled when Z-Controller to Hold is + deselected in the Advanced section. + max_sew_rate(NX_NUMBER): + doc: | + Maximum rate at which the bias changes (before, during and after sweeping). + (V/s) + backward_sweep(NX_BOOLEAN): + doc: | + Select whether to measure the backward (return) sweep or the forward only. + z_controller_hold(NX_BOOLEAN): + doc: | + Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. + It is selected by default. When deselected, Z-offset and Z-control time + parameters are disabled. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a6b94f019c914824a8a0ec5b134141063c65e973450f5b7ec9ac852e29aac455 +# +# +# +# +# +# Application definition for bias devices. +# +# +# +# Applied a voltage between tip and sample. +# +# +# +# +# The ratio between the tunneling current at the sample surface and the bias voltage +# applied between the sample and the tip. +# +# +# +# +# Calibration of the Bias output (V/V). +# +# +# +# +# Allows compensating for an offset in Bias. Hardware parameter offset. +# +# +# +# +# Sets the amplitude (in physical units of the modulated signal) of the sine +# modulation. +# +# +# +# +# Bias sweeps while measuring arbitrary channels with I(V) curves. +# +# +# +# +# Select the channels to record. +# +# +# +# +# When selected, the Bias voltage returns to the initial value (before starting the sweep) at +# the end of the spectroscopy measurement (default). When not selected, Bias remains at the +# last value of the sweep. This is useful e.g. when combining several sweep segments. Example +# for an automated measurement (using Programming Interface): switch off Z-Controller, start +# spectroscopy sweep segments (only fwd sweep, no reset bias), set bias back to initial value, +# switch on Z-Controller. +# +# +# +# +# Select whether to record the Z position during Z averaging time at the end of +# the sweep (after Z control time) and store the average value in the header of +# the file when saving. Using this option increases the sweep time by Z averaging +# time. +# +# +# +# +# Select whether to set the Lock-In to run during the measurement. When using this +# feature, make sure the Lock-In is configured correctly and settling times are +# set to twice the Lock-In period at least. This option is ignored when Lock-In is +# already running. This option is disabled if the Sweep Mode is MLS and the flag +# to configure the Lock-In per segment in the Multiline segment editor is set. +# +# +# +# +# Time during which the spectroscopy data are acquired and averaged. +# +# +# +# +# Number of sweeps to measure and average. +# +# +# +# +# The first bias values of the sweep. +# +# +# +# +# The last bias values of the sweep. +# +# +# +# +# Define the sweep number of points, that is, the maximum spectrum resolution eq. +# Bias window divide by Num Pixel. +# +# +# +# +# Duration over which the Z position is recorded and averaged before and after the +# sweep (the latter only if Record final Z position is selected in the Advanced +# section). After the initial Z averaging time, if Z-Controller to Hold is +# selected in the Advanced section, the Z-Controller is set to hold and the tip is +# placed at the previously averaged Z position (plus Z offset). +# +# +# +# +# Select a filter to smooth the displayed data. When saving, if any filter +# selected, filtered data are saved to file along with the unfiltered data. +# +# +# +# +# Filter order of a dynamic filter or width (in number of points) for the gaussian +# filter. +# +# +# +# +# Cutoff frequency for dynamic filters. +# +# +# +# +# Offset added to the initial averaged position Zaver before starting to sweep. +# This parameter is disabled when Z-Controller to Hold is deselected in the +# Advanced section. The LED “Alt” next to the Z offset indicates if an alternate +# Z-controller setpoint is enabled. +# +# +# +# +# time to wait after changing the bias to the next level and before starting to +# acquire data. +# +# +# +# +# Time to wait after the sweep has finished and the bias is ramped to the initial +# value. +# +# +# +# +# Time during which the Z-Controller is enabled once a sweep has finished. When +# averaging multiple sweeps (i.e. Sweeps>1), the Z-Controller is enabled for this +# duration between each sweep. After the last sweep, it will wait the specified +# time before continuing a running scan. This ensures each sweep reliably starts +# from the same position. This parameter is disabled when Z-Controller to Hold is +# deselected in the Advanced section. +# +# +# +# +# Maximum rate at which the bias changes (before, during and after sweeping). +# (V/s) +# +# +# +# +# Select whether to measure the backward (return) sweep or the forward only. +# +# +# +# +# Select whether to set the Z-Controller on hold (i.e. disabled) during the sweep. +# It is selected by default. When deselected, Z-offset and Z-control time +# parameters are disabled. +# +# +# diff --git a/contributed_definitions/nyaml/NXiv_temp.yaml b/contributed_definitions/nyaml/NXiv_temp.yaml new file mode 100644 index 0000000000..732b36f25a --- /dev/null +++ b/contributed_definitions/nyaml/NXiv_temp.yaml @@ -0,0 +1,164 @@ +category: application +doc: | + Application definition for temperature-dependent IV curve measurements. + + In this application definition, times should be specified always together + with an UTC offset. + + This is the application definition describing temperature dependent IV curve + measurements. For this a temperature is set. After reaching the temperature, + a voltage sweep is performed. For each voltage a current is measured. + Then, the next desired temperature is set and an IV measurement is performed. +symbols: + n_different_temperatures: | + Number of different temperature setpoints used in the experiment. + n_different_voltages: | + Number of different voltage setpoints used in the experiment. +type: group +NXiv_temp(NXsensor_scan): + (NXentry): + definition: + enumeration: [NXiv_temp] + (NXsample): + exists: recommended + name: + doc: | + Descriptive name or ideally (globally) unique persistent identifier. + atom_types: + doc: | + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + + The purpose of the field is to offer materials database systems an + opportunity to parse the relevant elements without having to interpret + these from the sample history or from other data sources. + (NXinstrument): + (NXenvironment): + doc: | + Describes an environment setup for a temperature-dependent IV measurement experiment. + + The temperature and voltage must be present as independently scanned controllers and + the current sensor must also be present with its readings. + voltage_controller(NXsensor): + temperature_controller(NXsensor): + current_sensor(NXsensor): + (NXdata): + doc: | + This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. + There should also be two more fields called temperature and voltage containing the setpoint values. + There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension + equal to the number of voltage setpoints. + temperature(NX_NUMBER): + voltage(NX_NUMBER): + current(NX_NUMBER): + dimensions: + rank: 2 + dim: [[1, n_different_temperatures], [2, n_different_voltages]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d0ebd176fc6c8eb6b9ba8d1a766808a44ac9777a307638e6a22714cdecbda7f9 +# +# +# +# +# +# +# +# Number of different temperature setpoints used in the experiment. +# +# +# +# +# Number of different voltage setpoints used in the experiment. +# +# +# +# +# Application definition for temperature-dependent IV curve measurements. +# +# In this application definition, times should be specified always together +# with an UTC offset. +# +# This is the application definition describing temperature dependent IV curve +# measurements. For this a temperature is set. After reaching the temperature, +# a voltage sweep is performed. For each voltage a current is measured. +# Then, the next desired temperature is set and an IV measurement is performed. +# +# +# +# +# +# +# +# +# +# +# Descriptive name or ideally (globally) unique persistent identifier. +# +# +# +# +# List of comma-separated elements from the periodic table +# that are contained in the sample. +# If the sample substance has multiple components, all +# elements from each component must be included in `atom_types`. +# +# The purpose of the field is to offer materials database systems an +# opportunity to parse the relevant elements without having to interpret +# these from the sample history or from other data sources. +# +# +# +# +# +# +# Describes an environment setup for a temperature-dependent IV measurement experiment. +# +# The temperature and voltage must be present as independently scanned controllers and +# the current sensor must also be present with its readings. +# +# +# +# +# +# +# +# +# This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. +# There should also be two more fields called temperature and voltage containing the setpoint values. +# There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension +# equal to the number of voltage setpoints. +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXlab_electro_chemo_mechanical_preparation.yaml b/contributed_definitions/nyaml/NXlab_electro_chemo_mechanical_preparation.yaml new file mode 100644 index 0000000000..bbc1a500c3 --- /dev/null +++ b/contributed_definitions/nyaml/NXlab_electro_chemo_mechanical_preparation.yaml @@ -0,0 +1,317 @@ +category: application +doc: | + Grinding and polishing of a sample using abrasives in a wet lab. + Manual procedures, electro-chemical, vibropolishing. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXlab_electro_chemo_mechanical_preparation(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXlab_electro_chemo_mechanical_preparation] + workflow_step_identifier(NX_UINT): + workflow_step_description: + SAMPLE(NXsample): + exists: ['min', '1', 'max', '1'] + USER(NXuser): + exists: ['min', '1', 'max', 'unbounded'] + + # (NXlab_grinding_machine): + grinding_machine(NXfabrication): + vendor: + model: + identifier: + exists: recommended + GRINDING_STEP(NXprocess): + doc: | + A preparation step performed by a human or a robot/automated system. + + # maybe a user per step as sometimes samples are prepared by more than + # one person or not each person performs all polishing steps + sequence_index(NX_POSINT): + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + abrasive_medium_carrier: + doc: | + Carrier/plate used on which the abrasive/(lubricant) mixture was applied. + + # enumeration: [plate] + # controlled vocabulary items + abrasive_medium: + doc: | + Medium on the abrasive_medium_carrier (cloth or grinding plate) + whereby material is abrasively weared. + + # enumeration: [SiC180] + # controlled vocabulary items or instance of chemical, need for free-text? + # also need for free-text in subsequent files? + lubricant: + doc: | + Lubricant + + # enumeration: [none, water, ethanol, oil] + # from a list of controlled vocabulary items, or instance of chemical + # etching/corrosive attack, tracking the environment, what can we + # learn from our colleagues within NFDI4Cat, NFDI4Chem, and NFDI-MatWerk? + rotation_control: + doc: | + Qualitative statement how the revelation of the machine was configured. + If the rotation was controlled manually, e.g. by turning knobs + choose manual and estimate the nominal average rotation. + If the rotation was controlled via choosing from a fixed set + of options offered by the machine choose fixed and + specify the nominal rotation. + If programmed use rotation_history (e.g. for automated/robot systems). + enumeration: [undefined, manual, fixed, programmed] + force_control: + doc: | + Qualitative statement how the (piston) force with which the sample + was pressed into/against the abrasive medium was controlled if at all. + If the force was controlled manually e.g. by turning knobs + choose manual and estimate nominal average force. + If the force was controlled via choosing from a fixed set + of options offered by the machine choose fixed and + specify the nominal force. + If programmed use force_history (e.g. for automated/robot systems). + enumeration: [undefined, manual, fixed, programmed] + time_control: + doc: | + Qualitative statement for how long (assuming regular uninterrupted) + preparation at the specified conditions the preparation step was + applied. + enumeration: [undefined, manual, fixed, programmed] + rotation(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Turns per unit time. + + # rotation_history(NX_NUMBER): + force(NX_NUMBER): + unit: NX_ANY + doc: | + Force exerted on the sample to press it into the abrasive. + + # force-history(NX_NUMBER): + time(NX_NUMBER): + unit: NX_TIME + doc: | + Seconds + removal: + doc: | + Qualitative statement how the material removal was characterized. + enumeration: [undefined, estimated, measured] + thickness_reduction(NX_NUMBER): + unit: NX_LENGTH + doc: | + How thick a layer was removed. + + # time_history(NX_NUMBER): + # SENSOR_SCAN(NXsensor_scan): + # electro-chemical preparation is nothing but an I(V) curve within + # a corrosive medium, eventually some wet lab steps have characteristics + # of pure grinding, mechanical polishing, or a mixture with corrosive + # attack + CLEANING_STEP(NXprocess): + doc: | + A preparation step performed by a human or a robot/automated system + with the aim to remove residual abrasive medium from the specimen surface. + sequence_index(NX_POSINT): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a2826c4a9cb1e0eb52d77a18d6ef8832462f14f6b96c118099419f8603362bac +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Grinding and polishing of a sample using abrasives in a wet lab. +# Manual procedures, electro-chemical, vibropolishing. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A preparation step performed by a human or a robot/automated system. +# +# +# +# +# +# +# +# Carrier/plate used on which the abrasive/(lubricant) mixture was applied. +# +# +# +# +# +# Medium on the abrasive_medium_carrier (cloth or grinding plate) +# whereby material is abrasively weared. +# +# +# +# +# +# Lubricant +# +# +# +# +# +# Qualitative statement how the revelation of the machine was configured. +# If the rotation was controlled manually, e.g. by turning knobs +# choose manual and estimate the nominal average rotation. +# If the rotation was controlled via choosing from a fixed set +# of options offered by the machine choose fixed and +# specify the nominal rotation. +# If programmed use rotation_history (e.g. for automated/robot systems). +# +# +# +# +# +# +# +# +# +# +# Qualitative statement how the (piston) force with which the sample +# was pressed into/against the abrasive medium was controlled if at all. +# If the force was controlled manually e.g. by turning knobs +# choose manual and estimate nominal average force. +# If the force was controlled via choosing from a fixed set +# of options offered by the machine choose fixed and +# specify the nominal force. +# If programmed use force_history (e.g. for automated/robot systems). +# +# +# +# +# +# +# +# +# +# +# Qualitative statement for how long (assuming regular uninterrupted) +# preparation at the specified conditions the preparation step was +# applied. +# +# +# +# +# +# +# +# +# +# +# Turns per unit time. +# +# +# +# +# +# Force exerted on the sample to press it into the abrasive. +# +# +# +# +# +# Seconds +# +# +# +# +# Qualitative statement how the material removal was characterized. +# +# +# +# +# +# +# +# +# +# How thick a layer was removed. +# +# +# +# +# +# +# A preparation step performed by a human or a robot/automated system +# with the aim to remove residual abrasive medium from the specimen surface. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXlab_sample_mounting.yaml b/contributed_definitions/nyaml/NXlab_sample_mounting.yaml new file mode 100644 index 0000000000..3963b841f5 --- /dev/null +++ b/contributed_definitions/nyaml/NXlab_sample_mounting.yaml @@ -0,0 +1,151 @@ +category: application +doc: | + Embedding of a sample in a medium for easing processability. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXlab_sample_mounting(NXobject): + (NXentry): + + # by default for appdefs the value of the exists keyword is required unless it is explicitly specified differently + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXlab_sample_mounting] + SAMPLE(NXsample): + exists: ['min', '1', 'max', '1'] + USER(NXuser): + exists: ['min', '1', 'max', 'unbounded'] + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + + # (NXlab_mounting_machine): + mounting_machine(NXfabrication): + vendor: + model: + identifier: + exists: recommended + mounting_method: + doc: | + Qualitative statement how the sample was mounted. + enumeration: [cold_mounting, hot_mounting] + embedding_medium: + doc: | + Type of material. + enumeration: [resin, epoxy] + electrical_conductivity(NX_FLOAT): + unit: NX_ANY + doc: | + Electrical conductivity of the embedding medium. + + # temperature control of the mounting (e.g. relevant when hot_mounting Al) + # cleaning procedures + # a descriptor of the shape of the specimen + # borrow from NXlab_thermo_mechanical_processing to document the external + # stimuli (eventually) applied during mounting + # temperature, mechanical, magnetic, electro-magnetic, are externally + # applied stimuli on the sample, can we use one master schema? + # e.g. one can even store NXcg_polyhedron_set and NXcg_face_list_data_structure + # instances to keep track of the geometry of specific instrument and how + # the samples were arranged in these + # key question is which steps has the sample experienced? + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1edd9800a540016328456efebddc4ba62635309c1b0a8d7722d35ac79279ff05 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Embedding of a sample in a medium for easing processability. +# +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Qualitative statement how the sample was mounted. +# +# +# +# +# +# +# +# +# Type of material. +# +# +# +# +# +# +# +# +# Electrical conductivity of the embedding medium. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXlens_em.yaml b/contributed_definitions/nyaml/NXlens_em.yaml new file mode 100644 index 0000000000..b64a786dba --- /dev/null +++ b/contributed_definitions/nyaml/NXlens_em.yaml @@ -0,0 +1,74 @@ +category: base +doc: | + Base class for an electro-magnetic lens or a compound lens. + + For :ref:`NXtransformations` the origin of the coordinate system is placed + in the center of the lens (its polepiece, pinhole, or another + point of reference). The origin should be specified in the :ref:`NXtransformations`. + + For details of electro-magnetic lenses in the literature + see e.g. `L. Reimer `_ +type: group +# more consolidation to harvest from a generic component base class +# with other research fields (MPES, XPS, OPT) could be useful +NXlens_em(NXobject): + type(NX_CHAR): + doc: | + Qualitative type of lens with respect to the number of pole pieces. + enumeration: [single, double, quadrupole, hexapole, octupole] + name(NX_CHAR): + doc: | + Given name, alias, colloquial, or short name for the lens. + For manufacturer names and identifiers use respective manufacturer fields. + # manufacturer_name: + # doc: | + # Name of the manufacturer who built/constructed the lens. + (NXfabrication): + # model: + # doc: | + # Hardware name, hash identifier, or serial number that was given by the + # manufacturer to identify the lens. + description(NX_CHAR): # NXidentifier + doc: | + Ideally an identifier, persistent link, or free text which + gives further details about the lens. + voltage(NX_NUMBER): + doc: | + Excitation voltage of the lens. + + For dipoles it is a single number. + For higher order multipoles, it is an array. + unit: NX_VOLTAGE + current(NX_NUMBER): + doc: | + Excitation current of the lens. + + For dipoles it is a single number. + For higher order multipoles, it is an array. + unit: NX_CURRENT + value(NX_NUMBER): + doc: | + This field should be used when the exact voltage or current of the lens + is not directly controllable as the control software of the microscope + does not enable or was not configured to display these values. + + In this case this value field should be used and the value + from the control software stored as is. + + Although this value does not document the exact physical voltage or + excitation, it can still give useful context to reproduce the lens setting, + which, provided a properly working instrument and software sets the lens + into a similar state to the technical level possible when no more information + is available physically or accessible legally. + unit: NX_ANY + \@depends_on(NX_CHAR): + doc: | + Specifies the position of the lens by pointing to the last transformation in the + transformation chain in the NXtransformations group. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the + location and geometry of the lens as a component in the instrument. + Typically, the components of a system should all be related relative to + each other and only one component should relate to the reference + coordinate system. diff --git a/contributed_definitions/nyaml/NXlens_opt.yaml b/contributed_definitions/nyaml/NXlens_opt.yaml new file mode 100644 index 0000000000..625aa9c40b --- /dev/null +++ b/contributed_definitions/nyaml/NXlens_opt.yaml @@ -0,0 +1,307 @@ +category: base +doc: | + Description of an optical lens. +symbols: + N_spectrum: | + Size of the wavelength array for which the refractive index of the material + is given. + N_spectrum_coating: | + Size of the wavelength array for which the refractive index of the coating + is given. + N_spectrum_RT: | + Size of the wavelength array for which the reflectance or transmission of + the lens is given. + +# A draft of a new base class describing an optical lens +# (Note: NXlens_em describes an electro-magnetic lens or a compound lens) +type: group +NXlens_opt(NXobject): + type: + doc: | + Type of the lens (e.g. concave, convex etc.). + enumeration: [biconcave, plano-concave, convexo-concave, biconvex, plano-convex, concavo-convex, Fresnel lens, other] + other_type: + doc: | + If you chose 'other' as type specify what it is. + chromatic(NX_BOOLEAN): + doc: | + Is it a chromatic lens? + lens_diameter(NX_NUMBER): + unit: NX_LENGTH + doc: | + Diameter of the lens. + substrate(NXsample): + doc: | + Properties of the substrate material of the lens. If the lens has a + coating specify the coating material and its properties in 'coating'. + substrate_material: + doc: | + Specify the substrate material of the lens. + substrate_thickness(NX_NUMBER): + unit: NX_LENGTH + doc: | + Thickness of the lens substrate at the optical axis. + index_of_refraction(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the lens material. Specify at given + wavelength (or energy, wavenumber etc.) values. + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + COATING(NXsample): + + # Used captial letters for COATING so that more than one can be defined if + # the lens has different coatings on the front and back side. + doc: | + If the lens has a coating describe the material and its properties. + Some basic information can be found e.g. [here] + (https://www.opto-e.com/basics/reflection-transmission-and-coatings). + If the back and front side of the lens are coated with different + materials, use separate COATING(NXsample) fields to describe the coatings + on the front and back side, respectively. For example: + coating_front(NXsample) and coating_back(NXsample). + coating_type: + doc: | + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + coating_material: + doc: | + Describe the coating material (e.g. MgF2). + coating_thickness(NX_NUMBER): + unit: NX_LENGTH + doc: | + Thickness of the coating. + index_of_refraction_coating(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum_coating]] + reflectance: + unit: NX_UNITLESS + doc: | + Reflectance of the lens at given spectral values. + dimensions: + rank: 1 + dim: [[1, N_spectrum_RT]] + transmission: + unit: NX_UNITLESS + doc: | + Transmission of the lens at given spectral values. + dimensions: + rank: 1 + dim: [[1, N_spectrum_RT]] + focal_length(NX_NUMBER): + exists: recommended + unit: NX_LENGTH + doc: | + Focal length of the lens on the front side (first value), i.e. where the + beam is incident, and on the back side (second value). + dimensions: + rank: 1 + dim: [[1, 2]] + curvature_radius_FACE(NX_NUMBER): + exists: recommended + unit: NX_LENGTH + doc: | + Curvature radius of the lens. + Instead of 'FACE' in the name of this field, the user is advised to + specify for which surface (e.g. front or back) the curvature is provided: + e.g. curvature_front or curvature_back. The front face is the surface on + which the light beam is incident, while the back face is the one from + which the light beam exits the lens. + Abbe_number(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Abbe number (or V-number) of the lens. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 691e29df6cdccccbeb03000ebbd435adb2c77135939ffb1d329d7da9d11c6539 +# +# +# +# +# +# +# +# +# Size of the wavelength array for which the refractive index of the material +# is given. +# +# +# +# +# Size of the wavelength array for which the refractive index of the coating +# is given. +# +# +# +# +# Size of the wavelength array for which the reflectance or transmission of +# the lens is given. +# +# +# +# +# Description of an optical lens. +# +# +# +# Type of the lens (e.g. concave, convex etc.). +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you chose 'other' as type specify what it is. +# +# +# +# +# Is it a chromatic lens? +# +# +# +# +# Diameter of the lens. +# +# +# +# +# Properties of the substrate material of the lens. If the lens has a +# coating specify the coating material and its properties in 'coating'. +# +# +# +# Specify the substrate material of the lens. +# +# +# +# +# Thickness of the lens substrate at the optical axis. +# +# +# +# +# Complex index of refraction of the lens material. Specify at given +# wavelength (or energy, wavenumber etc.) values. +# +# +# +# +# +# +# +# +# +# +# If the lens has a coating describe the material and its properties. +# Some basic information can be found e.g. [here] +# (https://www.opto-e.com/basics/reflection-transmission-and-coatings). +# If the back and front side of the lens are coated with different +# materials, use separate COATING(NXsample) fields to describe the coatings +# on the front and back side, respectively. For example: +# coating_front(NXsample) and coating_back(NXsample). +# +# +# +# Specify the coating type (e.g. dielectric, anti-reflection (AR), +# multilayer coating etc.). +# +# +# +# +# Describe the coating material (e.g. MgF2). +# +# +# +# +# Thickness of the coating. +# +# +# +# +# Complex index of refraction of the coating. Specify at given spectral +# values (wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# Reflectance of the lens at given spectral values. +# +# +# +# +# +# +# +# Transmission of the lens at given spectral values. +# +# +# +# +# +# +# +# Focal length of the lens on the front side (first value), i.e. where the +# beam is incident, and on the back side (second value). +# +# +# +# +# +# +# +# Curvature radius of the lens. +# Instead of 'FACE' in the name of this field, the user is advised to +# specify for which surface (e.g. front or back) the curvature is provided: +# e.g. curvature_front or curvature_back. The front face is the surface on +# which the light beam is incident, while the back face is the one from +# which the light beam exits the lens. +# +# +# +# +# Abbe number (or V-number) of the lens. +# +# +# diff --git a/contributed_definitions/nyaml/NXlockin.yaml b/contributed_definitions/nyaml/NXlockin.yaml new file mode 100644 index 0000000000..b59b69a916 --- /dev/null +++ b/contributed_definitions/nyaml/NXlockin.yaml @@ -0,0 +1,252 @@ +category: base +doc: | + Base classes definition for lock in devices. +type: group +NXlockin(NXobject): + hardware(NXfabrication): + doc: | + Hardware manufacturers and type of lockin amplifier. + (NXamplifier): + doc: | + By mixing the input signal (STS signal) with the modulated signal (such as Bias) + and comparing it with the reference signal, they are enhanced and the effects of + noise interference are reduced, resulting in more accurate measurements. + bias_divider: + doc: | + if Lock-in -- Bias Divider 1/10 or 1/100, Bias divider = + V(ref)/[V(ref)+V(input)] + modulation_status(NX_BOOLEAN): + doc: | + Switch the lock-in moulation on or off. + modulation_signal: + doc: | + A modulation signal (such as bias, current et.al.) is a periodic voltage signal, + usually applied to the surface of a sample, which serves to modify the physical + properties of the sample surface and generate weak AC current signals that can + be detected and analysed by instruments such as lock-in amplifiers. + + # (For bais modulate signal, it depands on the modulate type) + modulation_amplitude(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Sets the amplitude (in physical units of the modulated signal) of the sine + modulation. + modulation_frequency(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Sets the frequency of the sine modulation added to the signal to modulate. + demodulated_signal: + doc: | + The input signal (STS signal) will be demodulated, in order to determine the amplitude + and phase at the frequency set in the Frequency field or harmonics, such as current, + bias, et.al. + + # output (demodulated signal) characterisation (foreach channel, like demodulation, a separate sensor output, e.g. X,Y) + number_of_demodulator_channels(NX_NUMBER): + doc: | + The number of signals which will be demodulated. + low_pass(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) + hi_pass(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) + lp_filter_cutoff(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Sets the cut-off frequency of the low-pass filter (affects the displayed TC (s) + value) for D1. The filter is applied to the demodulated signals (X,Y). + lp_filter_order(NX_NUMBER): + doc: | + Order and cut-off frequency of the low-pass filter applied on the demodulated + signals (X,Y). Reducing the bandwidth or increasing the order reduces noise on + the demodulated signals, but will require longer settling and measurement times. + hp_filter_cutoff(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Sets the cut-off frequency of the high-pass filter (affects the displayed TC (s) + value) for D1. The filter is applied to the demodulated signals (X,Y). + hp_filter_order(NX_NUMBER): + doc: | + Order and cut-off frequency of the high-pass filter applied on the demodulation + signal of D!. This is used mainly to suppress a DC component of the demodulation + signal, which would lead to a component at modulation frequency in the + demodulated signals. + sync(NX_BOOLEAN): + doc: | + Switch on/off the Sync filter on the demodulated signals (X,Y) on or off. + (foreach DemodulatorChannels) + ref_phase_N(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Reference phase for the sine on the demodulated signal with respect to the + modulation signal. (foreach DemodulatorChannels) + integration_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the data are acquired and averaged. (for the input filter) + harmonic_order_N(NX_NUMBER): + doc: | + The order of the harmonic oscillation to detect on the demodulated signals. + (with respect to the modulation frequency) + sensitivity_factor(NX_NUMBER): + doc: | + Ratio of output signal amplitude to input signal amplitue (V/V). (input gain) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c73589fddbb7b57d065748d989ab0d3d9e421b9163f8a4b4ab305b1b18bf82a8 +# +# +# +# +# +# Base classes definition for lock in devices. +# +# +# +# Hardware manufacturers and type of lockin amplifier. +# +# +# +# +# By mixing the input signal (STS signal) with the modulated signal (such as Bias) +# and comparing it with the reference signal, they are enhanced and the effects of +# noise interference are reduced, resulting in more accurate measurements. +# +# +# +# +# if Lock-in -- Bias Divider 1/10 or 1/100, Bias divider = +# V(ref)/[V(ref)+V(input)] +# +# +# +# +# Switch the lock-in moulation on or off. +# +# +# +# +# A modulation signal (such as bias, current et.al.) is a periodic voltage signal, +# usually applied to the surface of a sample, which serves to modify the physical +# properties of the sample surface and generate weak AC current signals that can +# be detected and analysed by instruments such as lock-in amplifiers. +# +# +# +# +# +# Sets the amplitude (in physical units of the modulated signal) of the sine +# modulation. +# +# +# +# +# Sets the frequency of the sine modulation added to the signal to modulate. +# +# +# +# +# The input signal (STS signal) will be demodulated, in order to determine the amplitude +# and phase at the frequency set in the Frequency field or harmonics, such as current, +# bias, et.al. +# +# +# +# +# +# The number of signals which will be demodulated. +# +# +# +# +# Order and cut-off frequency of the low-pass filter applied on the demodulated +# signals (X,Y). Cut-off frq (low pass filter) (foreach DemodulatorChannels) +# +# +# +# +# Order and cut-off frequency of the high-pass filter applied on the demodulation +# signal. Cut-off frq (hi pass filter) (foreach DemodulatorChannels) +# +# +# +# +# Sets the cut-off frequency of the low-pass filter (affects the displayed TC (s) +# value) for D1. The filter is applied to the demodulated signals (X,Y). +# +# +# +# +# Order and cut-off frequency of the low-pass filter applied on the demodulated +# signals (X,Y). Reducing the bandwidth or increasing the order reduces noise on +# the demodulated signals, but will require longer settling and measurement times. +# +# +# +# +# Sets the cut-off frequency of the high-pass filter (affects the displayed TC (s) +# value) for D1. The filter is applied to the demodulated signals (X,Y). +# +# +# +# +# Order and cut-off frequency of the high-pass filter applied on the demodulation +# signal of D!. This is used mainly to suppress a DC component of the demodulation +# signal, which would lead to a component at modulation frequency in the +# demodulated signals. +# +# +# +# +# Switch on/off the Sync filter on the demodulated signals (X,Y) on or off. +# (foreach DemodulatorChannels) +# +# +# +# +# Reference phase for the sine on the demodulated signal with respect to the +# modulation signal. (foreach DemodulatorChannels) +# +# +# +# +# Time during which the data are acquired and averaged. (for the input filter) +# +# +# +# +# The order of the harmonic oscillation to detect on the demodulated signals. +# (with respect to the modulation frequency) +# +# +# +# +# Ratio of output signal amplitude to input signal amplitue (V/V). (input gain) +# +# +# diff --git a/contributed_definitions/nyaml/NXmagnetic_kicker.yaml b/contributed_definitions/nyaml/NXmagnetic_kicker.yaml new file mode 100644 index 0000000000..317325e62a --- /dev/null +++ b/contributed_definitions/nyaml/NXmagnetic_kicker.yaml @@ -0,0 +1,102 @@ +category: base +doc: | + definition for a magnetic kicker. +type: group +NXmagnetic_kicker(NXobject): + description(NX_CHAR): + doc: | + extended description of the kicker. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + timing(NX_FLOAT): + unit: NX_TIME + exists: ['min', '0', 'max', '1'] + doc: | + kicker timing as defined by ``description`` attribute + \@description: + type: NX_CHAR + set_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on supply. + read_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from supply. + value: + unit: NX_CURRENT + set_voltage(NX_FLOAT): + unit: NX_VOLTAGE + exists: ['min', '0', 'max', '1'] + doc: | + voltage set on supply. + read_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 34b7476f76592e9226269d3b02886646193836d024fce656135de8c230c8119c +# +# +# +# +# definition for a magnetic kicker. +# +# extended description of the kicker. +# +# +# define position of beamline element relative to production target +# +# +# kicker timing as defined by ``description`` attribute +# +# +# +# current set on supply. +# +# +# current read from supply. +# +# +# +# voltage set on supply. +# +# +# voltage read from supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXmanipulator.yaml b/contributed_definitions/nyaml/NXmanipulator.yaml new file mode 100644 index 0000000000..eea2d55b7e --- /dev/null +++ b/contributed_definitions/nyaml/NXmanipulator.yaml @@ -0,0 +1,398 @@ +category: base +doc: | + Extension of NXpositioner to include fields to describe the use of manipulators + in photoemission experiments. +type: group +NXmanipulator(NXobject): + name(NX_CHAR): + doc: | + Name of the manipulator. + description(NX_CHAR): + doc: | + A description of the manipulator. + type(NX_CHAR): + doc: | + Type of manipulator, Hexapod, Rod, etc. + cryostat(NXactuator): + doc: | + Cryostat for cooling the sample. + physical_quantity: + enumeration: [temperature] + (NXpid): + setpoint(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In case of a fixed or averaged cooling temperature, this is the scalar temperature setpoint. + It can also be a 1D array of temperature setpoints (without time stamps). + setpoint_log(NXlog): + value(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In the case of an experiment in which the temperature is changed and the setpoints are + recorded with time stamps, this is an array of length m of temperature setpoints. + temperature_sensor(NXsensor): + doc: | + Temperature sensor measuring the sample temperature. + measurement: + enumeration: [temperature] + value(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In case of a single or averaged temperature measurement, this is the scalar temperature measured + by the sample temperature sensor. It can also be a 1D array of measured temperatures + (without time stamps). + value_log(NXlog): + value(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In the case of an experiment in which the temperature changes and is recorded with time stamps, + this is an array of length m of temperatures. + sample_heater(NXactuator): + doc: | + Device to heat the sample. + physical_quantity: + enumeration: [temperature] + heater_power(NX_FLOAT): + unit: NX_POWER + doc: | + In case of a fixed or averaged heating power, this is the scalar heater power. + It can also be a 1D array of heater powers (without time stamps). + heater_power_log(NXlog): + value(NX_FLOAT): + unit: NX_POWER + doc: | + In the case of an experiment in which the heater power is changed and recorded with time stamps, + this is an array of length m of temperature setpoints. + (NXpid): + setpoint(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In case of a fixed or averaged temperature, this is the scalar temperature setpoint. + It can also be a 1D array of temperature setpoints (without time stamps). + setpoint_log(NXlog): + value(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + In the case of an experiment in which the temperature is changed and the setpoints are + recorded with time stamps, this is an array of length m of temperature setpoints. + drain_current_amperemeter(NXsensor): + doc: | + Amperemeter measuring the drain current of the sample and sample holder. + measurement: + enumeration: [current] + value(NX_FLOAT): + unit: NX_CURRENT + doc: | + In case of a single or averaged drain current measurement, this is the scalar drain current measured between + the sample and sample holder. It can also be an 1D array of measured currents (without time stamps). + value_log(NXlog): + value(NX_FLOAT): + unit: NX_CURRENT + doc: | + In the case of an experiment in which the current changes and is recorded with + time stamps, this is an array of length m of currents. + sample_bias_potentiostat(NXactuator): + doc: | + Actuator applying a voltage to sample and sample holder. + physical_quantity: + enumeration: [voltage] + (NXpid): + setpoint(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + In case of a fixed or averaged applied bias, this is the scalar voltage applied between + sample and sample holder. It can also be an 1D array of voltage setpoints (without time stamps). + setpoint_log(NXlog): + value(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + In the case of an experiment in which the bias is changed and the setpoints are + recorded with time stamps, this is an array of length m of voltage setpoints. + sample_bias_voltmeter(NXsensor): + doc: | + Sensor measuring the voltage applied to sample and sample holder. + measurement: + enumeration: [voltage] + value(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + In case of a single or averaged bias measurement, this is the scalar voltage measured between + sample and sample holder. It can also be an 1D array of measured voltages (without time stamps). + value_log(NXlog): + value(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + In the case of an experiment in which the bias changes and is recorded with + time stamps, this is an array of length m of voltages. + (NXactuator): + doc: | + Any additional actuator on the manipulator used to control an external + condition. + (NXsensor): + doc: | + Any additional sensors on the manipulator used to monitor an external condition. + (NXpositioner): + doc: | + Class to describe the motors that are used in the manipulator + depends_on(NX_CHAR): + doc: | + Refers to the last transformation specifying the positon of the manipulator in + the NXtransformations chain. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the manipulator as a component in the instrument. Conventions from + the NXtransformations base class are used. In principle, the McStas coordinate + system is used. The first transformation has to point either to another + component of the system or . (for pointing to the reference frame) to relate it + relative to the experimental setup. Typically, the components of a system should + all be related relative to each other and only one component should relate to + the reference coordinate system. + (NXfabrication): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 08d47f40a1d7fee3cd364f477c76cb02e60194cdcd1c00ff53d9b4e24d025ebd +# +# +# +# +# +# Extension of NXpositioner to include fields to describe the use of manipulators +# in photoemission experiments. +# +# +# +# Name of the manipulator. +# +# +# +# +# A description of the manipulator. +# +# +# +# +# Type of manipulator, Hexapod, Rod, etc. +# +# +# +# +# Cryostat for cooling the sample. +# +# +# +# +# +# +# +# +# +# In case of a fixed or averaged cooling temperature, this is the scalar temperature setpoint. +# It can also be a 1D array of temperature setpoints (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the temperature is changed and the setpoints are +# recorded with time stamps, this is an array of length m of temperature setpoints. +# +# +# +# +# +# +# +# Temperature sensor measuring the sample temperature. +# +# +# +# +# +# +# +# +# In case of a single or averaged temperature measurement, this is the scalar temperature measured +# by the sample temperature sensor. It can also be a 1D array of measured temperatures +# (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the temperature changes and is recorded with time stamps, +# this is an array of length m of temperatures. +# +# +# +# +# +# +# Device to heat the sample. +# +# +# +# +# +# +# +# +# In case of a fixed or averaged heating power, this is the scalar heater power. +# It can also be a 1D array of heater powers (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the heater power is changed and recorded with time stamps, +# this is an array of length m of temperature setpoints. +# +# +# +# +# +# +# In case of a fixed or averaged temperature, this is the scalar temperature setpoint. +# It can also be a 1D array of temperature setpoints (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the temperature is changed and the setpoints are +# recorded with time stamps, this is an array of length m of temperature setpoints. +# +# +# +# +# +# +# +# Amperemeter measuring the drain current of the sample and sample holder. +# +# +# +# +# +# +# +# +# In case of a single or averaged drain current measurement, this is the scalar drain current measured between +# the sample and sample holder. It can also be an 1D array of measured currents (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the current changes and is recorded with +# time stamps, this is an array of length m of currents. +# +# +# +# +# +# +# Actuator applying a voltage to sample and sample holder. +# +# +# +# +# +# +# +# +# +# In case of a fixed or averaged applied bias, this is the scalar voltage applied between +# sample and sample holder. It can also be an 1D array of voltage setpoints (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the bias is changed and the setpoints are +# recorded with time stamps, this is an array of length m of voltage setpoints. +# +# +# +# +# +# +# +# Sensor measuring the voltage applied to sample and sample holder. +# +# +# +# +# +# +# +# +# In case of a single or averaged bias measurement, this is the scalar voltage measured between +# sample and sample holder. It can also be an 1D array of measured voltages (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the bias changes and is recorded with +# time stamps, this is an array of length m of voltages. +# +# +# +# +# +# +# Any additional actuator on the manipulator used to control an external +# condition. +# +# +# +# +# Any additional sensors on the manipulator used to monitor an external condition. +# +# +# +# +# Class to describe the motors that are used in the manipulator +# +# +# +# +# Refers to the last transformation specifying the positon of the manipulator in +# the NXtransformations chain. +# +# +# +# +# Collection of axis-based translations and rotations to describe the location and +# geometry of the manipulator as a component in the instrument. Conventions from +# the NXtransformations base class are used. In principle, the McStas coordinate +# system is used. The first transformation has to point either to another +# component of the system or . (for pointing to the reference frame) to relate it +# relative to the experimental setup. Typically, the components of a system should +# all be related relative to each other and only one component should relate to +# the reference coordinate system. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXmatch_filter.yaml b/contributed_definitions/nyaml/NXmatch_filter.yaml new file mode 100644 index 0000000000..d42df74cdc --- /dev/null +++ b/contributed_definitions/nyaml/NXmatch_filter.yaml @@ -0,0 +1,95 @@ +category: base +doc: | + Settings of a filter to select or remove entries based on their value. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_values: | + How many different match values does the filter specify. +type: group +NXmatch_filter(NXobject): + method: + doc: | + Meaning of the filter: + Whitelist specifies which entries with said value to include. + Entries with all other values will be filtered out. + + Blacklist specifies which entries with said value to exclude. + Entries with all other values will be included. + enumeration: [whitelist, blacklist] + match(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of values to filter according to method. For example if the filter + specifies [1, 5, 6] and method is whitelist, only entries with values + matching 1, 5 or 6 will be processed. All other entries will be filtered + out. + dimensions: + rank: 1 + dim: [[1, n_values]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 658011327c521407a34c26bfa9eae3d21d763c4d975f4a8d514fcedf8ed18b36 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# How many different match values does the filter specify. +# +# +# +# +# Settings of a filter to select or remove entries based on their value. +# +# +# +# Meaning of the filter: +# Whitelist specifies which entries with said value to include. +# Entries with all other values will be filtered out. +# +# Blacklist specifies which entries with said value to exclude. +# Entries with all other values will be included. +# +# +# +# +# +# +# +# +# Array of values to filter according to method. For example if the filter +# specifies [1, 5, 6] and method is whitelist, only entries with values +# matching 1, 5 or 6 will be processed. All other entries will be filtered +# out. +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXmpes.yaml b/contributed_definitions/nyaml/NXmpes.yaml new file mode 100644 index 0000000000..8636d08e62 --- /dev/null +++ b/contributed_definitions/nyaml/NXmpes.yaml @@ -0,0 +1,1640 @@ +category: application +doc: | + This is the most general application definition for multidimensional + photoelectron spectroscopy. + + Groups and fields are named according to the + `ISO 18115-1:2023`_ specification as well as the `IUPAC Recommendations 2020`_. + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _IUPAC Recommendations 2020: https://doi.org/10.1515/pac-2019-0404 +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays + n_transmission_function: | + Number of data points in the transmission function. +type: group +NXmpes(NXobject): + (NXentry): + definition: + \@version: + enumeration: [NXmpes] + title: + start_time(NX_DATE_TIME): + doc: | + Datetime of the start of the measurement. + Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, + otherwise the local time zone is assumed per ISO8601. + end_time(NX_DATE_TIME): + exists: recommended + doc: | + Datetime of the end of the measurement. + Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, + otherwise the local time zone is assumed per ISO8601. + method: + exists: recommended + doc: | + Name of the experimental method. + + If applicable, this name should match the terms given by `Clause 11`_ of + the `ISO 18115-1:2023`_ specification. + + Examples include: + * X-ray photoelectron spectroscopy (XPS) + * angle-resolved X-ray photoelectron spectroscopy (ARXPS) + * ultraviolet photoelectron spectroscopy (UPS) + * angle-resolved photoelectron spectroscopy (ARPES) + * hard X-ray photoemission spectroscopy (HAXPES) + * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) + * photoelectron emission microscopy (PEEM) + * electron spectroscopy for chemical analysis (ESCA) + * time-resolved angle-resolved X-ray photoelectron spectroscopy (trARPES) + * spin-resolved angle-resolved X-ray photoelectron spectroscopy (spin-ARPES) + * momentum microscopy + + .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html + .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 + (NXuser): + exists: recommended + doc: | + Contact information of at least the user of the instrument or the investigator + who performed this experiment. Adding multiple users if relevant is recommended. + name: + doc: | + Name of the user. + affiliation: + doc: | + Name of the affiliation of the user at the time when the experiment was + performed. + (NXinstrument): + doc: + - | + Description of the MPES spectrometer and its individual parts. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.58 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 + energy_resolution(NXresolution): + exists: recommended + doc: + - | + Overall energy resolution of the MPES instrument + - | + xref: + spec: ISO 18115-1:2023 + term: 10.7 ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.7 + - | + xref: + spec: ISO 18115-1:2023 + term: 10.24 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 + physical_quantity: + enumeration: [energy] + type: + exists: recommended + resolution(NX_FLOAT): + unit: NX_ENERGY + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + source_TYPE(NXsource): + exists: recommended + doc: | + A source used to generate a beam. Properties refer strictly to parameters of the + source, not of the output beam. For example, the energy of the source is not the + optical power of the beam, but the energy of the electron beam in a synchrotron + or similar. + + Note that the uppercase notation in source_TYPE means that multiple sources can + be provided. For example, in pump-probe experiments, it is possible to have both + a `source_probe` and a `source_pump` + type: + enumeration: [Synchrotron X-ray Source, Rotating Anode X-ray, Fixed Tube X-ray, UV Laser, Free-Electron Laser, Optical Laser, UV Plasma Source, Metal Jet X-ray, HHG laser, UV lamp, Monochromatized electron source, other] + type_other: + exists: optional + doc: | + Specification of type, may also go to name. + name: + exists: recommended + probe: + exists: optional + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + associated_beam(NXbeam): + doc: | + The beam emitted by this source. + Should be named with the same appendix, e.g., + for `source_probe` it should refer to `beam_probe`. + Refers to the same concept as /NXentry/NXinstrument/beam_TYPE + and may be linked. + beam_TYPE(NXbeam): + doc: | + Properties of the photon beam at a given location. + Should be named with the same appendix as source_TYPE, e.g., + for `source_probe` it should refer to `beam_probe`. + distance(NX_NUMBER): + unit: NX_LENGTH + exists: recommended + doc: | + Distance between the point where the current NXbeam instance is evaluating + the beam properties and the point where the beam interacts with the sample. + For photoemission, the latter is the point where the the centre of the beam + touches the sample surface. + incident_energy(NX_FLOAT): + unit: NX_ENERGY + incident_energy_spread(NX_NUMBER): + exists: recommended + unit: NX_ENERGY + incident_polarization(NX_NUMBER): + exists: recommended + unit: NX_ANY + extent(NX_FLOAT): + exists: recommended + associated_source(NXsource): + exists: recommended + doc: | + The source that emitted this beam. + Should be named with the same appendix, e.g., + for `beam_probe` it should refer to `source_probe`. + Refers to the same concept as /NXentry/NXinstrument/source_TYPE + and may be linked. + Should be specified if an associated source exists. + (NXelectronanalyser): + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + description: + work_function(NX_FLOAT): + unit: NX_ENERGY + exists: recommended + energy_resolution(NXresolution): + exists: recommended + type: + exists: recommended + physical_quantity: + enumeration: [energy] + resolution(NX_FLOAT): + fast_axes: + exists: recommended + slow_axes: + exists: recommended + transmission_function(NXdata): + exists: optional + (NXcollectioncolumn): + scheme: + doc: | + Scheme of the electron collection column. + enumeration: [angular dispersive, spatial dispersive, momentum dispersive, non-dispersive] + lens_mode: + exists: recommended + projection: + exists: recommended + angular_acceptance(NX_FLOAT): + exists: optional + spatial_acceptance(NX_FLOAT): + exists: optional + field_aperture(NXaperture): + exists: optional + doc: | + The size and position of the field aperture inserted in the column. To add + additional or other apertures use the APERTURE group of NXcollectioncolumn. + contrast_aperture(NXaperture): + exists: optional + doc: | + The size and position of the contrast aperture inserted in the column. To add + additional or other apertures use the APERTURE group of NXcollectioncolumn. + iris(NXaperture): + exists: optional + doc: | + Size, position and shape of the iris inserted in the column. + + The iris is an aperture in the lens with a variable diameter which can reduce the number of + electrons entering the analyzer. + + To add additional or other slits use the APERTURE group of NXcollectioncolumn. + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + (NXenergydispersion): + scheme: + enumeration: [tof, hemispherical, double hemispherical, cylindrical mirror, display mirror, retarding grid] + pass_energy(NX_FLOAT): + unit: NX_ENERGY + energy_scan_mode: + exists: recommended + entrance_slit(NXaperture): + exists: optional + doc: | + Size, position and shape of the entrance slit in dispersive analyzers. + + To add additional or other slits use the APERTURE group of NXenergydispersion. + exit_slit(NXaperture): + exists: optional + doc: | + Size, position and shape of the exit slit in dispersive analyzers. + + To add additional or other slits use the APERTURE group of NXenergydispersion. + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + (NXdetector): + amplifier_type: + exists: recommended + doc: | + Type of electron amplifier in the first amplification step. + enumeration: [MCP, channeltron] + detector_type: + exists: recommended + doc: | + Description of the detector type. + enumeration: [DLD, Phosphor+CCD, Phosphor+CMOS, ECMOS, Anode, Multi-anode] + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + exists: recommended + raw_data(NXdata): + exists: recommended + doc: | + Contains the raw data collected by the detector before calibration. + The data which is considered raw might change from experiment to experiment + due to hardware pre-processing of the data. + This field ideally collects the data with the lowest level of processing + possible. + + The naming of fields should follow a convention to ensure compatibility. + It is recommend to use the following field names: + + - **pixel_x**: Detector pixel in x direction. + - **pixel_y**: Detector pixel in y direction. + - **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). + - **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). + - **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). + - **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). + - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). + Unit category: NX_ANGLE + - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_ANGLE + - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) + Unit category: NX_LENGTH + - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_LENGTH + - **delay**: Calibrated delay time. Unit category: NX_TIME (s). + - **polarization_angle**: Linear polarization angle of the incoming or + outgoing beam. + Unit category: NX_ANGLE (° or rad) + - **ellipticity**: Ellipticity of the incoming or outgoing beam. + Unit category: NX_ANGLE (° or rad) + - **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT + - **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. + - **external_AXIS**: Describes an axis which is coming from outside the detectors scope. + \@signal: + enumeration: [raw] + raw(NX_NUMBER): + doc: | + Raw data before calibration. + (NXmanipulator): + exists: optional + doc: | + Manipulator for positioning of the sample. + temperature_sensor(NXsensor): + exists: recommended + name: + exists: recommended + measurement: + enumeration: [temperature] + type: + exists: optional + value(NX_FLOAT): + sample_heater(NXactuator): + exists: optional + name: + exists: recommended + physical_quantity: + enumeration: [temperature] + type: + exists: optional + heater_power(NX_FLOAT): + (NXpid): + exists: recommended + setpoint(NX_FLOAT): + exists: recommended + cryostat(NXactuator): + exists: optional + name: + exists: recommended + physical_quantity: + enumeration: [temperature] + type: + exists: optional + (NXpid): + setpoint(NX_FLOAT): + exists: recommended + drain_current_amperemeter(NXsensor): + exists: optional + name: + exists: recommended + measurement: + enumeration: [current] + type: + exists: optional + value(NX_FLOAT): + sample_bias_voltmeter(NXsensor): + exists: recommended + name: + exists: recommended + measurement: + enumeration: [voltage] + type: + exists: optional + value(NX_FLOAT): + sample_bias_potentiostat(NXactuator): + exists: recommended + name: + exists: recommended + physical_quantity: + enumeration: [voltage] + type: + exists: optional + (NXpid): + exists: recommended + setpoint(NX_FLOAT): + exists: recommended + device_information(NXfabrication): + exists: recommended + vendor: + exists: recommended + model: + exists: recommended + identifier: + pressure_gauge(NXsensor): + exists: recommended + doc: | + Device to measure the gas pressure around the sample. + name: + exists: recommended + measurement: + enumeration: [pressure] + type: + exists: optional + value(NX_FLOAT): + unit: NX_PRESSURE + doc: | + In case of a single or averaged gas pressure measurement, this is the scalar gas pressure around + the sample. It can also be an 1D array of measured pressures (without time stamps). + value_log(NXlog): + exists: optional + value(NX_NUMBER): + unit: NX_PRESSURE + doc: | + In the case of an experiment in which the gas pressure changes and is recorded, + this is an array of length m of gas pressures. + flood_gun(NXactuator): + exists: optional + doc: | + Device to bring low-energy electrons to the sample for charge neutralization + name: + exists: recommended + physical_quantity: + enumeration: [current] + type: + exists: optional + current(NX_FLOAT): + exists: recommended + unit: NX_CURRENT + doc: | + In case of a fixed or averaged electron current, this is the scalar current. + It can also be an 1D array of output current (without time stamps). + current_log(NXlog): + exists: optional + value(NX_NUMBER): + unit: NX_CURRENT + doc: | + In the case of an experiment in which the electron current is changed and + recorded with time stamps, this is an array of length m of current setpoints. + (NXprocess): + exists: recommended + doc: | + Document an event of data processing, reconstruction, or analysis for this data. + Describe the appropriate axis calibrations for your experiment using one or more + of the following NXcalibrations + energy_calibration(NXcalibration): + exists: optional + doc: | + Calibration event on the energy axis. + + For XPS, the calibration should ideally be performed according to + `ISO 15472:2010`_ specification. + + .. _ISO 15472:2010: https://www.iso.org/standard/74811.html + calibrated_axis(NX_FLOAT): + exists: recommended + doc: | + This is the calibrated energy axis to be used for data plotting. + angular_calibration(NXcalibration): + exists: optional + calibrated_axis(NX_FLOAT): + exists: recommended + doc: | + This is the calibrated angular axis to be used for data plotting. + spatial_calibration(NXcalibration): + exists: optional + calibrated_axis(NX_FLOAT): + exists: recommended + doc: | + This is the calibrated spatial axis to be used for data plotting. + momentum_calibration(NXcalibration): + exists: optional + calibrated_axis(NX_FLOAT): + exists: recommended + doc: | + This is the momentum axis to be used for data plotting. + energy_referencing(NXcalibration): + exists: optional + doc: + - | + For energy referencing, the measured energies are corrected for the charging potential + (i.e., the electrical potential of the surface region of an insulating sample, caused by + irradiation) such that those energies correspond to a sample with no surface charge. + Usually, the energy axis is adjusted by shifting all energies uniformally until one + well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.74 ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 + level(NXelectron_level): + exists: recommended + doc: | + Electronic core or valence level that was used for the calibration. + reference_peak: + doc: | + Reference peak that was used for the calibration. + + For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level + binding_energy(NX_FLOAT): + exists: recommended + doc: + - | + The binding energy (in units of eV) that the specified emission line appeared at, + after adjusting the binding energy scale. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.16_ ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + offset(NX_FLOAT): + exists: recommended + doc: | + Offset between measured binding energy and calibrated binding energy of the + emission line. + calibrated_axis(NX_FLOAT): + exists: recommended + doc: | + This is the calibrated energy axis to be used for data plotting. + + This should link to /entry/data/energy. + transmission_correction(NXcalibration): + exists: optional + doc: | + In the transmission correction, each intensity measurement for electrons of a given + kinetic energy is multiplied by the corresponding value in the relative_intensity + field of the transmission_function. This calibration procedure is used to account for + the different tranmsission efficiencies when using different lens modes. + transmission_function(NXdata): + exists: recommended + doc: | + Transmission function of the electron analyser. + + The transmission function (TF) specifies the detection efficiency for electrons of + different kinetic energy passing through the electron analyser. + This can be a link to /entry/instrument/electronanalyser/transmission_function. + \@signal: + enumeration: [relative_intensity] + \@axes: + enumeration: [kinetic_energy] + kinetic_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Kinetic energy values + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + relative_intensity(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Relative transmission efficiency for the given kinetic energies + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + (NXsample): + name: + (NXsubstance): + exists: recommended + doc: | + For samples containing a single pure substance. For mixtures use the + NXsample_component_set and NXsample_component group in NXsample instead. + molecular_formula_hill: + exists: recommended + doc: | + The chemical formula of the sample (using CIF conventions). + atom_types: + exists: recommended + doc: | + List of comma-separated elements from the periodic table + that are contained in the sample. + If the sample substance has multiple components, all + elements from each component must be included in `atom_types`. + physical_form: + exists: recommended + situation: + exists: recommended + enumeration: [vacuum, inert atmosphere, oxidising atmosphere, reducing atmosphere] + sample_history(NXsample_history): + exists: recommended + doc: | + A set of activities that occurred to the sample prior to/during photoemission + experiment. + sample_preparation(NXphysical_process): + exists: recommended + doc: | + Details about the sample preparation for the MPES experiment (e.g. UHV cleaving, + in-situ growth, sputtering/annealing, etc.). + start_time(NX_DATE_TIME): + end_time(NX_DATE_TIME): + exists: recommended + method: + exists: recommended + doc: | + Details about the method of sample preparation before the MPES experiment. + temperature(NXenvironment): + exists: recommended + doc: | + Sample temperature (either controlled or just measured). + temperature_sensor(NXsensor): + doc: | + Temperature sensor measuring the sample temperature. + This should be a link to /entry/instrument/manipulator/temperature_sensor. + sample_heater(NXactuator): + exists: optional + doc: | + Device to heat the sample. + This should be a link to /entry/instrument/manipulator/sample_heater. + cryostat(NXactuator): + exists: optional + doc: | + Cryostat for cooling the sample. + This should be a link to /entry/instrument/manipulator/cryostat. + gas_pressure(NXenvironment): + exists: recommended + doc: | + Gas pressure surrounding the sample. + pressure_gauge(NXsensor): + doc: | + Gauge measuring the gas pressure. + + This should be a link to /entry/instrument/pressure_gauge. + bias(NXenvironment): + exists: recommended + doc: + - | + Bias of the sample with respect to analyser ground. + - | + xref: + spec: ISO 18115-1:2023 + term: 8.41 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:8.41 + voltmeter(NXsensor): + doc: | + Sensor measuring the applied voltage. + + This should be a link to /entry/instrument/manipulator/sample_bias_voltmeter. + potentiostat(NXactuator): + exists: optional + doc: | + Actuator applying a voltage to sample and sample holder. + + This should be a link to /entry/instrument/manipulator/sample_bias_potentiostat. + drain_current(NXenvironment): + exists: optional + doc: | + Drain current of the sample and sample holder. + amperemeter(NXsensor): + doc: | + Amperemeter measuring the drain current of the sample and sample holder. + + This should be a link to /entry/instrument/manipulator/drain_current_amperemeter. + flood_gun_current(NXenvironment): + exists: optional + doc: | + Current of low-energy electrons to the sample for charge neutralization. + flood_gun(NXactuator): + doc: | + Flood gun creating a current of low-energy electrons. + + This should be a link to /entry/instrument/flood_gun. + data(NXdata): + doc: | + The default NXdata field containing a view on the measured data. + This NXdata field contains a collection of the main relevant fields (axes). + In NXmpes, it is required to provide an energy axis. + If you want to provide additional views on your data, you can additionally use + the generic NXdata group of NXentry. + The other data fields inside this NXdata group should be named according to conventions + to ensure compatibility. We recommened the following field names + for common data fields: + + - **kx**: Calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). + - **ky**: Calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). + - **kz**: Calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). + - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). + Unit category: NX_ANGLE + - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_ANGLE + - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) + Unit category: NX_LENGTH + - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) + Unit category: NX_LENGTH + - **delay**: Calibrated delay time. Unit category: NX_TIME (s). + - **polarization_angle**: Linear polarization angle of the incoming or + outgoing beam. This could be a link to + /entry/instrument/beam/incident_polarization_angle or + /entry/instrument/beam/final_polarization_angle if they exist. + Unit category: NX_ANGLE (° or rad) + - **ellipticity**: Ellipticity of the incoming or outgoing beam. + Could be a link to /entry/instrument/beam/incident_ellipticity or + /entry/instrument/beam/final_ellipticity if they exist. + Unit category: NX_ANGLE (° or rad) + \@signal: + enumeration: [data] + data(NX_NUMBER): + unit: NX_ANY + doc: | + Represents a measure of one- or more-dimensional photoemission counts, where the + varied axis may be for example energy, momentum, spatial coordinate, pump-probe + delay, spin index, temperature, etc. The axes traces should be linked to the + actual encoder position in NXinstrument or calibrated axes in NXprocess. + energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Calibrated energy axis. + + This could be a link to either + /entry/process/energy_calibration/calibrated_axis or + /entry/process/energy_correction/calibrated_axis. + \@type: + type: NX_CHAR + doc: | + The energy can be either stored as kinetic or as binding energy. + enumeration: + kinetic: + doc: + - | + Calibrated kinetic energy axis. + - | + In case the kinetic energy axis is referenced to the Fermi level :math:`E_F` + (e.g., in entry/process/energy_referencing), kinetic energies :math:`E` are + provided as :math:`E-E_F`. + - | + xref: + spec: ISO 18115-1:2023 + term: 3.35 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 + binding: + doc: + - | + Calibrated binding energy axis. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.16 + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + \@energy_indices: + exists: recommended + \@energy_depends: + type: NX_CHAR + exists: recommended + doc: | + The energy can be dispersed according to different strategies. ``energy_depends`` points to + the path of a field defining the calibrated axis on which the energy axis depends. + + For example: + @energy_depends: 'entry/process/energy_calibration' + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# a126a001ba56386d0e4cb7731e73e48921961202950cf53ecc142cc30fa79728 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays +# +# +# +# Number of data points in the transmission function. +# +# +# +# +# This is the most general application definition for multidimensional +# photoelectron spectroscopy. +# +# Groups and fields are named according to the +# `ISO 18115-1:2023`_ specification as well as the `IUPAC Recommendations 2020`_. +# +# .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html +# .. _IUPAC Recommendations 2020: https://doi.org/10.1515/pac-2019-0404 +# +# +# +# +# +# +# +# +# +# +# +# Datetime of the start of the measurement. +# Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, +# otherwise the local time zone is assumed per ISO8601. +# +# +# +# +# Datetime of the end of the measurement. +# Should be a ISO8601 date/time stamp. It is recommended to add an explicit time zone, +# otherwise the local time zone is assumed per ISO8601. +# +# +# +# +# Name of the experimental method. +# +# If applicable, this name should match the terms given by `Clause 11`_ of +# the `ISO 18115-1:2023`_ specification. +# +# Examples include: +# * X-ray photoelectron spectroscopy (XPS) +# * angle-resolved X-ray photoelectron spectroscopy (ARXPS) +# * ultraviolet photoelectron spectroscopy (UPS) +# * angle-resolved photoelectron spectroscopy (ARPES) +# * hard X-ray photoemission spectroscopy (HAXPES) +# * near ambient pressure X-ray photoelectron spectroscopy (NAPXPS) +# * photoelectron emission microscopy (PEEM) +# * electron spectroscopy for chemical analysis (ESCA) +# * time-resolved angle-resolved X-ray photoelectron spectroscopy (trARPES) +# * spin-resolved angle-resolved X-ray photoelectron spectroscopy (spin-ARPES) +# * momentum microscopy +# +# .. _ISO 18115-1:2023: https://www.iso.org/standard/74811.html +# .. _Clause 11: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:sec:11 +# +# +# +# +# Contact information of at least the user of the instrument or the investigator +# who performed this experiment. Adding multiple users if relevant is recommended. +# +# +# +# Name of the user. +# +# +# +# +# Name of the affiliation of the user at the time when the experiment was +# performed. +# +# +# +# +# +# Description of the MPES spectrometer and its individual parts. +# +# This concept is related to term `12.58`_ of the ISO 18115-1:2023 standard. +# +# .. _12.58: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.58 +# +# +# +# Overall energy resolution of the MPES instrument +# +# This concept is related to term `10.7 ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _10.7 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.7 +# +# This concept is related to term `10.24`_ of the ISO 18115-1:2023 standard. +# +# .. _10.24: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:10.24 +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# A source used to generate a beam. Properties refer strictly to parameters of the +# source, not of the output beam. For example, the energy of the source is not the +# optical power of the beam, but the energy of the electron beam in a synchrotron +# or similar. +# +# Note that the uppercase notation in source_TYPE means that multiple sources can +# be provided. For example, in pump-probe experiments, it is possible to have both +# a `source_probe` and a `source_pump` +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Specification of type, may also go to name. +# +# +# +# +# +# +# +# +# +# +# +# The beam emitted by this source. +# Should be named with the same appendix, e.g., +# for `source_probe` it should refer to `beam_probe`. +# Refers to the same concept as /NXentry/NXinstrument/beam_TYPE +# and may be linked. +# +# +# +# +# +# Properties of the photon beam at a given location. +# Should be named with the same appendix as source_TYPE, e.g., +# for `source_probe` it should refer to `beam_probe`. +# +# +# +# Distance between the point where the current NXbeam instance is evaluating +# the beam properties and the point where the beam interacts with the sample. +# For photoemission, the latter is the point where the the centre of the beam +# touches the sample surface. +# +# +# +# +# +# +# +# +# The source that emitted this beam. +# Should be named with the same appendix, e.g., +# for `beam_probe` it should refer to `source_probe`. +# Refers to the same concept as /NXentry/NXinstrument/source_TYPE +# and may be linked. +# Should be specified if an associated source exists. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Scheme of the electron collection column. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The size and position of the field aperture inserted in the column. To add +# additional or other apertures use the APERTURE group of NXcollectioncolumn. +# +# +# +# +# The size and position of the contrast aperture inserted in the column. To add +# additional or other apertures use the APERTURE group of NXcollectioncolumn. +# +# +# +# +# Size, position and shape of the iris inserted in the column. +# +# The iris is an aperture in the lens with a variable diameter which can reduce the number of +# electrons entering the analyzer. +# +# To add additional or other slits use the APERTURE group of NXcollectioncolumn. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Size, position and shape of the entrance slit in dispersive analyzers. +# +# To add additional or other slits use the APERTURE group of NXenergydispersion. +# +# +# +# +# Size, position and shape of the exit slit in dispersive analyzers. +# +# To add additional or other slits use the APERTURE group of NXenergydispersion. +# +# +# +# +# +# +# +# +# +# +# +# Type of electron amplifier in the first amplification step. +# +# +# +# +# +# +# +# +# Description of the detector type. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Contains the raw data collected by the detector before calibration. +# The data which is considered raw might change from experiment to experiment +# due to hardware pre-processing of the data. +# This field ideally collects the data with the lowest level of processing +# possible. +# +# The naming of fields should follow a convention to ensure compatibility. +# It is recommend to use the following field names: +# +# - **pixel_x**: Detector pixel in x direction. +# - **pixel_y**: Detector pixel in y direction. +# - **energy**: (Un)calibrated energy (kinetic or binding energy). Unit category: NX_ENERGY (e.g., eV). +# - **kx**: (Un)calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). +# - **ky**: (Un)calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). +# - **kz**: (Un)calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). +# - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). +# Unit category: NX_ANGLE +# - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +# Unit category: NX_ANGLE +# - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) +# Unit category: NX_LENGTH +# - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +# Unit category: NX_LENGTH +# - **delay**: Calibrated delay time. Unit category: NX_TIME (s). +# - **polarization_angle**: Linear polarization angle of the incoming or +# outgoing beam. +# Unit category: NX_ANGLE (° or rad) +# - **ellipticity**: Ellipticity of the incoming or outgoing beam. +# Unit category: NX_ANGLE (° or rad) +# - **time_of_flight**: Total time of flight. Unit category: NX_TIME_OF_FLIGHT +# - **time_of_flight_adc**: Time-of-flight values, analog-to-digital converted. +# - **external_AXIS**: Describes an axis which is coming from outside the detectors scope. +# +# +# +# +# +# +# +# +# Raw data before calibration. +# +# +# +# +# +# +# +# Manipulator for positioning of the sample. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Device to measure the gas pressure around the sample. +# +# +# +# +# +# +# +# +# +# +# In case of a single or averaged gas pressure measurement, this is the scalar gas pressure around +# the sample. It can also be an 1D array of measured pressures (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the gas pressure changes and is recorded, +# this is an array of length m of gas pressures. +# +# +# +# +# +# +# Device to bring low-energy electrons to the sample for charge neutralization +# +# +# +# +# +# +# +# +# +# +# In case of a fixed or averaged electron current, this is the scalar current. +# It can also be an 1D array of output current (without time stamps). +# +# +# +# +# +# In the case of an experiment in which the electron current is changed and +# recorded with time stamps, this is an array of length m of current setpoints. +# +# +# +# +# +# +# +# Document an event of data processing, reconstruction, or analysis for this data. +# Describe the appropriate axis calibrations for your experiment using one or more +# of the following NXcalibrations +# +# +# +# Calibration event on the energy axis. +# +# For XPS, the calibration should ideally be performed according to +# `ISO 15472:2010`_ specification. +# +# .. _ISO 15472:2010: https://www.iso.org/standard/74811.html +# +# +# +# This is the calibrated energy axis to be used for data plotting. +# +# +# +# +# +# +# This is the calibrated angular axis to be used for data plotting. +# +# +# +# +# +# +# This is the calibrated spatial axis to be used for data plotting. +# +# +# +# +# +# +# This is the momentum axis to be used for data plotting. +# +# +# +# +# +# For energy referencing, the measured energies are corrected for the charging potential +# (i.e., the electrical potential of the surface region of an insulating sample, caused by +# irradiation) such that those energies correspond to a sample with no surface charge. +# Usually, the energy axis is adjusted by shifting all energies uniformally until one +# well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. +# +# This concept is related to term `12.74 ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _12.74 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 +# +# +# +# Electronic core or valence level that was used for the calibration. +# +# +# +# +# Reference peak that was used for the calibration. +# +# For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level +# +# +# +# +# The binding energy (in units of eV) that the specified emission line appeared at, +# after adjusting the binding energy scale. +# +# This concept is related to term `12.16_ ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _12.16_ ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 +# +# +# +# +# Offset between measured binding energy and calibrated binding energy of the +# emission line. +# +# +# +# +# This is the calibrated energy axis to be used for data plotting. +# +# This should link to /entry/data/energy. +# +# +# +# +# +# In the transmission correction, each intensity measurement for electrons of a given +# kinetic energy is multiplied by the corresponding value in the relative_intensity +# field of the transmission_function. This calibration procedure is used to account for +# the different tranmsission efficiencies when using different lens modes. +# +# +# +# Transmission function of the electron analyser. +# +# The transmission function (TF) specifies the detection efficiency for electrons of +# different kinetic energy passing through the electron analyser. +# This can be a link to /entry/instrument/electronanalyser/transmission_function. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Kinetic energy values +# +# +# +# +# +# +# +# Relative transmission efficiency for the given kinetic energies +# +# +# +# +# +# +# +# +# +# +# +# +# For samples containing a single pure substance. For mixtures use the +# NXsample_component_set and NXsample_component group in NXsample instead. +# +# +# +# The chemical formula of the sample (using CIF conventions). +# +# +# +# +# +# List of comma-separated elements from the periodic table +# that are contained in the sample. +# If the sample substance has multiple components, all +# elements from each component must be included in `atom_types`. +# +# +# +# +# +# +# +# +# +# +# +# +# +# A set of activities that occurred to the sample prior to/during photoemission +# experiment. +# +# +# +# Details about the sample preparation for the MPES experiment (e.g. UHV cleaving, +# in-situ growth, sputtering/annealing, etc.). +# +# +# +# +# +# Details about the method of sample preparation before the MPES experiment. +# +# +# +# +# +# +# Sample temperature (either controlled or just measured). +# +# +# +# Temperature sensor measuring the sample temperature. +# This should be a link to /entry/instrument/manipulator/temperature_sensor. +# +# +# +# +# Device to heat the sample. +# This should be a link to /entry/instrument/manipulator/sample_heater. +# +# +# +# +# Cryostat for cooling the sample. +# This should be a link to /entry/instrument/manipulator/cryostat. +# +# +# +# +# +# Gas pressure surrounding the sample. +# +# +# +# Gauge measuring the gas pressure. +# +# This should be a link to /entry/instrument/pressure_gauge. +# +# +# +# +# +# Bias of the sample with respect to analyser ground. +# +# This concept is related to term `8.41`_ of the ISO 18115-1:2023 standard. +# +# .. _8.41: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:8.41 +# +# +# +# Sensor measuring the applied voltage. +# +# This should be a link to /entry/instrument/manipulator/sample_bias_voltmeter. +# +# +# +# +# Actuator applying a voltage to sample and sample holder. +# +# This should be a link to /entry/instrument/manipulator/sample_bias_potentiostat. +# +# +# +# +# +# Drain current of the sample and sample holder. +# +# +# +# Amperemeter measuring the drain current of the sample and sample holder. +# +# This should be a link to /entry/instrument/manipulator/drain_current_amperemeter. +# +# +# +# +# +# Current of low-energy electrons to the sample for charge neutralization. +# +# +# +# Flood gun creating a current of low-energy electrons. +# +# This should be a link to /entry/instrument/flood_gun. +# +# +# +# +# +# +# The default NXdata field containing a view on the measured data. +# This NXdata field contains a collection of the main relevant fields (axes). +# In NXmpes, it is required to provide an energy axis. +# If you want to provide additional views on your data, you can additionally use +# the generic NXdata group of NXentry. +# The other data fields inside this NXdata group should be named according to conventions +# to ensure compatibility. We recommened the following field names +# for common data fields: +# +# - **kx**: Calibrated x axis in k-space. Unit category: NX_ANY (e.g., 1/Angström). +# - **ky**: Calibrated y axis in k-space. Unit category: NX_ANY (1/Angström). +# - **kz**: Calibrated z axis in k-space. Unit category: NX_ANY (1/Angström). +# - **angular0**: Fast-axis angular coordinate (or second slow axis if angularly integrated). +# Unit category: NX_ANGLE +# - **angular1**: Slow-axis angular coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +# Unit category: NX_ANGLE +# - **spatial0**: Fast-axis spatial coordinate (or second slow axis if spatially integrated) +# Unit category: NX_LENGTH +# - **spatial1**: Slow-axis spatial coordinate (or second fast axis if simultaneously dispersed in 2 dimensions) +# Unit category: NX_LENGTH +# - **delay**: Calibrated delay time. Unit category: NX_TIME (s). +# - **polarization_angle**: Linear polarization angle of the incoming or +# outgoing beam. This could be a link to +# /entry/instrument/beam/incident_polarization_angle or +# /entry/instrument/beam/final_polarization_angle if they exist. +# Unit category: NX_ANGLE (° or rad) +# - **ellipticity**: Ellipticity of the incoming or outgoing beam. +# Could be a link to /entry/instrument/beam/incident_ellipticity or +# /entry/instrument/beam/final_ellipticity if they exist. +# Unit category: NX_ANGLE (° or rad) +# +# +# +# +# +# +# +# +# Represents a measure of one- or more-dimensional photoemission counts, where the +# varied axis may be for example energy, momentum, spatial coordinate, pump-probe +# delay, spin index, temperature, etc. The axes traces should be linked to the +# actual encoder position in NXinstrument or calibrated axes in NXprocess. +# +# +# +# +# Calibrated energy axis. +# +# This could be a link to either +# /entry/process/energy_calibration/calibrated_axis or +# /entry/process/energy_correction/calibrated_axis. +# +# +# +# The energy can be either stored as kinetic or as binding energy. +# +# +# +# +# Calibrated kinetic energy axis. +# +# In case the kinetic energy axis is referenced to the Fermi level :math:`E_F` +# (e.g., in entry/process/energy_referencing), kinetic energies :math:`E` are +# provided as :math:`E-E_F`. +# +# This concept is related to term `3.35`_ of the ISO 18115-1:2023 standard. +# +# .. _3.35: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:3.35 +# +# +# +# +# Calibrated binding energy axis. +# +# This concept is related to term `12.16`_ of the ISO 18115-1:2023 standard. +# +# .. _12.16: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 +# +# +# +# +# +# +# +# +# The energy can be dispersed according to different strategies. ``energy_depends`` points to +# the path of a field defining the calibrated axis on which the energy axis depends. +# +# For example: +# @energy_depends: 'entry/process/energy_calibration' +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXms.yaml b/contributed_definitions/nyaml/NXms.yaml new file mode 100644 index 0000000000..888c6a90c2 --- /dev/null +++ b/contributed_definitions/nyaml/NXms.yaml @@ -0,0 +1,461 @@ +category: application +doc: | + Application definition, spatiotemporal characterization of a microstructure. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_b: | + Number of boundaries of the bounding box or primitive to domain. + n_p: | + Number of parameter required for the chosen orientation parameterization. + c: | + Number of texture components identified. + +# key points to keep in mind when thinking about a general enough description for coarse-graining systems of atoms into +# so-called microstructural features of interest for which we may store also thermodynamic properties or other feature-specific descriptors +# several viewpoints how to coarse-grain are equally justified: grains are useful when there are crystallites with adjoining interfaces and # none, or only some statistical populations of defects and/or some spatially-well defined defects inside these +# however, if grains are build almost only from defects like dislocation walls, it might no longer be useful to define the grains +# as a well identifiable region whose majority volume shows long-range atomic periodicity (so that defining an orientation makes) sense. +# one could then rather describe the set of defects. Alternatively one could describe a material volume by sampling individual so-called +# material points (e.g. in continuum-scale plasticity models) or describe the material volume really from the atoms up +# but there are many terms used in materials engineering which people may want to distinguish which stand however between the scales e.g. +# lattice curvature, this is jargon with some truth in it but curvature has to be build from atoms and defects need to build the curvature +# dislocations are another good example where different research questions demand differently granularized descriptions e.g. +# average density, total line length, per character, per family, line length, curvature, jog, kink density, +# coarse-grainable structural motifs in the dislocation core, atomic structure +# also different scales one would like to distinguish as this is relevant when defects couple/show spatiotemporal correlations +# to specific mechanisms (e.g. phonons) or when defect affect the properties of other defects +# ambiguous choices: is the grain boundary part of the grain or is it an own defect? +# i.e. can/should we store grains as childs of their grain boundary set vs the interface the childs of the grains? +# Depending on the use case we need to have a flexible description which can address a continuum of descriptors: +# important is that one can logically map different features +# Length scale of homogeneity: With the reality of a multi-parameter space of all possible methods and effects and +# different external stimuli applied for real materials, simulations in computational materials science typically focus +# their analysis on a few individual, spatiotemporally constrained effects and boundary conditions for which the simulation +# is formulated, useful, interpretable, and comparable to experiment. +# Data structures for multi-scale materials modeling IMM/ICME are currently diverse because they reflect the above-mentioned needs +# and different views which researchers have on their simulations e.g. DFT (time, length-scale, which electronic effects) +# RVE annealing phenomena at the micrometer scale (pressure, temperature, length scale, interactions considered or not) +# Some regions are well separated spatially (although it can be non-trivial to quantify the distance in a multi-dim parameter space) +# Some simulations are cross-scale (classical MD at the cutting edge with micrometer crystal plasticity microsecond and/or annealing at +# ns time scale) MD with classical vs abinitio-informed potential for studying evolution of mechanisms and phenomena at different length scales +type: group +NXms(NXobject): + (NXentry): + \@version: + doc: | + An at least as strong as SHA256 hashvalue of the file + that specifies the application definition. + + # enumeration: [sha_256_hash] + definition: + doc: | + NeXus NXDL schema to which this file conforms. + enumeration: [NXms] + workflow_identifier: + doc: | + Ideally, a (globally) unique persistent identifier + for referring to this experiment or computer simulation. + + The identifier is usually defined/issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments to e.g. proposals. + workflow_description: + exists: optional + doc: | + Free-text description about the workflow (experiment/analysis/simulation). + + Users are strongly advised to detail the sample history in the + respective field and fill rather as completely as possible the fields + of this application definition rather than write details about the + experiment into this free-text description field. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the characterization started. + end_time(NX_DATE_TIME): + exists: recommended + doc: | + ISO 8601 time code with local time zone offset to UTC included + when the characterization ended. + PROGRAM(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program_name: + \@version: + experiment_or_simulation: + doc: | + Specify if the (characterization) results/data of this instance of an + application definition are based on the results of a simulation or the + results of a post-processing of measured data to describe + a microstructure. + + The term microstructure is used to describe the spatial arrangement of + crystal defects inside a sample/specimen without demanding necessarily + that this structure is mainly at the micron length scale. + Nanostructure and macrostructure are close synonyms. + Material architecture is a narrow synonym. + + Given that microstructure simulations nowadays more and more consider + the atomic arrangement, this application definition can also be used + to describe features at the scale of atoms. + enumeration: [experiment, simulation] + USER(NXuser): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Contact information and eventually details of at least one person + involved in creating this result. This can be the principle investigator + who performed this experiment. Adding multiple users if relevant is recommended. + name: + doc: | + Given (first) name and surname of the user. + affiliation: + exists: recommended + doc: | + Name of the affiliation of the user at the point in time + when the experiment was performed. + address: + exists: recommended + doc: | + Postal address of the affiliation. + email: + exists: recommended + doc: | + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + orcid: + exists: recommended + doc: | + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific service + should also be written in orcid_platform + orcid_platform: + exists: recommended + doc: | + Name of the OrcID or ResearcherID where the account + under orcid is registered. + telephone_number: + exists: optional + doc: | + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + role: + exists: recommended + doc: | + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope. Student, postdoc, principle investigator, guest + are common examples. + social_media_name: + exists: optional + doc: | + Account name that is associated with the user in social media platforms. + social_media_platform: + exists: optional + doc: | + Name of the social media platform where the account + under social_media_name is registered. + specimen(NXsample): + + # NEW ISSUE: inject the conclusion from the discussion with Andrea + # according to SAMPLE.yaml 0f8df14 2022/06/15 + name: + doc: | + Descriptive name or ideally (globally) unique persistent identifier. + + # sample_history: + # doc: | + # Ideally, a reference to the location of or a (globally) unique + # persistent identifier of e.g. another file which should document + # ideally as many details as possible of the material, its + # microstructure, and its thermo-chemo-mechanical processing/ + # preparation history. + # preparation_date(NX_DATE_TIME): + # doc: | + # ISO 8601 time code with local time zone offset to UTC information + # when the specimen was prepared. + (NXdata): + exists: optional + doc: | + Hard link to a location in the hierarchy of the NeXus file + where the data for default plotting are stored. + (NXcoordinate_system_set): + doc: | + Container to hold different coordinate systems conventions. + A least a right-handed Cartesian coordinate system with base vectors + named x, y, and z has to be specified. Each base vector of the + coordinate system should be described with an NXtransformations instance. + TRANSFORMATIONS(NXtransformations): + exists: ['min', '3', 'max', 'unbounded'] + conventions(NXem_conventions_ebsd): + rotation_conventions(NXprocess): + three_dimensional_rotation_handedness: + rotation_convention: + euler_angle_convention: + axis_angle_convention: + orientation_parameterization_sign_convention: + processing_reference_frame(NXprocess): + reference_frame_type: + xaxis_direction: + xaxis_alias: + yaxis_direction: + yaxis_alias: + zaxis_direction: + zaxis_alias: + origin: + sample_reference_frame(NXprocess): + reference_frame_type: + xaxis_direction: + yaxis_direction: + zaxis_direction: + origin: + ROI_SET(NXcg_roi_set): + exists: ['min', '1', 'max', 'unbounded'] + + # however for solitary unit models (i.e. ensembles of volume elements/simulation domains) and for replica methods + # we may need more than one domain + # the volume element is not called representative because for what a volume element is representative is a matter of + # interpretation (fundamentally this is an assumption) and can differ for different descriptors + doc: | + The simulated or characterized material volume element aka domain. + At least one instance of geometry required either NXcg_grid, + NXcg_polyhedron_set, or NXcg_point_set. This geometry group needs + to contain details about the boundary conditions. + grid(NXcg_grid): + exists: optional + + # specific application definitions can use these fields to specialize + point_set(NXcg_point_set): + exists: optional + polyhedron_set(NXcg_polyhedron_set): + exists: optional + boundary(NXcg_polyhedron_set): + exists: optional + doc: | + A boundary to the volume element. + Either an instance of NXcg_hexahedron_set or of NXcg_ellipsoid_set. + + # a good example for a general bounding box description for such a grids of triclinic cells + # https://docs.lammps.org/Howto_triclinic.html NXcg_hexahedron_set because can be a parallelepiped + number_of_boundaries(NX_POSINT): + unit: NX_UNITLESS + doc: | + How many distinct boundaries are distinguished. Value required equal to n_b. + boundaries: + doc: | + Name of the boundaries. E.g. left, right, front, back, bottom, top, + dimensions: + rank: 1 + dim: [[1, n_b]] + boundary_conditions(NX_UINT): + unit: NX_UNITLESS + doc: | + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + dimensions: + rank: 1 + dim: [[1, n_b]] + snapshot_set(NXms_snapshot_set): + doc: | + Collection of microstructural data observed/simulated. + identifier_offset(NX_UINT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate + if the identifiers are expected to start from 1 (referred to as + Fortran-/Matlab-) or from 0 (referred to as C-, Python-style index + notation) respectively. + + # essentially NXmonitor instances for evolution of ensemble summary statistics + evolution(NXprocess): + exists: optional + doc: | + Summary quantities which are the result of some post-processing of + the snapshot data (averaging, integrating, interpolating). + Frequently used descriptors from continuum mechanics and thermodynamics + can be used here. A few examples are given. Each descriptor is currently + modelled as an instance of an NXprocess because it is relevant to + understand how the descriptors are computed. + temperature(NXprocess): + exists: optional + pressure(NXprocess): + exists: optional + stress(NXprocess): + exists: optional + strain(NXprocess): + exists: optional + deformation_gradient(NXprocess): + exists: optional + magnetic_field(NXprocess): + exists: optional + electric_field(NXprocess): + exists: optional + + # time-resolved results for individual snapshots + # virtually all computer simulations and all experiments always probe + # snapshots + MS_SNAPSHOT(NXms_snapshot): + time(NX_NUMBER): + unit: NX_TIME + doc: | + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + iteration(NX_UINT): + unit: NX_UNITLESS + doc: | + Iteration or increment counter. + + # optional places to store the grid for instance if it changes + grid(NXcg_grid): + exists: optional + polyhedron_set(NXcg_polyhedron_set): + exists: optional + point_set(NXcg_point_set): + exists: optional + + # homogenization: + # constituent: + # constitutive: + # ROI(NXcg_roi_set): #multiple rois, for each geometry, connectivity/topology, cellType... + # see that the materialpoint that is tracked conceptually in tools like DAMASK is a ROI (which is currently scale-invariant), isnt a coarse-graining of atom configurations a homogenization + # several "results" homogenized quantities at (eventually different length scales + # continuum-scale view thermodynamic(NXview) + # mechanical + # damage + # thermal + # composition + MS_FEATURE_SET(NXms_feature_set): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Conceptually distinguished object/feature in the ROI/ + system with some relevance. Instances of NXms_feature_set can + be nested to build a hierarchy of logically-related objects. + + A typical example for MD simulations is to have one + ms_feature_set for the atoms which is the parent to another + ms_feature_set for monomers/molecules/proteins which is then the + parent to another ms_feature_set for the secondary, another feature_set + for the tertiary, and the parent for another feature_set for the + quaternary structure. + + Another typical example from materials engineering is to have + one ms_feature_set for crystals (grains/phases) which serves as + the parent to another ms_feature_set for interfaces between these + crystals which then is the parent for another ms_feature_set to + describe the triple junctions which is then the parent for the + quadruple/higher-order junctions between which connect the + triple lines. + + Another example from discrete dislocation dynamics could be to + have one ms_feature_set for the dislocations (maybe separate + sets for each dislocation type or family) which are then + parents to other ms_feature_set which describe junctions between + dislocations or features along the dislocation line network. + + # respective application definitions based on NXms should add and + # specialize + odf(NXprocess): + exists: optional + doc: | + Details about the orientation distribution function + within the entire domain. + computation_method: + doc: | + With which method was the ODF approximated? + + # add approximation parameter + texture_index(NX_NUMBER): + exists: optional + unit: NX_ANY + doc: | + TO BE DEFINED + texture_strength(NX_NUMBER): + exists: optional + unit: NX_ANY + doc: | + TO BE DEFINED + volume_statistics(NXcollection): + exists: optional + doc: | + Collection of texture components commonly referred to. + TRANSFORMATIONS(NXtransformations): + doc: | + Reference to or definition of a coordinate system with + which the definitions are interpretable. + parameterization: + enumeration: [bunge-euler (ZXZ), quaternion] + orientation(NX_NUMBER): + unit: NX_ANY + doc: | + Parameterized orientations. + dimensions: + rank: 2 + dim: [[1, c], [2, n_p]] + name: + doc: | + Name of each texture component, e.g. Cube, Dillamore, Y. + dimensions: + rank: 1 + dim: [[1, c]] + integration_radius(NX_NUMBER): + unit: NX_ANGLE + doc: | + The portion of orientation space integrated over + to compute the volume fraction. + dimensions: + rank: 1 + dim: [[1, c]] + volume_fraction(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + The volume fraction of each texture component. + dimensions: + rank: 1 + dim: [[1, c]] + + # a grain-boundary character distribution + # is again a spatial correlation statistics, GBCD can be understood like an ODF in that the entire surface Of a grain boundary (interface) network is partitioned into regions between grains in specific disorientation relationships, and boundary plane inclination so that one can again ask for the "texture" i.e. which fraction of the area network is of specific disorientation and nominal plane inclination relationship + modf(NXprocess): + exists: optional + doc: | + Details about the disorientation distribution function + within the entire domain. + gbcd(NXprocess): + exists: optional + doc: | + Details about the grain boundary character distribution + within the entire domain. + + # add descriptions for the state of each cell + # e.g. values of phase field variables if desired + temperature(NXprocess): + exists: optional + pressure(NXprocess): + exists: optional + stress(NXprocess): + exists: optional + strain(NXprocess): + exists: optional + deformation_gradient(NXprocess): + exists: optional + magnetic_field(NXprocess): + exists: optional + electric_field(NXprocess): + exists: optional + recrystallization_kinetics(NXprocess): + exists: optional + grain_size_distribution(NXprocess): + exists: optional + recrystallization_front(NXprocess): + exists: optional diff --git a/contributed_definitions/nyaml/NXms_feature_set.yaml b/contributed_definitions/nyaml/NXms_feature_set.yaml new file mode 100644 index 0000000000..cc7aceda67 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_feature_set.yaml @@ -0,0 +1,528 @@ +category: base +doc: | + Set of topological/spatial features in materials build from other features. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + Dimensionality + c: | + Cardinality/number of members/features in the feature set. + n_type_dict: | + Number of types in the dictionary of human-readable types of features. + n_parent_ids: | + Total number of parent identifier. +# NXms_feature_set can be used e.g. as groups inside instances of NXms_snapshot +# for an MD simulation each timestep is such snapshot all snapshot for a set +# which is the parent group that has all these NXms_snapshot instances as childs +# time_stamp: # simulated, physical +# Thea, Joseph, Lauri, Dinga (TJLD) just for comparison for each group and field to what this would map in their model for the MDTutorial 2 +type: group +NXms_feature_set(NXobject): + # TJLD: this class represents a generalization of AtomGroups + # TJLD: one such for atoms(NXms_feature_set) + # TJLD: one such for atom_groups(NXms_feature_set) + # TJLD: but not one for every molecule, i.e. all molecules and how their atoms with ids are related to atoms ids is concatenated + # TJLD: clearly there are two possibilities: either concatenate or make one NXms_feature_set for each molecule or component in the topology hierarchy + # TJLD: however the here proposed design generalizes the arbitrary (microstructural) features and computational geometry based coarse-grained representations + \@depends_on(NX_CHAR): + # TJLD: not required it is currently assumed that features are always build from atoms and this relation is shown using their ids, integers on [0, n_atoms-1] + doc: | + Name (or link?) to another NXms_feature_set which defines features what are + assumed as the parents/super_features of all members in this feature set. + If depends_on is set to "." or this attribute is not defined in an instance + of this application definition, assume that this feature_set instance + represents the root feature_set of the feature tree/graph. + # the design of this base class makes it possible to have Joseph's suggestion + # but it has the additional benefit that as it defines the set one also + # bundle the description for all features at this hierarchy level into combined + # arrays to make the eventual storage of this for instances with millions of features + # more efficient as in the current design each molecule would again be a group + # and having millions of groups comes with e.g. HDF5 with substantial overlap + # I faced this when storing grains from micro-scale continuum crystal growth simulations + # TJLD: is_molecule(NX_BOOLEAN): not used, could however be added in an appdef which uses instances of NXms_feature_set + # TJLD: the key point we can use NXms_feature_set in the same way as currently TJLD use atoms and atoms/atom_groups/molecule0, */molecule1, ... + # but with the additional benefit of a much richer geometrical description and the details about the uncertainty of these descriptions + # I can also imagine that materials engineers e.g. can reuse NXms_feature_set in an application definition by just then naming + # their group e.g. grains(NXms_feature_set) and use in the application definition either only the (material point), interface network, or volumetric description + dimensionality(NX_POSINT): + # TJLD: not needed because they assume everything is 3d + doc: | + What is the best matching description how dimensional the feature is. + enumeration: [1, 2, 3] + cardinality(NX_UINT): + # TJLD: equivalent to the number of AtomGroups class instance childs + doc: | + How many features/members are in this set? + unit: NX_UNITLESS + type_dict_keyword(NX_CHAR): + # TJLD: equivalent to the controlled vocabulary term monomer or molecule, i.e. label + # TJLD: but with the difference that in this NeXus design here different features can take different roles + # TJLD: and do not conceptually have to be atoms, alternatively one could also create an NXms_interface_set which + # TJLD: inherits from NXms_feature_set but would need to have no dimensionality + doc: | + The keywords of the dictionary of human-readable types of features. + Using terms from a community-agreed upon controlled vocabulary, e.g. + atom, solute, vacancy, monomer, molecule, anti-site, crowd_ion, + quadruple junction, triple line, disconnection, dislocation, + kink, jog, stacking_fault, homo_phase_boundary, hetero_phase_boundary, + surface, thermal_groove_root, precipitate, dispersoid, pore, crack + is recommended. + dim: (n_type_dict,) + type_dict_value(NX_INT): + # TJLD: equivalent to the AtomGroups index + doc: | + The integer identifier used to resolve of which type each feature is, + i.e. the values of the dictionary of human-readable types of features. + unit: NX_UNITLESS + dim: (n_type_dict,) + number_of_parent_identifier(NX_INT): + doc: | + For each feature in the set specify the associated number of identifier + to parent features as are resolvable via depends_on. + This array enables to compute the array interval from which details for + specific features can be extracted as if they would be stored in an own + group. + unit: NX_UNITLESS + dim: (c,) + parent_identifier(NX_INT): + doc: | + Concatenated array of parent identifier for each feature (in the sequence) + according to identifier and how the identifier of features in the here + described feature set are defined (implicitly from 0, to c-1 or via explicit + identifier. + unit: NX_UNITLESS + dim: (n_parent_ids,) + # description of the geometry of the features + # MK::how can be define that inside lines(NXprocess) we assure that there is either no geometry or only one geometry but then this geometry can be either an NXcg_polyline_set or NXcg_spline_set? + # the key problem is that at least for an implementation in HDF5 we are not allowed to have two groups named geometry even if their attributes are different because + # HDF5 implements no conceptual understanding of the relations between elements in the underlying graph which holds the data, these elements are either attributes, fields, groups, all of which + # end up as links + identifier_offset(NX_INT): + doc: | + Integer which specifies the first index to be used for distinguishing + features. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate if the + identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) + or from 0 (referred to as C-, Python-style index notation) respectively. + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Integer used to distinguish features for explicit indexing. + unit: NX_UNITLESS + dim: (c,) + points(NXprocess): + # TJLD: this design here is different, TJLD give atom positions only (at least as of now) for the root of an object + # TJLD: while all higher-order features that are connected through their assumed topology just refer to the atoms in the root + # TJLD: via their IDs, TJLD design is ideal for systems build from atoms but would create unnecessary copies for higher-dimensional-type features + # TJLD: in fact initially I also thought it is useful to create an NXms_dislocation_set, and an NXms_atom_set but overall these are just + # specializations of NXms_feature_set. Instead I like the key approach in TJLD which is to nest instances of the same class in TJLD's case AtomGroups + # but here NXms_feature_set instances + doc: | + Assumptions and parameter to arrive at geometric primitives + to locate zero-dimensional/point-(like) features which are + discretized/represented by points. + geometry(NXcg_point_set): + uncertainty(NXprocess): + doc: | + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + lines(NXprocess): + # TJLD: not conceptualized, see comments for points and what the benefit of using NeXus would be + doc: | + Assumptions and parameters to arrive at geometric primitives + to locate one-dimensional/line-like features which are + discretized by polylines. + # MK::geometry(NXcg_spline_set) + geometry(NXcg_polyline_set): + uncertainty(NXprocess): + doc: | + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + interfaces(NXprocess): + doc: | + Assumptions and parameters to arrive at geometric primitives + to locate two-dimensional/interface features which are + discretized by triangulated surface meshes. + # MK::geometry(NXcg_nurbs_set): + geometry(NXcg_triangle_set): + uncertainty(NXprocess): + doc: | + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + volumes(NXprocess): + doc: | + Assumptions and parameters to arrive at geometric primitives + to locate three-dimensional/volumetric features which are + discretized by triangulated surface meshes of polyhedra. + # MK::geometry(NXcg_nurbs_set): + geometry(NXcg_polyhedron_set): + uncertainty(NXprocess): + doc: | + Assumptions, parameters, and details how positional uncertainty + of the geometry is quantified. + # Sandor and Markus agree that how trajectories are extracted should be stored in instances of NXprocess at respective places + # Sandor suggested it can be useful to also describe how one could transform system-specific atom positions from the system-focused coordinate system to a molecule- or atom-focused local coordinate system + + # how to map results from MD simulations was already sketched by the comments from TJLD + # but ones more here stating it explicitly + # atoms(NXms_feature_set): + # no \@depends_on: as everything is build spatiotemporally coarse-grained from the sampled atom positions and/or their trajectories + # dislocations(NXms_feature_set): + # \@depends_on: <>/atoms + # is trivially the same case as was described already for the DDD simulation + + # how to map from DREAM.3D to NXms_feature_set + # material_points(NXms_feature_set): # material points can be voxels of a grid (which should be specified with an instance of NXcg_grid) or real material points + # no \@depends_on: "." required or value can be "." as material_points are considered the root + # grains(NXms_feature_set): + # \@depends_on: <>/material_points + # boundaries(NXms_feature_set): + # \@depends_on: <>/grains + # triple_lines(NXms_feature_set): + # \@depends_on: <>/boundaries + # quadruple_junctions(NXms_feature_set): + # \@depends_on: <>/triple_lines + + # how to map from e.g. DDD codes like ParaDis to NXms_feature_set + # dislocations(NXms_feature_set): + # either all types of dislocations are specified via the type_dict dictionary or by making several named instances of NXms_feature_set classes, i.e. groups + # multi_junctions(NXms_feature_set): + # \@depends_on: <>/dislocations + + # how to describe e.g. 3D cracks + # cracks(NXms_feature_set): + # you can use volumes and interfaces to describe explicitly the 3D geometry + # alternatively you can + + # how to map from an MTex v5.8.2 @grain2d object + # grains.poly is a cell of list of vertex indices referring to grains.V + # grains.id + # grains.phaseId to which phase does each grain belong why is it different to phase? + # grains.prop (mean and gos) + # grains.boundary + # F, list of minmax-hashed vertex indices building the facet + # grainId, list of pairs of grains incident at facet special value 0 marks grains with boundary contact + # ebsdId, list of interpolated scan points incident + # phaseId, homo/heterophase information list of pairs of phases incident at facet + # V, list of facet support vertices, the support of the polyline + # midPoint, list of facet midPoint coordinates + # direction 3d vector (V(F(i, 1),:) - V(F(i, 2), :)) and with z = 0 and then normalized, so not respecting winding order + # grains.triplePoints + # id, list of vertex id for the location of the triple point referring to grains.V or grains.boundary.V as these lists are equivalent + # grainid, triplet of adjoining grain ids + # boundaryId, triplet of adjoining boundary facets from grains.boundary.F + # nextVertexId, next vertex hit when walking from the triple point + # phaseId, is it a triple point between homophases or heterophases + # V, list of x, y coordinates for the triple points + # angles, trivial nextVertexId to triplePoint vertex angles + # grains(NXms_feature_set): + # boundaries(NXms_feature_set): + # alternatively one NXms_feature_set for homophase boundaries + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 15f205ec24e25536f17046f9540798e889bf21046d3e1e2a63ab9434e3f6ffa9 +# +# +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Dimensionality +# +# +# +# +# Cardinality/number of members/features in the feature set. +# +# +# +# +# Number of types in the dictionary of human-readable types of features. +# +# +# +# +# Total number of parent identifier. +# +# +# +# +# Set of topological/spatial features in materials build from other features. +# +# +# +# +# +# Name (or link?) to another NXms_feature_set which defines features what are +# assumed as the parents/super_features of all members in this feature set. +# If depends_on is set to "." or this attribute is not defined in an instance +# of this application definition, assume that this feature_set instance +# represents the root feature_set of the feature tree/graph. +# +# +# +# +# +# +# What is the best matching description how dimensional the feature is. +# +# +# +# +# +# +# +# +# +# +# +# How many features/members are in this set? +# +# +# +# +# +# The keywords of the dictionary of human-readable types of features. +# Using terms from a community-agreed upon controlled vocabulary, e.g. +# atom, solute, vacancy, monomer, molecule, anti-site, crowd_ion, +# quadruple junction, triple line, disconnection, dislocation, +# kink, jog, stacking_fault, homo_phase_boundary, hetero_phase_boundary, +# surface, thermal_groove_root, precipitate, dispersoid, pore, crack +# is recommended. +# +# +# +# +# +# +# +# +# The integer identifier used to resolve of which type each feature is, +# i.e. the values of the dictionary of human-readable types of features. +# +# +# +# +# +# +# +# For each feature in the set specify the associated number of identifier +# to parent features as are resolvable via depends_on. +# This array enables to compute the array interval from which details for +# specific features can be extracted as if they would be stored in an own +# group. +# +# +# +# +# +# +# +# Concatenated array of parent identifier for each feature (in the sequence) +# according to identifier and how the identifier of features in the here +# described feature set are defined (implicitly from 0, to c-1 or via explicit +# identifier. +# +# +# +# +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# features. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# The identifier_offset field can for example be used to communicate if the +# identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) +# or from 0 (referred to as C-, Python-style index notation) respectively. +# +# +# +# +# Integer used to distinguish features for explicit indexing. +# +# +# +# +# +# +# +# +# Assumptions and parameter to arrive at geometric primitives +# to locate zero-dimensional/point-(like) features which are +# discretized/represented by points. +# +# +# +# +# Assumptions, parameters, and details how positional uncertainty +# of the geometry is quantified. +# +# +# +# +# +# +# Assumptions and parameters to arrive at geometric primitives +# to locate one-dimensional/line-like features which are +# discretized by polylines. +# +# +# +# +# +# Assumptions, parameters, and details how positional uncertainty +# of the geometry is quantified. +# +# +# +# +# +# Assumptions and parameters to arrive at geometric primitives +# to locate two-dimensional/interface features which are +# discretized by triangulated surface meshes. +# +# +# +# +# +# Assumptions, parameters, and details how positional uncertainty +# of the geometry is quantified. +# +# +# +# +# +# Assumptions and parameters to arrive at geometric primitives +# to locate three-dimensional/volumetric features which are +# discretized by triangulated surface meshes of polyhedra. +# +# +# +# +# +# Assumptions, parameters, and details how positional uncertainty +# of the geometry is quantified. +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXms_ipf.yaml b/contributed_definitions/nyaml/NXms_ipf.yaml new file mode 100644 index 0000000000..11bfc59831 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_ipf.yaml @@ -0,0 +1,299 @@ +category: base +doc: | + Base class to store an inverse pole figure (IPF) mapping (IPF map). +symbols: + # how to make this optional + n_z: | + Number of pixel along the z slowest direction. + n_y: | + Number of pixel along the y slow direction. + n_x: | + Number of pixel along the x fast direction. + n_rgb: | + Number of RGB values along the fastest direction, always three. + d: | + Dimensionality of the mapping (either 2 or 3). +type: group +NXms_ipf(NXprocess): + \@depends_on(NX_CHAR): + doc: | + Reference to the coordinate system whereby the projection_direction is defined. + + If the field depends_on is not provided but a parent of the instance + of this base class or its specialization defines an :ref:`NXcoordinate_system_set` + and exactly one :ref:`NXcoordinate_system`, the reference points to this system. + + If nothing is provided and none of the above-mentioned references pointing + in a parent, McStas is assumed. + projection_direction(NX_NUMBER): + doc: | + The direction along which orientations are projected. + unit: NX_UNITLESS + dim: (3,) + input_grid(NXcg_grid): + doc: | + Details about the original grid. + + Here original grid means the one onto which the IPF map was computed + when exported from the tech partner's file format representation. + output_grid(NXcg_grid): + doc: | + Details about the grid onto which the IPF is recomputed. + + Rescaling the visualization of the IPF map may be needed to enable + visualization in specific software tools like H5Web. + The value specifies the fractional change of the spacing between + the original mapping and the scaled one. + interpolation(NX_CHAR): + doc: | + How where orientation values at the location of the output grid + positions computed. + + Nearest neighbour means the orientation of the closed (Euclidean distance) + grid point of the input_grid was taken. + enumeration: [nearest_neighbour] + map(NXdata): + doc: | + Inverse pole figure mapping. + + Default inverse pole figure (IPF) plot of the data specific for each + phase. No ipf_mapID instances for non-indexed scan points as these are + by definition assigned the null phase with phase_identifier 0. + Inspect the definition of :ref:`NXcrystal_structure` and its field + phase_identifier for further details. + + Details about possible regridding and associated interpolation + during the computation of the IPF map visualization can be stored + using the input_grid, output_grid, and interpolation fields. + + The main purpose of this map is to offer a normalized default representation + of the IPF map for consumption by a research data management system (RDMS). + This is aligned with the first aim of :ref:`NXms_ipf`, to bring colleagues and + users of IPF maps together to discuss which pieces of information + need to be stored together. We are convinced a step-by-step design and + community-driven discussion about which pieces of information should + and/or need to be included is a practical strategy to work towards an + interoperable description and data model for exchanging IPF maps as specific + community-accepted tools to convey orientation maps. + + With this design the individual RDMS solutions and tools can still continue + to support specific custom data analyses workflow and routes but at least + there is one common understanding which enables also those users who are + not necessarily experts in all the details of the underlying techniques + can understand and thus eventually judge if the dataset is worth to be + reused or repurposed. + # \@signal: data + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + data(NX_NUMBER): + # assume a mapping with step size 0.5 micron + # we need to distinguish + # pixel position, i.e. 0, 1, 2, 3, unit px + # answers in which pixel on the map but map is disconnected from sample surface context + # calibrated pixel position 0., 0.5, 1.0, 1.5, unit micron + # answers in addition physical dimensions (relevant to get crystal extent etc.) but still disconnected from sample surface context + # calibrated pixel position including the offset of the original coordinate system + # answers everything would enable one to point if still in the microscope where on the sample surface each pixel is located + # tech partners oftentimes do not report to more than calibrated pixel position + doc: | + Inverse pole figure color code for each map coordinate. + unit: NX_UNITLESS + dim: (n_y, n_x, 3) # | (n_z, n_y, n_x, 3) + axis_z(NX_NUMBER): + doc: | + Pixel center coordinate calibrated for step size along the z axis of the map. + unit: NX_LENGTH + dim: (n_z,) + # \@long_name(NX_CHAR): + axis_y(NX_NUMBER): + unit: NX_LENGTH + doc: | + Pixel center coordinate calibrated for step size along the y axis of the map. + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + unit: NX_LENGTH + doc: | + Pixel center coordinate calibrated for step size along the x axis of the map. + dim: (n_x,) + # \@long_name(NX_CHAR): + # title: + legend(NXdata): + doc: | + The color code which maps colors into orientation into the fundamental zone. + + For each stereographic standard triangle (SST), i.e. a rendering of the + fundamental zone of the crystal-symmetry-reduced orientation space + SO3, it is possible to define a color model which assigns each point in + the fundamental zone a color. + + Different mapping models are used. These implement (slightly) different + scaling relations. Differences exist across representations of tech partners. + + Differences are which base colors of the RGB color model are placed in + which extremal position of the SST and where the white point is located. + + For further details see: + + * [G. Nolze et al.](https://doi.org/10.1107/S1600576716012942) + * Srikanth Patala and coworkers"'" work and of others. + + Details are implementation-specific and not standardized yet. + + Given that the SST has a complicated geometry, it cannot yet be + visualized using tools like H5Web, which is why for now the matrix + of a rasterized image which is rendered by the backend tool gets + copied into an RGB matrix to offer a default plot. + # \@signal: data + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + data(NX_NUMBER): + # hehe, but can be larger than one but could also be an NX_DIMENSIONLESS ! + doc: | + Inverse pole figure color code for each map coordinate. + unit: NX_UNITLESS + dim: (n_y, n_x, 3) + axis_y(NX_NUMBER): + doc: | + Pixel along the y-axis. + unit: NX_UNITLESS + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + doc: | + Pixel along the x-axis. + unit: NX_UNITLESS + dim: (n_x,) + # \@long_name(NX_CHAR): + # title: + +# keep this for now for FAIRmat internal documentation +# It is important to mention that we cannot assume, at least for now, +# that the parser which writes to an NXem_ebsd-compliant file is also +# responsible or capable at all of computing the inverse pole figure +# color keys and maps itself. This cannot be assumed working because +# this mapping of orientation data uses involved mathematical algorithms +# and functions which not every tools used in the EBSD community is capable +# of using or is for sure not using in exactly the same way. +# +# Currently, we assume it is the responsibilty of the tool used which +# generated the data under on_the_fly_indexing to compute these +# plots and deliver these to the parser. +# +# Specific case studies have been explored by the experiment team of +# Area B of the FAIRmat project to realize and implement such mapping. +# +# The first case study uses the H5OINA format and the pyxem/orix library. +# As orix is a Python library, the coloring is performed by the em_om parser. +# +# The second case study uses MTex and its EBSD color coding model. +# As MTex is a Matlab tool, an intermediate format is written from MTex +# first which stores these pieces of information. The parser then pulls +# these data from the intermediate Matlab-agnostic representation and +# supplements the file with missing pieces of information as it is +# required by NXem_ebsd. +# +# The third case study shows how a generic set of Kikuchi pattern +# can be loaded with the em_om parser. The pattern are loaded directly +# from a ZIP file and mapped to an simulation image section for now. +# +# The fourth case study uses the DREAM.3D package which provides an own +# set of EBSD data post-processing procedures. DREAM.3D documents the +# processing steps with a pipeline file which is stored inside DREAM.3D +# output files. In this case study, the parser reads the DREAM.3D file +# and maps data relevant from the perspective of NXem_ebsd plus adds +# relevant IPF color maps as they were computed by DREAM.3D. +# Given that in this case the origin of the data is the DREAM.3D file +# again provenance is kept and more details can be followed upon when +# resolving origin. +# +# These examples offer a first set of suggestions on how to make EBSD +# data injectable into research data management system using schemes +# which themselves are agnostic to the specific RDMS and interoperable. +# Steps of collecting the raw data and post-processing these with custom +# scripts like MTex or commercial tools so far are mainly undocumented. +# The limitation is that a program which consumes results or dump files +# from these tools may not have necessarily all the sufficient information +# available to check if the injected orientation data and color models +# are matching the conventions which a user or automated system has +# injected into an electronic lab notebook from which currently the em_om +# parser collects the conventions and stores them into this NXem_ebsd instance. +# The immediate benefit of the here presented NXem_ebsd concept though +# is that the conventions and reference frame definitions are expected +# in an ELN-agnostic representation to make NXem_ebsd a generally useful +# data scheme for EBSD. +# +# Ideally, the em_om parser would load convention-compliant EBSD data +# and use subsequently a community library to transcode/convert orientation +# conventions and parameterized orientation values. Thereafter, convention- +# compliant default plot(s) could be created that would be truely interoperable. +# +# However, given the variety of post-processing tools available surplus +# the fact that these are not usually executed along standardized +# post-processing workflows which perform exactly the same algorithmic steps, +# this is currently not a practically implementable option. Indeed, first +# developers who wish to implement this would first have to create a library +# for performing such tasks, mapping generally between conventions, +# i.e. map and rotate coordinate systems at the parser level. +# +# The unfortunate situation in EBSD is that due to historical reasons +# and competitive strategies, different players in the field have +# implemented (slightly) different approaches each of which misses +# some part of a complete workflow description which is behind EBSD analyses: +# Sample preparation, measurement, indexing, post-processing, paper... +# +# The here exemplified default plot do not so far apply relevant rotations +# but takes the orientation values as they come from the origin and using +# coloring them as they come. It is thus the scientists responsibility to +# enter and check if the respective dataset is rotation-conventions-wise +# consistent and fit for a particular task. +# +# Ideally, with all conventions defined it can be possible to develop +# a converter which rotates the input data. This application definition +# does not assume this and users should be aware of this limitation. +# +# The key point is that the conventions however are captured and this is +# the most important step to the development of such a generic transcoder +# for creating interoperable EBSD datasets. +# +# Currently the conventions remain in the mind or manual lab book of the +# respective scientists or technicians instead of getting stored and +# communicated with research papers that are written based on +# specific dataset, i.e. database entries. +# +# The default gridded representation of the data should not be +# misinterpreted as the only possible way how EBSD data and OIM +# maps can be created! +# +# Indeed, the most general case is that patterns are collected for +# scan points. The scan generator of an electron microscope is instructed +# to steer the beam in such a way across the specimen surface that the +# beam illuminates certain positions for a certain amount time (usually +# equally-spaced and spending about the same amount of time at each +# position). +# +# Therefore, scan positions can be due to such regular flight plans and +# represent sampling on lines, line stacks, rectangular regions-of- +# interests, but also could instruct spiral, random, or adaptive scans +# instead of tessellations with square or hexagonal pixels. +# +# The majority of EBSD maps is though is reporting results for a regular +# grid (square, hexagon). What matters though in terms of damage induced +# by the electron beam and signal quality is the real electron dose +# history, i.e. for how long the beam exposed which location of the +# specimen. Especially when electron charging occurs (i.e. an excess +# amount of charge accumulates due to e.g. poor conducting away of this +# charge or an improper mounting, too high dose, etc. such details are +# relevant. +# +# Specifically, the default visualization is an inverse pole-figure (IPF) +# map with the usual RGB color coding. Different strategies and +# normalization schemes are in use to define such color coding. +# +# Finally, we should mention that each ipf_map represents data for +# scan points indexed as one phase. The alias/name of this phase should +# be stored in phase_name, the phase_identifier give an ID which must +# not be zero as this value is reserved for non-indexed / null model scan +# points. \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXms_ipf_set.yaml b/contributed_definitions/nyaml/NXms_ipf_set.yaml new file mode 100644 index 0000000000..a783655a24 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_ipf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_ipf` instances. + + A collection of inverse pole figure approximations. +# symbols: +type: group +NXms_ipf_set(NXprocess): + (NXms_ipf): diff --git a/contributed_definitions/nyaml/NXms_mtex_config.yaml b/contributed_definitions/nyaml/NXms_mtex_config.yaml new file mode 100644 index 0000000000..b8fee982d5 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_mtex_config.yaml @@ -0,0 +1,187 @@ +category: base +doc: | + Base class to store the configuration when using the MTex/Matlab software. + + MTex is a Matlab package for texture analysis used in the Materials and Earth Sciences. + See `R. Hielscher et al. `_ and + the `MTex source code `_ for details. +type: group +NXms_mtex_config(NXobject): + conventions(NXcollection): + doc: | + Reference frame and orientation conventions. + Consult the `MTex docs `_ for details. + x_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + # check against v5.12 + z_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + a_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + b_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + euler_angle(NX_CHAR): + doc: | + TODO with MTex developers + enumeration: [unknown, undefined, bunge] + plotting(NXcollection): + doc: | + Settings relevant for generating plots. + font_size(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + inner_plot_spacing(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + outer_plot_spacing(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + marker_size(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + figure_size(NX_NUMBER): + doc: | + TODO with MTex developers + show_micron_bar(NX_BOOLEAN): + doc: | + True if MTex renders a scale bar with figures. + show_coordinates(NX_BOOLEAN): + doc: | + True if MTex renders a grid with figures. + pf_anno_fun_hdl: + doc: | + Code for the function handle used for annotating pole figure plots. + color_map(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_UNITLESS + dim: (i, 3) + default_color_map(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_UNITLESS + dim: (i, 3) + # phase_color_order: + # doc: | + # TODO with MTex developers + # unit: NX_UNITLESS + # dim: (i,) + color_palette(NX_CHAR): + degree_char(NX_CHAR): + doc: | + TODO with MTex developers + arrow_char(NX_CHAR): + doc: | + TODO with MTex developers + marker(NX_CHAR): + doc: | + TODO with MTex developers + marker_edge_color(NX_CHAR): + doc: | + TODO with MTex developers + marker_face_color(NX_CHAR): + doc: | + TODO with MTex developers + hit_test(NX_BOOLEAN): + doc: | + TODO with MTex developers + miscellaneous(NXcollection): + doc: | + Miscellaneous other settings of MTex. + mosek(NX_BOOLEAN): + doc: | + TODO with MTex developers + generating_help_mode(NX_BOOLEAN): + doc: | + TODO with MTex developers + methods_advise(NX_BOOLEAN): + doc: | + TODO with MTex developers + stop_on_symmetry_mismatch(NX_BOOLEAN): + doc: | + TODO with MTex developers + inside_poly(NX_BOOLEAN): + doc: | + TODO with MTex developers + text_interpreter: + numerics(NXcollection): + doc: | + Miscellaneous settings relevant for numerics. + eps(NX_NUMBER): + doc: | + Return value of the Matlab eps command. + unit: NX_UNITLESS + fft_accuracy(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # NX_LENGTH or NX_RECIPROCAL_LENGTH? + max_stwo_bandwidth(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # radiant? + max_sothree_bandwidth(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # radiant? + system(NXcollection): + doc: | + Miscellaneous settings relevant of the system where MTex runs. + memory(NX_NUMBER): + doc: | + TODO with MTex developers + open_gl_bug(NX_BOOLEAN): + doc: | + TODO with MTex developers + save_to_file(NX_BOOLEAN): + doc: | + TODO with MTex developers + path(NXcollection): + doc: | + Collection of paths from where MTex reads information and code. + mtex(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + data(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + cif(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + ebsd(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + pf(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + odf(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + tensor(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + example(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + import_wizard(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + pf_extensions(NX_CHAR): + doc: | + List of file type suffixes for which MTex assumes + texture/pole figure information. + ebsd_extensions(NX_CHAR): + doc: | + List of file type suffixes for which MTex assumes EBSD content. + # version as an instance of (NXprogram) one for MTex one for Matlab diff --git a/contributed_definitions/nyaml/NXms_odf.yaml b/contributed_definitions/nyaml/NXms_odf.yaml new file mode 100644 index 0000000000..92ad96589a --- /dev/null +++ b/contributed_definitions/nyaml/NXms_odf.yaml @@ -0,0 +1,99 @@ +category: base +doc: | + Base class to store an orientation distribution function (ODF) computation. +symbols: + n_varphi_one: | + Number of pixel per varphi section plot along the varphi_one fastest direction. + n_capital_phi: | + Number of pixel per varphi section plot along the capital_phi slow direction. + n_varphi_two: | + Number of pixel per varphi section plot along the varphi_two slowest direction. + k: | + Number of local maxima evaluated in the component analysis. +type: group +NXms_odf(NXprocess): + configuration(NXobject): + doc: | + Details about the algorithm used for computing the ODF. + crystal_symmetry_point_group(NX_CHAR): + doc: | + Point group of the crystal structure (International Table of Crystallography) + of the phase for which the here documented phase-dependent ODF was computed. + specimen_symmetry_point_group(NX_CHAR): + doc: | + Point group assumed for processing-induced *sample symmetries*. + (according to International Table of Crystallography). + kernel_halfwidth(NX_NUMBER): + doc: | + Halfwidth of the kernel. + unit: NX_ANGLE + kernel_name(NX_CHAR): + doc: | + Name of the kernel. + resolution(NX_NUMBER): + doc: | + Resolution of the kernel. + unit: NX_ANGLE + kth_extrema(NXobject): + kth(NX_UINT): + doc: | + Number of local maxima evaluated for the ODF. + unit: NX_UNITLESS + # value of kth should be k + location(NX_NUMBER): + doc: | + Euler angle representation of the kth-most maxima of the ODF + in decreasing order of the intensity maximum. + unit: NX_ANGLE + dim: (k, 3) + theta(NX_NUMBER): + doc: | + Disorientation threshold within which intensity of the ODF + is integrated for the component analysis. + unit: NX_ANGLE + volume_fraction(NX_NUMBER): + doc: | + Integrated ODF intensity within a theta-ball of SO3 about + each location as specified for each location in the order + and reported in the order of these locations. + unit: NX_ANY + dim: (k,) + phi_two_plot(NXdata): + doc: | + Visualization of the ODF intensity as orthogonal sections through Euler space. + + This is one example of typical default plots used in the texture + community in Materials Engineering. + + Mind that the Euler space is a distorted space. Therefore, equivalent + orientations show intensity contributions in eventually multiple + locations. + # \@signal: intensity + # \@axes: [varphi_two, capital_phi, varphi_one] + # \@varphi_one_indices: 0 + # \@capital_phi: 1 + # \@varphi_two_indices: 2 + intensity(NX_NUMBER): + doc: | + ODF intensity at probed locations relative to + null model of a completely random texture. + unit: NX_DIMENSIONLESS + dim: (n_varphi_two, n_capital_phi, n_varphi_one) + varphi_one(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\varphi_1` direction. + unit: NX_ANGLE + dim: (n_varphi_one,) + # \@long_name(NX_CHAR): + varphi_two(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\varphi_2` direction. + unit: NX_ANGLE + dim: (n_varphi_two,) + # \@long_name(NX_CHAR): + capital_phi(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\Phi` direction. + unit: NX_ANGLE + dim: (n_capital_phi,) + # \@long_name(NX_CHAR): diff --git a/contributed_definitions/nyaml/NXms_odf_set.yaml b/contributed_definitions/nyaml/NXms_odf_set.yaml new file mode 100644 index 0000000000..5ea1c4d6cb --- /dev/null +++ b/contributed_definitions/nyaml/NXms_odf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_odf` instances. + + A collection of orientation distribution function approximations. +# symbols: +type: group +NXms_odf_set(NXprocess): + (NXms_odf): diff --git a/contributed_definitions/nyaml/NXms_pf.yaml b/contributed_definitions/nyaml/NXms_pf.yaml new file mode 100644 index 0000000000..09ab12f785 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_pf.yaml @@ -0,0 +1,59 @@ +category: base +doc: | + Base class to store a pole figure (PF) computation. +symbols: + n_y: | + Number of pixel per pole figure in the slow direction. + n_x: | + Number of pixel per pole figure in the fast direction. +type: group +NXms_pf(NXprocess): + configuration(NXobject): + doc: | + Details about the algorithm that was used to compute the pole figure. + crystal_symmetry_point_group(NX_CHAR): + doc: | + Point group of the crystal structure of the phase for which the + here documented phase-dependent pole figure was computed + (according to International Table of Crystallography). + specimen_symmetry_point_group(NX_CHAR): + doc: | + Point group assumed for processing induced *sample symmetries* + (according to International Table of Crystallography). + halfwidth(NX_NUMBER): + doc: | + Halfwidth of the kernel. + unit: NX_ANGLE + miller_indices(NX_CHAR): + doc: | + Miller indices (:math:`(hkl)[uvw]`) to specify the pole figure. + resolution(NX_NUMBER): + doc: | + Resolution of the kernel. + unit: NX_ANGLE + pf(NXdata): + doc: | + Pole figure. + # \@signal: intensity + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + intensity(NX_NUMBER): + doc: | + Pole figure intensity. + unit: NX_UNITLESS + dim: (n_y, n_x) + axis_y(NX_NUMBER): + doc: | + Pixel center along y direction in the equatorial plane of + a stereographic projection of the unit sphere. + unit: NX_ANY + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + doc: | + Pixel center along x direction in the equatorial plane of + a stereographic projection of the unit sphere. + unit: NX_ANY + dim: (n_x,) + # \@long_name(NX_CHAR): diff --git a/contributed_definitions/nyaml/NXms_pf_set.yaml b/contributed_definitions/nyaml/NXms_pf_set.yaml new file mode 100644 index 0000000000..afd785f157 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_pf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_pf` instances. + + A collection of pole figure approximations. +# symbols: +type: group +NXms_pf_set(NXprocess): + (NXms_pf): diff --git a/contributed_definitions/nyaml/NXms_recon.yaml b/contributed_definitions/nyaml/NXms_recon.yaml new file mode 100644 index 0000000000..bd6825bacc --- /dev/null +++ b/contributed_definitions/nyaml/NXms_recon.yaml @@ -0,0 +1,315 @@ +# position would need another depends_on the specific coordinate system used, currently we assume McStas +# roi1/ebsd/microstructure1 +category: base +doc: | + Base class to describe discretized (micro)structural features of a material. + + One instance of this base class can be used to describe the current configuration + the base class does not include time-dependent descriptions for the sake of + clarity and because of the fact that virtually all simulations or experiments + probe time by sampling. Therefore, time-dependent state descriptions should + be realized with creating a set of :ref:`NXms_snapshot_set` with instances of + :ref:`NXms_snapshot` using e.g. :ref:`NXms_recon` base class instances. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + # in so-called linear intercept analysis we observe + # one-dimensional sections of either projections (see below) + # or true one-dimensional cuts across a volume of material + # n_icept: | + # The number of linear intercepts defined. + # n_c_one: | + # The number of crystal projections segmented by crossing (projected or real) interfaces + # n_i_one: | + # The number of crossings + # two-dimensional projections of characterized in reality three-dimensional objects + # using E. E. Underwood notation + # crystals/grains are projections that are delineated by projections of interface, i.e. interface lines which meet at projections of triple lines i.e. triple "points" + n_c_two: | + The number of crystal projections. + n_i_two: | + The number of interface projections. + n_t_two: | + The number of assumed triple junction projections aka triple points. + # three-dimensional real objects, volumetrically characterized + # crystals are delineated by interfaces that are delineated by triple lines that meet at quad junctions + n_c: | + The number of crystals. + n_i: | + The number of interfaces + n_t: | + The number of triple lines + n_q: | + The number of quadruple junctions. +type: group +NXms_recon(NXobject): + # as e.g. a result of one grain reconstruction with MTex or othe + # grain reconstruction software in commercial tools + # the idea is we may wish to run as many grain reconstructions as we want... + # add details about the processing + configuration(NXprocess): + doc: | + The configuration and parameterization of the reconstruction algorithm + whereby the microstructural features were identified. + # maybe a depends_on what was the input however if the group is injected + # in an roi1/ebsd instance isnt this information implicit? + dimensionality(NX_POSINT): + doc: | + Dimensionality of the analysis. + + This field can be used e.g. by a research data management system + to identify if the described feature set specifies a + one-, two-, or three-dimensional feature set. + unit: NX_UNITLESS + enumeration: [1, 2, 3] + algorithm(NX_CHAR): + doc: | + Which algorithm is used to reconstruct the features. + enumeration: [unknown, disorientation_clustering, fast_multiscale_clustering, markov_chain_clustering] + disorientation_threshold(NX_NUMBER): + doc: | + Threshold to define at which disorientation angle to assume + two crystalline regions have a significant orientation difference + which warrants to argue that there is an interface between the + two regions. + unit: NX_ANGLE + # the result of running one grain reconstruction + # ms_feature_set1 + # we could also enumerate instances ms_feature_setID here because configuration + # may specify a range of different parameter resulting in multiple ms_feature_sets + # dimensionality(N) composed from NXms_feature_set base: + # controlled vocabulary of base class instances to be used to inform about the + # discretization of these features instances to discretize the features + # wherever possible the computational geometry specific instances whose + # purpose is only to support/represent the discretization of the features should + # be separated out from the materials engineering interpretation of what these + # features are, i.e. a grain that is measured with a 2d section ends up + # modelled as an projection of that real 3d grain object + # the model is discretized usign a polyline which models the location of the + # interface at the required here coarse-grained continuum picture + points(NXcg_point_set): + lines(NXcg_polyline_set): + surfaces(NXcg_triangle_set): + volumes(NXcg_polyhedron_set): + + # domain-specific, i.e. microstructural features + # ONE DIMENSIONAL FEATURES + + # TWO DIMENSIONAL FEATURES + crystal_projections(NXms_feature_set): + doc: | + Projections of crystals on the sample surface as typically + characterized with optical or electron microscopy. + \@discretization(NX_CHAR): + doc: | + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Most microscopy techniques support to generate only a two-dimensional + representation (projection) of the characterized material. + + For true volumetric techniques use the specifically + specialized crystals :ref:`NXms_feature_set` instead. + See stereology literature for more details e.g. + E.E. Underwood's book entitled Quantitative Stereology + number_of_crystals(NX_UINT): + doc: | + Number of crystals. + unit: NX_UNITLESS + crystal_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + crystal_identifier(NX_INT): + doc: | + Identifier used for crystals for explicit indexing. + unit: NX_UNITLESS + dim: (n_c_two,) + number_of_phases(NX_UINT): + doc: | + How many phases are distinguished + unit: NX_UNITLESS + phase_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + unit: NX_UNITLESS + phase_identifier(NX_INT): + # \@depends_on(NX_CHAR): + doc: | + Identifier used for phase for explicit indexing. + unit: NX_UNITLESS + dim: (n_c_two,) + # properties of crystal_projections aka grain properties + boundary_contact(NX_BOOLEAN): + doc: | + True, if the crystal makes contact with the edge of the ROI, + false otherwise. + dim: (n_c_two,) + orientation_spread(NX_NUMBER): + doc: | + Average disorientation angle between individual orientation of the + crystal at probed positions (weighted by area of that position) versus + the average disorientation of the crystal. + unit: NX_ANGLE + dim: (n_c_two,) + (NXrotation_set): + area(NX_NUMBER): + doc: | + Calibrated area of surrounded by the polyline about each crystal. + unit: NX_AREA + dim: (n_c_two,) + interface_projections(NXms_feature_set): + # grain boundaries have a network of line-like defects, its explicit description + # often generates unnecessary information duplication and cluttering, + # therefore here a compact and suggestion how to store such data + doc: | + Projections of grain or phase boundaries as typically sectioned + with optical or electron microscopy characterization. + \@discretization(NX_CHAR): + doc: | + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Set of tuples of polyline segments which build the interface. + # topology + # i) Set of pair of crystals sharing an interface + crystals(NX_INT): + doc: | + Set of pairs of crystal_identifier resolved via depends_on which + are adjacent to each interface. + unit: NX_UNITLESS + dim: (n_i_two, 2) + \@depends_on(NX_CHAR): + doc: | + The specific crystal_projections(NXms_feature_set) instance + to resolve crystal identifier. + # ii) Set of pair of topologically connected triple points + triple_points(NX_INT): + doc: | + Set of pairs of triple_point_identifier which the interface connects. + For 2D projections of 3D microstructural features a triple point is + physically only the projection of a triple line. + unit: NX_UNITLESS + dim: (n_i_two, 2) + \@depends_on(NX_CHAR): + doc: | + The specific triple_line_projections(NXms_feature_set) instance + whereby to resolve triple_point identifier. + # alternatively which polyline of adjoining interfaces + # properties, descriptors + length(NX_NUMBER): + doc: | + The length of the interface. + + This is not necessarily the same as the length of the individual + polyline segments whereby the interface is discretized. + + The actual coordinate system whereby the geometry is calibrated + with real physical dimensions is typically documented by the + depends_on attribute of the respective NXcg_primitive_set. + This depends_on attribute should point explicitly to an + instance of a :ref:`NXcoordinate_system` to support users as + much as possible with interpreting how and where the lines are + located in the reference frame. + unit: NX_LENGTH + dim: (n_i_two,) + interface_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + interface_identifier(NX_INT): + doc: | + Identifier for each interface using explicit indexing. + unit: NX_UNITLESS + dim: (n_i_two,) + triple_line_projections(NXms_feature_set): + # only for 2D, quad junction is the equivalent for 3D is not a triple_line + # four alternative descriptors with different strength to specify spatial + # or logical information about the triple junction feature set. + # the explicit description often generating unnecessary information duplication + doc: | + Projections of triple lines as typically characterized with optical + or electron microscopy. + + Mind that most specimens are thermo-chemo-mechanically treated before + they are characterized. Therefore, the projected crystal defects are + have physically no longer the same structure as in the bulk. + + Examples are manifest as effects such as thermal grooving, or relaxation + effects of an intersection between a triple line that is cut + by the specimen surface as these defects are then exposed typically + to a different atmosphere and hence have different thermodynamic boundary + conditions than of their true volumetric defects in the bulk. + \@discretization(NX_CHAR): + doc: | + Reference to points(NXcg_point_set) which supports the + locations of these triple points. + # another view to describe a triple junction is via its topology/connection expressed either via + # i) triplet of interface identifier + number_of_triple_points(NX_UINT): + doc: | + Number of triple points. + unit: NX_UNITLESS + triple_point_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + triple_point_identifier(NX_INT): + doc: | + Identifier for each triple point using explicit indexing. + unit: NX_UNITLESS + dim: (n_t_two,) + location(NX_INT): + doc: | + Set of triple point identifiers. + unit: NX_UNITLESS + dim: (n_t_two,) + \@depends_on(NX_CHAR): + doc: | + The relevant points(NXcg_point_set) instance whereby to + resolve interface identifiers. + interfaces(NX_INT): # aka topology or interfaces + doc: | + Set of triplets of identifier of line-like features. + Each triplet resolves which three interface projections + the triple point connects. + unit: NX_UNITLESS + dim: (n_t_two, 3) + \@depends_on(NX_CHAR): + doc: | + The specific interface_projections(NXms_feature_set) + instance whereby to resolve interface identifiers. + # ii) a triplet of line segment identifier whereby the point-like features + # is assumed discretized via three polylines representing interfaces + polylines(NX_INT): + doc: | + Triplet of identifier of polyline segments. Each triplet resolves + which three segments of polyline segments the triple junction connects. + unit: NX_UNITLESS + dim: (n_t_two, 3) + \@depends_on(NX_CHAR): + doc: | + The specific lines(NXcg_polyline_set) instance to resolve + polyline segments. + # the difference in the interpretation of interfaces and polylines + # is that the interface resolves interface (e.g. phase boundary names) + # while polylines resolves segments within the set of named geometric primitive + # instances! + # add all sort of other qualitative or quantitive descriptors (triple junction + # energy, volume etc), i.e properties of that triple point diff --git a/contributed_definitions/nyaml/NXms_score_config.yaml b/contributed_definitions/nyaml/NXms_score_config.yaml new file mode 100644 index 0000000000..3e5bbba0e8 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_score_config.yaml @@ -0,0 +1,777 @@ +category: application +doc: | + Application definition to control a simulation with the SCORE model. +symbols: + n_dg_ori: | + Number of Bunge-Euler angle triplets for deformed grains. + n_rx_ori: | + Number of Bunge-Euler angle triplets for recrystallization nuclei. + n_su: | + Number of solitary unit domains to export. +type: group +NXms_score_config(NXobject): + (NXentry): + \@version: + doc: | + Version specifier of this application definition. + definition: + doc: | + Official NeXus NXDL schema with which this file was written. + enumeration: [NXms_score_config] + PROGRAM(NXprogram): + program_name: + \@version: + analysis_identifier: + doc: | + Ideally, a (globally persistent) unique identifier for referring + to this analysis. + analysis_description: + exists: optional + doc: | + Possibility for leaving a free-text description about this analysis. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + time_stamp(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code with local time zone offset to UTC + information included when this configuration file was created. + initial_microstructure(NXprocess): + doc: | + Relevant data to instantiate a starting configuration that is typically + a microstructure in deformed conditions where stored (elastic) energy + is stored in the form of crystal defects, which in the SCORE model are + is considered as mean-field dislocation content. + type: + doc: | + Which model should be used to generate a starting microstructure. + enumeration: [cuboidal, poisson_voronoi, ebsd, damask] + cell_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Edge length of the cubic cells of each CA domain. + domain_size(NX_UINT): + unit: NX_UNITLESS + doc: | + Extend of each CA domain in voxel along the x, y, and z direction. + Deformation of sheet material is assumed. + The x axis is assumed pointing along the rolling direction. + The y axis is assumed pointing along the transverse direction. + The z axis is assumed pointing along the normal direction. + dimensions: + rank: 1 + dim: [[1, 3]] + grain_size(NX_FLOAT): + unit: NX_LENGTH + doc: | + Extent of each deformed grain along the x, y, and z direction when type is + cuboidal. + dimensions: + rank: 1 + dim: [[1, 3]] + grain_diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Average spherical diameter when type is poisson_voronoi. + grain_euler(NX_FLOAT): + unit: NX_ANGLE + doc: | + Set of Bunge-Euler angles to sample orientations randomly from. + dimensions: + rank: 2 + dim: [[1, n_dg_ori], [2, 3]] + ebsd(NXprocess): + exists: optional + doc: | + The EBSD dataset from which the initial microstructure is instantiated + if initial_microstructure/type has value ebsd. + filename: + doc: | + Path and name of the EBSD dataset from which to generate the starting + microstructure. + \@version: + doc: | + SHA256 checksum of the file which contains the EBSD dataset. + stepsize(NX_FLOAT): + unit: NX_LENGTH + doc: | + Size of the EBSD. The EBSD orientation mapping has to be on a + regular grid of square-shaped pixels. + dimensions: + rank: 1 + dim: [[1, 2]] + nucleation_model(NXprocess): + doc: | + Phenomenological model according to which it nuclei are placed + into the domain and assumed growing. + spatial_distribution_model: + doc: | + According to which model will the nuclei become distributed spatially. + CSR means complete spatial randomness. + Custom is implementation specific. + GB places nuclei at grain boundaries. + enumeration: [csr, custom, gb] + incubation_time_model: + doc: | + According to which model will the nuclei start to grow. + enumeration: [site_saturation] + orientation_model: + doc: | + According to which model will the nuclei get their orientation assigned. + enumeration: [sample_from_nucleus_euler] + nucleus_euler(NX_FLOAT): + unit: NX_ANGLE + doc: | + Set of Bunge-Euler angles to sample orientations of nuclei randomly from. + dimensions: + rank: 2 + dim: [[1, n_rx_ori], [2, 3]] + material_properties(NXprocess): + doc: | + (Mechanical) properties of the material which scale the amount + of stored (elastic) energy in the ROI/system. + reference_shear_modulus(NX_FLOAT): + unit: NX_PRESSURE + doc: | + Shear modulus at zero Kelvin. + reference_burgers_magnitude(NX_FLOAT): + unit: NX_LENGTH + doc: | + Magnitude at the Burgers vector at zero Kelvin. + + # firstOrderdG0dT + # alloyConstantThermalExpCoeff + # FirstOrderThermalExpCoeff + # SecondOrderThermalExpCoeff + melting_temperature(NX_FLOAT): + unit: NX_TEMPERATURE + doc: | + Melting temperature in degrees Celsius. + grain_boundary_mobility_model(NXprocess): + doc: | + Model for the assumed mobility of grain boundaries with different + disorientation. + model: + doc: | + Which type of fundamental model for the grain boundary mobility: + For the Sebald-Gottstein model the following equation is used. + For the Rollett-Holm model the following equation is used. + enumeration: [sebald_gottstein, rollett_holm] + sebald_gottstein_parameters(NXcollection): + lagb_pre_factor(NX_FLOAT): + unit: NX_ANY + lagb_enthalpy(NX_FLOAT): + unit: NX_ANY + hagb_pre_factor(NX_FLOAT): + unit: NX_ANY + hagb_enthalpy(NX_FLOAT): + unit: NX_ANY + special_pre_factor(NX_FLOAT): + unit: NX_ANY + special_enthalpy(NX_FLOAT): + unit: NX_ANY + rollett_holm_parameters(NXcollection): + hagb_pre_factor(NX_FLOAT): + unit: NX_ANY + hagb_enthalpy(NX_FLOAT): + unit: NX_ANY + lagb_to_hagb_cut(NX_FLOAT): + unit: NX_ANY + lagb_to_hagb_transition(NX_FLOAT): + unit: NX_ANY + lagb_to_hagb_exponent(NX_FLOAT): + unit: NX_ANY + stored_energy_recovery_model(NXprocess): + doc: | + Simulated evolution of the dislocation density as the stored + (elastic) energy assumed stored in each grain. + model: + doc: | + Which type of recovery model. + enumeration: [none] + dispersoid_drag_model(NXprocess): + doc: | + Simulated reduction of the grain boundary speed due to + the presence of dispersoids through which the total grain boundary + area of the recrystallization front can be reduced. + model: + doc: | + Which type of drag model. + enumeration: [none, zener_smith] + zener_smith_parameter(NXcollection): + pre_factor(NX_FLOAT): + surface_energy_density(NX_FLOAT): + time(NX_FLOAT): + unit: NX_TIME + doc: | + Support point of the linearized curve of simulated time matching + a specific support point of the average dispersoid radius. + dimensions: + rank: 1 + dim: [[1, i]] + radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + Support point of the linearized curve of the average dispersoid radius. + dimensions: + rank: 1 + dim: [[1, i]] + time_temperature_history(NXprocess): + doc: | + Simulated time temperature profile + time(NX_FLOAT): + unit: NX_TIME + doc: | + Support point of the linearized curve of simulated time matching + a specific support point of the temperature. + dimensions: + rank: 1 + dim: [[1, j]] + temperature(NX_FLOAT): + unit: NX_LENGTH + doc: | + Support point of the linearized curve of the temperature. + dimensions: + rank: 1 + dim: [[1, j]] + stop_criteria(NXprocess): + doc: | + Criteria which enable to stop the simulation in a controlled manner. + Whichever criterion is fulfilled first stops the simulation. + max_x(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Maximum recrystallized volume fraction. + max_time(NX_NUMBER): + unit: NX_TIME + doc: | + Maximum simulated physical time. + max_iteration(NX_UINT): + unit: NX_UNITLESS + doc: | + Maximum number of iteration steps. + numerics(NXprocess): + doc: | + Settings relevant for stable numerical integration. + max_delta_x(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Maximum fraction equivalent to the migration of the + fastest grain boundary in the system how much a cell + may be consumed in a single iteration. + initial_cell_cache(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Fraction of the total number of cells in the CA which + should initially be allocated for offering cells in the + recrystallization front. + realloc_cell_cache(NX_FLOAT): + unit: NX_UNITLESS + doc: | + By how much more times should the already allocated memory + be is increased to offer space for storing states of cells + in the recrystallization front. + defragment_cell_cache(NX_BOOLEAN): + doc: | + Should the cache for cells in the recrystallization front + be defragmented on-the-fly. + defragment_x(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Heuristic recrystallized volume target values at which + the cache for cells in the recrystallization front + will be defragmented on-the-fly. + dimensions: + rank: 1 + dim: [[1, i]] + snapshot_x(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + List of recrystallized volume target values at which a + snapshot of the CA state should be exported for. + dimensions: + rank: 1 + dim: [[1, j]] + solitary_unit_model(NXprocess): + apply(NX_BOOLEAN): + doc: | + Perform a statistical analyses of the results as it was + proposed by M. Kühbach (solitary unit model ensemble approach). + number_of_domains(NX_UINT): + unit: NX_UNITLESS + doc: | + How many independent cellular automaton domains + should be instantiated. + rediscretization(NX_UINT): + unit: NX_UNITLESS + doc: | + Into how many time steps should the real time interval be discretized upon + during post-processing the results with the solitary unit modeling approach. + domain_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + List of identifier for those domain which should be rendered. + Identifier start from 0. + dimensions: + rank: 1 + dim: [[1, n_su]] + performance(NXcs_profiling): + current_working_directory: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6142d3475f379790762453cd32f9330b04fd40950389a8c7322331e405008183 +# +# +# +# +# +# +# +# Number of Bunge-Euler angle triplets for deformed grains. +# +# +# +# +# Number of Bunge-Euler angle triplets for recrystallization nuclei. +# +# +# +# +# Number of solitary unit domains to export. +# +# +# +# +# Application definition to control a simulation with the SCORE model. +# +# +# +# +# Version specifier of this application definition. +# +# +# +# +# Official NeXus NXDL schema with which this file was written. +# +# +# +# +# +# +# +# +# +# +# +# +# Ideally, a (globally persistent) unique identifier for referring +# to this analysis. +# +# +# +# +# Possibility for leaving a free-text description about this analysis. +# +# +# +# +# Path to the directory where the tool should store NeXus/HDF5 results +# of this analysis. If not specified results will be stored in the +# current working directory. +# +# +# +# +# ISO 8601 formatted time code with local time zone offset to UTC +# information included when this configuration file was created. +# +# +# +# +# Relevant data to instantiate a starting configuration that is typically +# a microstructure in deformed conditions where stored (elastic) energy +# is stored in the form of crystal defects, which in the SCORE model are +# is considered as mean-field dislocation content. +# +# +# +# Which model should be used to generate a starting microstructure. +# +# +# +# +# +# +# +# +# +# +# Edge length of the cubic cells of each CA domain. +# +# +# +# +# Extend of each CA domain in voxel along the x, y, and z direction. +# Deformation of sheet material is assumed. +# The x axis is assumed pointing along the rolling direction. +# The y axis is assumed pointing along the transverse direction. +# The z axis is assumed pointing along the normal direction. +# +# +# +# +# +# +# +# Extent of each deformed grain along the x, y, and z direction when type is +# cuboidal. +# +# +# +# +# +# +# +# Average spherical diameter when type is poisson_voronoi. +# +# +# +# +# Set of Bunge-Euler angles to sample orientations randomly from. +# +# +# +# +# +# +# +# +# The EBSD dataset from which the initial microstructure is instantiated +# if initial_microstructure/type has value ebsd. +# +# +# +# Path and name of the EBSD dataset from which to generate the starting +# microstructure. +# +# +# +# SHA256 checksum of the file which contains the EBSD dataset. +# +# +# +# +# +# Size of the EBSD. The EBSD orientation mapping has to be on a +# regular grid of square-shaped pixels. +# +# +# +# +# +# +# +# +# +# Phenomenological model according to which it nuclei are placed +# into the domain and assumed growing. +# +# +# +# According to which model will the nuclei become distributed spatially. +# CSR means complete spatial randomness. +# Custom is implementation specific. +# GB places nuclei at grain boundaries. +# +# +# +# +# +# +# +# +# +# According to which model will the nuclei start to grow. +# +# +# +# +# +# +# +# According to which model will the nuclei get their orientation assigned. +# +# +# +# +# +# +# +# Set of Bunge-Euler angles to sample orientations of nuclei randomly from. +# +# +# +# +# +# +# +# +# +# (Mechanical) properties of the material which scale the amount +# of stored (elastic) energy in the ROI/system. +# +# +# +# Shear modulus at zero Kelvin. +# +# +# +# +# Magnitude at the Burgers vector at zero Kelvin. +# +# +# +# +# +# Melting temperature in degrees Celsius. +# +# +# +# +# +# Model for the assumed mobility of grain boundaries with different +# disorientation. +# +# +# +# Which type of fundamental model for the grain boundary mobility: +# For the Sebald-Gottstein model the following equation is used. +# For the Rollett-Holm model the following equation is used. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Simulated evolution of the dislocation density as the stored +# (elastic) energy assumed stored in each grain. +# +# +# +# Which type of recovery model. +# +# +# +# +# +# +# +# +# Simulated reduction of the grain boundary speed due to +# the presence of dispersoids through which the total grain boundary +# area of the recrystallization front can be reduced. +# +# +# +# Which type of drag model. +# +# +# +# +# +# +# +# +# +# +# +# Support point of the linearized curve of simulated time matching +# a specific support point of the average dispersoid radius. +# +# +# +# +# +# +# +# Support point of the linearized curve of the average dispersoid radius. +# +# +# +# +# +# +# +# +# +# Simulated time temperature profile +# +# +# +# Support point of the linearized curve of simulated time matching +# a specific support point of the temperature. +# +# +# +# +# +# +# +# Support point of the linearized curve of the temperature. +# +# +# +# +# +# +# +# +# Criteria which enable to stop the simulation in a controlled manner. +# Whichever criterion is fulfilled first stops the simulation. +# +# +# +# Maximum recrystallized volume fraction. +# +# +# +# +# Maximum simulated physical time. +# +# +# +# +# Maximum number of iteration steps. +# +# +# +# +# +# Settings relevant for stable numerical integration. +# +# +# +# Maximum fraction equivalent to the migration of the +# fastest grain boundary in the system how much a cell +# may be consumed in a single iteration. +# +# +# +# +# Fraction of the total number of cells in the CA which +# should initially be allocated for offering cells in the +# recrystallization front. +# +# +# +# +# By how much more times should the already allocated memory +# be is increased to offer space for storing states of cells +# in the recrystallization front. +# +# +# +# +# Should the cache for cells in the recrystallization front +# be defragmented on-the-fly. +# +# +# +# +# Heuristic recrystallized volume target values at which +# the cache for cells in the recrystallization front +# will be defragmented on-the-fly. +# +# +# +# +# +# +# +# List of recrystallized volume target values at which a +# snapshot of the CA state should be exported for. +# +# +# +# +# +# +# +# +# +# Perform a statistical analyses of the results as it was +# proposed by M. Kühbach (solitary unit model ensemble approach). +# +# +# +# +# How many independent cellular automaton domains +# should be instantiated. +# +# +# +# +# Into how many time steps should the real time interval be discretized upon +# during post-processing the results with the solitary unit modeling approach. +# +# +# +# +# List of identifier for those domain which should be rendered. +# Identifier start from 0. +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXms_score_results.yaml b/contributed_definitions/nyaml/NXms_score_results.yaml new file mode 100644 index 0000000000..2996c7d7c7 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_score_results.yaml @@ -0,0 +1,612 @@ +category: application +doc: | + Application definition for storing results of the SCORE cellular automaton. + + The SCORE cellular automaton model for primary recrystallization is an + example of typical materials engineering applications used within the field + of so-called Integral Computational Materials Engineering (ICME) whereby + one can simulate the evolution of microstructures. + + Specifically the SCORE model can be used to simulate the growth of static + recrystallization nuclei. The model is described in the literature: + + * `M. Kühbach et al. `_ + * `C. Haase et al. `_ + * `M. Diehl et al. `_ +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_b: | + Number of boundaries of the bounding box or primitive to domain. + n_p: | + Number of parameter required for chosen orientation parameterization. + n_tex: | + Number of texture components identified. + d: | + Dimensionality. + c: | + Cardinality. + n_front: | + Number of active cells in the (recrystallization) front. + n_grains: | + Number of grains in the computer simulation. + +# inspect comments behind NXms +type: group +NXms_score_results(NXobject): + (NXentry): + \@version: + doc: | + An at least as strong as SHA256 hashvalue of the file + that specifies the application definition. + + # enumeration: [sha_256_hash] + definition: + doc: | + NeXus NXDL schema to which this file conforms. + enumeration: [NXms_score_results] + analysis_identifier: + doc: | + Ideally, a (globally) unique persistent identifier + for referring to this computer simulation. + + The identifier is usually defined/issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments to e.g. proposals. + analysis_description: + exists: optional + doc: | + Free-text description about the workflow (analysis/simulation). + + Users are strongly advised to detail the sample history in the + respective field and fill rather as completely as possible the fields + of this application definition rather than write details about the + experiment into this free-text description field. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the characterization started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC included + when the characterization ended. + PROGRAM(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program_name: + \@version: + experiment_or_simulation: + doc: | + Specify if the (characterization) results/data of this instance of an + application definition are based on the results of a simulation or the + results of a post-processing of measured data to describe a microstructure. + The term microstructure is used to describe the spatial arrangement of + crystal defects inside a sample/specimen without demanding necessarily + that this structure is mainly at the micron length scale. + Nanostructure and macrostructure are close synonyms. + Material architecture is a narrow synonym. + enumeration: [experiment, simulation] + + # always a simulation! + config_filename: + doc: | + The path and name of the config file for this analysis. + \@version: + doc: | + At least SHA256 strong hash of the specific config_file for + tracking provenance. + results_path: + exists: optional + doc: | + Path to the directory where the tool should store NeXus/HDF5 results + of this analysis. If not specified results will be stored in the + current working directory. + status: + doc: | + A statement whether the SCORE executable managed to + process the analysis or failed prematurely. + + This status is written to the results file after the end_time + at which point the executable must not compute any analysis. + Only when this status message is present and shows `success`, the + user should consider the results. In all other cases it might be + that the executable has terminated prematurely or another error + occurred. + enumeration: [success, failure] + USER(NXuser): + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Contact information and eventually details of at least one person + involved in creating this result. This can be the principle investigator + who performed this experiment. Adding multiple users if relevant is recommended. + name: + doc: | + Given (first) name and surname of the user. + affiliation: + exists: recommended + doc: | + Name of the affiliation of the user at the point in time + when the experiment was performed. + address: + exists: recommended + doc: | + Postal address of the affiliation. + email: + exists: recommended + doc: | + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + orcid: + exists: recommended + doc: | + Globally unique identifier of the user as offered by services + like ORCID or ResearcherID. If this field is field the specific service + should also be written in orcid_platform + orcid_platform: + exists: recommended + doc: | + Name of the OrcID or ResearcherID where the account + under orcid is registered. + telephone_number: + exists: optional + doc: | + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + role: + exists: recommended + doc: | + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope. Student, postdoc, principle investigator, guest + are common examples. + social_media_name: + exists: optional + doc: | + Account name that is associated with the user in social media platforms. + social_media_platform: + exists: optional + doc: | + Name of the social media platform where the account + under social_media_name is registered. + specimen(NXsample): + + # NEW ISSUE: inject the conclusion from the discussion with Andrea + # according to SAMPLE.yaml 0f8df14 2022/06/15 + name: + doc: | + Descriptive name or ideally (globally) unique persistent identifier. + + # sample_history: + # doc: | + # Ideally, a reference to the location of or a (globally) unique + # persistent identifier of e.g. another file which should document + # ideally as many details as possible of the material, its + # microstructure, and its thermo-chemo-mechanical processing/ + # preparation history. + # preparation_date(NX_DATE_TIME): + # doc: | + # ISO 8601 time code with local time zone offset to UTC information + # when the specimen was prepared. + (NXdata): + exists: optional + doc: | + Hard link to a location in the hierarchy of the NeXus file + where the data for default plotting are stored. + (NXcoordinate_system_set): + doc: | + Container to hold different coordinate systems conventions. + A least a right-handed Cartesian coordinate system with base vectors + named x, y, and z has to be specified. Each base vector of the + coordinate system should be described with an NXtransformations instance. + TRANSFORMATIONS(NXtransformations): + exists: ['min', '3', 'max', 'unbounded'] + conventions(NXem_conventions): + rotation_conventions(NXprocess): + three_dimensional_rotation_handedness: + rotation_convention: + euler_angle_convention: + axis_angle_convention: + orientation_parameterization_sign_convention: + processing_reference_frame(NXprocess): + reference_frame_type: + xaxis_direction: + xaxis_alias: + yaxis_direction: + yaxis_alias: + zaxis_direction: + zaxis_alias: + origin: + sample_reference_frame(NXprocess): + reference_frame_type: + xaxis_direction: + yaxis_direction: + zaxis_direction: + origin: + ROI_SET(NXcg_roi_set): + exists: ['min', '1', 'max', 'unbounded'] + + # however for solitary unit models aka volume element ensemble, replica methods we may need more than one domain + # the volume element is not called representative because for what we consider the volume element to be representative + # for is a matter of interpretation (fundamentally this is an assumption) and can differ for different descriptors + doc: | + The simulated or characterized material volume element aka domain. + At least one instance of geometry required either NXcg_grid, + NXcg_polyhedron_set, or NXcg_point_set. This geometry group needs + to contain details about the boundary conditions. + grid(NXcg_grid): + dimensionality(NX_POSINT): + cardinality(NX_POSINT): + origin(NX_NUMBER): + symmetry: + cell_dimensions(NX_NUMBER): + extent(NX_POSINT): + identifier_offset(NX_INT): + boundary(NXcg_polyhedron_set): + doc: | + A tight bounding box or sphere or bounding primitive about the grid. + + # a good example for a general bounding box description for such a grids of triclinic cells + # https://docs.lammps.org/Howto_triclinic.html NXcg_polyhedron because a parallelepiped + number_of_boundaries(NX_POSINT): + unit: NX_UNITLESS + doc: | + How many distinct boundaries are distinguished? + Most grids discretize a cubic or cuboidal region. In this case + six sides can be distinguished, each making an own boundary. + boundaries: + exists: ['min', '0'] + doc: | + Name of the boundaries. E.g. left, right, front, back, bottom, top, + The field must have as many entries as there are number_of_boundaries. + boundary_conditions(NX_INT): + unit: NX_UNITLESS + doc: | + The boundary conditions for each boundary: + + 0 - undefined + 1 - open + 2 - periodic + 3 - mirror + 4 - von Neumann + 5 - Dirichlet + dimensions: + rank: 1 + dim: [[1, n_b]] + snapshot_set(NXms_snapshot_set): + doc: | + Collection of microstructural data observed/simulated. + identifier_offset(NX_UINT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly or explicitly. + For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate + if the identifiers are expected to start from 1 (referred to as + Fortran-/Matlab-) or from 0 (referred to as C-, Python-style index + notation) respectively. + + # essentially NXmonitor instances for evolution of ensemble summary statistics + evolution(NXprocess): + exists: optional + doc: | + Summary quantities which are the result of some post-processing of + the snapshot data (averaging, integrating, interpolating). + Frequently used descriptors from continuum mechanics and thermodynamics + can be used here. A few examples are given. Each descriptor is currently + modelled as an instance of an NXprocess because it is relevant to + understand how the descriptors are computed. + time(NXprocess): + exists: optional + doc: | + Evolution of the physical time. + temperature(NXprocess): + exists: optional + doc: | + Evolution of the simulated temperature over time. + + # pressure(NXprocess): + # exists: optional + # stress(NXprocess): + # exists: optional + # strain(NXprocess): + # exists: optional + # deformation_gradient(NXprocess): + # exists: optional + # magnetic_field(NXprocess): + # exists: optional + # electric_field(NXprocess): + # exists: optional + kinetics(NXprocess): + exists: optional + doc: | + Evolution of the recrystallized volume fraction over time. + + # recrystallization_front(NXprocess): + # exists: optional + # time-resolved results for individual snapshots + # virtually all computer simulations and all experiments always probe + # snapshots + MS_SNAPSHOT(NXms_snapshot): + time(NX_NUMBER): + unit: NX_TIME + doc: | + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + doc: | + Simulated temperature. + iteration(NX_UINT): + unit: NX_UNITLESS + doc: | + Iteration or increment counter. + + # optional places to store the grid for instance if it changes + grid(NXcg_grid): + exists: recommended + grain_identifier(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + Grain identifier for each cell. + dimensions: + rank: 3 + dim: [[1, n_x], [2, n_y], [3, n_z]] + thread_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Identifier of the OpenMP thread which processed this part of the grid. + dimensions: + rank: 3 + dim: [[1, n_x], [2, n_y], [3, n_z]] + + # check comments behind NXms + recrystallization_front(NXprocess): + exists: recommended + doc: | + Details about those cells which in this time step represent + the discretized recrystallization front. + halo_region(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Which cells are currently in a halo region of threads. + dimensions: + rank: 1 + dim: [[1, n_front]] + mobility_weight(NX_NUMBER): + exists: recommended + unit: NX_UNITLESS + doc: | + So-called mobility weight which is a scaling factor to + control the mobility of the grain boundary which is assumed + to sweep currently this volume. + dimensions: + rank: 1 + dim: [[1, n_front]] + coordinate(NX_NUMBER): + exists: recommended + unit: NX_LENGTH + doc: | + Grid coordinates of each cell in the recrystallization front. + dimensions: + rank: 2 + dim: [[1, n_front], [2, 3]] + deformed_grain_identifier(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + Grain identifier assigned to each cell in the recrystallization front. + dimensions: + rank: 1 + dim: [[1, n_front]] + recrystallized_grain_identifier(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + Grain identifier assigned to each nucleus which affected that cell in the + recrystallization front. + dimensions: + rank: 1 + dim: [[1, n_front]] + recrystallized_volume_fraction(NX_NUMBER): + exists: recommended + unit: NX_DIMENSIONLESS + doc: | + Relative volume transformed as a measure of infection progress. + dimensions: + rank: 1 + dim: [[1, n_front]] + thread_identifier(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Identifier of the OpenMP thread processing each cell in the recrystallization + front. + dimensions: + rank: 1 + dim: [[1, n_front]] + infection_direction(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Hint about the direction from which the cell was infected. + dimensions: + rank: 1 + dim: [[1, n_front]] + grain_ensemble(NXprocess): + exists: recommended + doc: | + Current grain-related quantities. + euler(NX_NUMBER): + exists: optional + unit: NX_ANGLE + doc: | + Bunge-Euler angle triplets for each grain. + dimensions: + rank: 2 + dim: [[1, n_grains], [2, 3]] + volume(NX_NUMBER): + unit: NX_VOLUME + doc: | + Discrete volume of each grain accounting also for partially + transformed cells. + dimensions: + rank: 1 + dim: [[1, n_grains]] + dislocation_density(NX_NUMBER): + exists: recommended + unit: NX_ANY + doc: | + Current value for the dislocation density as a measure of + the remaining stored energy in assumed crystal defects inside + each grain. The difference between these values scales the + driving force of grain boundary migration. + dimensions: + rank: 1 + dim: [[1, n_grains]] + is_deformed(NX_BOOLEAN): + exists: recommended + doc: | + Is the grain deformed. + dimensions: + rank: 1 + dim: [[1, n_grains]] + is_recrystallized(NX_BOOLEAN): + exists: recommended + doc: | + Is the grain recrystallized. + dimensions: + rank: 1 + dim: [[1, n_grains]] + recrystallized_kinetics(NXprocess): + doc: | + Current recrystallized volume fraction. + value(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Currently evaluated actual recrystallized volume fraction. + This takes into account partially recrystallized cells. + target(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Currently desired target recrystallized volume fraction at + which the user requested to log a snapshot. + + # pressure(NXprocess): + # exists: optional + stress(NXprocess): + exists: optional + value(NX_NUMBER): + unit: NX_ANY + doc: | + Currently assumed globally applied Cauchy stress tensor on the ROI. + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + strain(NXprocess): + exists: optional + value(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Currently assumed globally applied Cauchy strain tensor on the ROI. + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + + # deformation_gradient(NXprocess): + # exists: optional + # magnetic_field(NXprocess): + # exists: optional + # electric_field(NXprocess): + # exists: optional + performance(NXcs_profiling): + current_working_directory: + command_line_call: + exists: optional + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + total_elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + number_of_threads(NX_POSINT): + number_of_gpus(NX_POSINT): + (NXcs_computer): + exists: recommended + name: + exists: recommended + operating_system: + \@version: + uuid: + exists: optional + (NXcs_cpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_gpu): + exists: ['min', '0', 'max', 'unbounded'] + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_mm_sys): + exists: ['min', '0', 'max', '1'] + total_physical_memory(NX_NUMBER): + (NXcs_io_sys): + exists: ['min', '0', 'max', '1'] + (NXcs_io_obj): + exists: ['min', '1', 'max', 'unbounded'] + technology: + max_physical_capacity(NX_NUMBER): + name: + exists: optional + (NXfabrication): + exists: recommended + identifier: + exists: optional + capabilities: + exists: optional + (NXcs_profiling_event): + start_time(NX_DATE_TIME): + exists: optional + end_time(NX_DATE_TIME): + exists: optional + description: + elapsed_time(NX_NUMBER): + number_of_processes(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_processes + in the NXcs_profiling super class. + number_of_threads(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + number_of_gpus(NX_POSINT): + + # exists: recommended + doc: | + Specify if it was different from the number_of_threads + in the NXcs_profiling super class. + max_virtual_memory_snapshot(NX_NUMBER): + exists: recommended + max_resident_memory_snapshot(NX_NUMBER): + exists: recommended diff --git a/contributed_definitions/nyaml/NXms_snapshot.yaml b/contributed_definitions/nyaml/NXms_snapshot.yaml new file mode 100644 index 0000000000..2c668ddd21 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_snapshot.yaml @@ -0,0 +1,79 @@ +category: base +doc: | + Base class for data on the state of the microstructure at a given + time/iteration. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXms_snapshot(NXobject): + comment: + doc: | + Is this time for a measurement or a simulation. + enumeration: [measurement, simulation] + time(NX_NUMBER): + unit: NX_TIME + doc: | + Measured or simulated physical time stamp for this snapshot. + Not to be confused with wall-clock timing or profiling data. + iteration(NX_INT): + unit: NX_UNITLESS + doc: | + Iteration or increment counter. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 727c20950297820e1d9da8230bb0ccaaeb162693eb09c7c72f831029a038bf23 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Base class for data on the state of the microstructure at a given +# time/iteration. +# +# +# +# Is this time for a measurement or a simulation. +# +# +# +# +# +# +# +# +# Measured or simulated physical time stamp for this snapshot. +# Not to be confused with wall-clock timing or profiling data. +# +# +# +# +# Iteration or increment counter. +# +# +# diff --git a/contributed_definitions/nyaml/NXms_snapshot_set.yaml b/contributed_definitions/nyaml/NXms_snapshot_set.yaml new file mode 100644 index 0000000000..6ce3b20223 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_snapshot_set.yaml @@ -0,0 +1,98 @@ +category: base +doc: | + A collection of spatiotemporal microstructure data. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXms_snapshot_set(NXobject): + comment: + doc: | + Is this set describing a measurement or a simulation? + enumeration: [measurement, simulation] + identifier_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which specifies the first index to be used for distinguishing + snapshots. Identifiers are defined either implicitly + or explicitly. For implicit indexing the identifiers are defined on the + interval [identifier_offset, identifier_offset+c-1]. + For explicit indexing the identifier array has to be defined. + + The identifier_offset field can for example be used to communicate if the + identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) + or from 0 (referred to as C-, Python-style index notation) respectively. + + # should we rather name snapshots explicitly always snapshot_1, snapshot_2 + # in which case identifier fields are not required, on the other hand + # if we give the names of the snapshots free via making them all capital + # how can we assure that snapshots are numbered consecutively? + # MS_SNAPSHOT + (NXms_snapshot): + + # exists: [min, 0, max, infty] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e9c6e090a782d50af20f1b70f91cd7299a386e1ad829ab70fea2cc1fbadff262 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# A collection of spatiotemporal microstructure data. +# +# +# +# Is this set describing a measurement or a simulation? +# +# +# +# +# +# +# +# +# Integer which specifies the first index to be used for distinguishing +# snapshots. Identifiers are defined either implicitly +# or explicitly. For implicit indexing the identifiers are defined on the +# interval [identifier_offset, identifier_offset+c-1]. +# For explicit indexing the identifier array has to be defined. +# +# The identifier_offset field can for example be used to communicate if the +# identifiers are expected to start from 1 (referred to as Fortran-/Matlab-) +# or from 0 (referred to as C-, Python-style index notation) respectively. +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXopt.yaml b/contributed_definitions/nyaml/NXopt.yaml new file mode 100644 index 0000000000..777076ff78 --- /dev/null +++ b/contributed_definitions/nyaml/NXopt.yaml @@ -0,0 +1,1502 @@ +category: application +doc: | + An application definition for optical spectroscopy experiments. +symbols: + doc: | + Variables used throughout the document, e.g. dimensions or parameters. + N_spectrum: | + Length of the spectrum array (e.g. wavelength or energy) of the measured + data. + N_sensors: | + Number of sensors used to measure parameters that influence the sample, + such as temperature or pressure. + N_measurements: | + Number of measurements (1st dimension of measured_data array). This is + equal to the number of parameters scanned. For example, if the experiment + was performed at three different temperatures and two different pressures + N_measurements = 2*3 = 6. + N_detection_angles: | + Number of detection angles of the beam reflected or scattered off the + sample. + N_incident_angles: | + Number of angles of incidence of the incident beam. + N_observables: | + Number of observables that are saved in a measurement. e.g. one for + intensity, reflectivity or transmittance, two for Psi and Delta etc. This + is equal to the second dimension of the data array 'measured_data' and the + number of column names. + +# 05/2023 +# Draft of a NeXus application definition which serves as a template for various +# optical spectroscopy experiments + +# To do: +# [ ] Check base classes (NXbeam_path + base classes used by it) +# [ ] Harmonize NXopt and NXellipsometry +# [ ] Fix dimensions and ranks +type: group +NXopt(NXobject): + (NXentry): + doc: | + An application definition template for optical spectroscopy experiments. + + A general optical experiment consists of a light or excitation source, a + beam path, a sample + its stage + its environment, and a detection unit. + Examples are reflection or transmission measurements, photoluminescence, + Raman spectroscopy, ellipsometry etc. + definition: + doc: | + An application definition describing a general optical experiment. + \@version: + doc: | + Version number to identify which definition of this application + definition was used for this entry/data. + \@url: + doc: | + URL where to find further material (documentation, examples) relevant + to the application definition. + enumeration: [NXopt] + experiment_identifier: + doc: | + A (globally persistent) unique identifier of the experiment. + (i) The identifier is usually defined by the facility or principle + investigator. + (ii) The identifier enables to link experiments to e.g. proposals. + experiment_description: + exists: optional + doc: | + An optional free-text description of the experiment. + + However, details of the experiment should be defined in the specific + fields of this application definition rather than in this experiment + description. + experiment_type: + doc: | + Specify the type of the optical experiment. + start_time(NX_DATE_TIME): + doc: | + Start time of the experiment. UTC offset should be specified. + (NXuser): + doc: | + Contact information of at least the user of the instrument or the + investigator who performed this experiment. + Adding multiple users, if relevant, is recommended. + name(NX_CHAR): + doc: | + Name of the user. + affiliation(NX_CHAR): + exists: recommended + doc: | + Name of the affiliation of the user at the point in time when the + experiment was performed. + address(NX_CHAR): + exists: recommended + doc: | + Street address of the user's affiliation. + email(NX_CHAR): + doc: | + Email address of the user. + orcid(NX_CHAR): + exists: recommended + doc: | + Author ID defined by https://orcid.org/. + telephone_number(NX_CHAR): + exists: recommended + doc: | + Telephone number of the user. + (NXinstrument): + doc: | + Properties of the experimental setup. This includes general information + about the instrument (such as model, company etc.), information about + the calibration of the instrument, elements of the beam path including + the excitation or light source and the detector unit, the sample stage + (plus the sample environment, which also includes sensors used to + monitor external conditions) and elements of the beam path. + + Meta data describing the sample should be specified in ENTRY/SAMPLE + outside of ENTRY/INSTRUMENT. + model: + doc: | + The name of the instrument. + \@version: + doc: | + The used version of the hardware if available. If not a commercial + instrument use date of completion of the hardware. + company: + exists: optional + doc: | + Name of the company which build the instrument. + construction_year(NX_DATE_TIME): + exists: optional + doc: | + ISO8601 date when the instrument was constructed. + UTC offset should be specified. + software(NXprocess): + program: + doc: | + Commercial or otherwise defined given name of the program that was + used to measure the data, i.e. the software used to start and + record the measured data and/or metadata. + If home written, one can provide the actual steps in the NOTE + subfield here. + version: + doc: | + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + \@url: + exists: optional + doc: | + Website of the software. + firmware(NXprogram): + exists: recommended + doc: | + Commercial or otherwise defined name of the firmware that was used + for the measurement - if available. + \@version: + doc: | + Version and build number or commit hash of the software source code. + \@url: + exists: optional + doc: | + Website of the software. + calibration_status(NX_CHAR): + doc: | + Was a calibration performed? If yes, when was it done? If the + calibration time is provided, it should be specified in + ENTRY/INSTRUMENT/calibration/calibration_time. + enumeration: [calibration time provided, no calibration, within 1 hour, within 1 day, within 1 week] + calibration(NXsubentry): + exists: recommended + doc: | + The calibration data and metadata should be described in a separate NeXus file + with the link provided in 'calibration_link'. + calibration_time(NX_DATE_TIME): + exists: optional + doc: | + If calibtration status is 'calibration time provided', specify the + ISO8601 date when calibration was last performed before this + measurement. UTC offset should be specified. + calibration_data_link: + doc: | + Link to the NeXus file containing the calibration data and metadata. + (NXbeam_path): + doc: | + Describes an arrangement of optical or other elements, e.g. the beam + path between the light source and the sample, or between the sample + and the detector unit (including the sources and detectors + themselves). + + If a beam splitter (i.e. a device that splits the incoming beam into + two or more beams) is part of the beam path, two or more NXbeam_path + fields may be needed to fully describe the beam paths and the correct + sequence of the beam path elements. + Use as many beam paths as needed to describe the setup. + angle_of_incidence(NX_NUMBER): + unit: NX_ANGLE + doc: | + Angle(s) of the incident beam vs. the normal of the bottom reflective + (substrate) surface in the sample. + dimensions: + rank: 1 + dim: [[1, N_incident_angles]] + \@units: + detection_angle(NX_NUMBER): + exists: optional + unit: NX_ANGLE + doc: | + Detection angle(s) of the beam reflected or scattered off the sample + vs. the normal of the bottom reflective (substrate) surface in the + sample if not equal to the angle(s) of incidence. + dimensions: + rank: 1 + dim: [[1, N_detection_angles]] + sample_stage(NXsubentry): + doc: | + Sample stage, holding the sample at a specific position in X,Y,Z + (Cartesian) coordinate system and at an orientation defined + by three Euler angles (alpha, beta, gamma). + stage_type: + doc: | + Specify the type of the sample stage. + enumeration: [manual stage, scanning stage, liquid stage, gas cell, cryostat] + alternative: + exists: optional + doc: | + If there is no motorized stage, we should at least qualify where + the beam hits the sample and in what direction the sample stands + in a free-text description, e.g. 'center of sample, long edge + parallel to the plane of incidence'. + environment_conditions(NXenvironment): + doc: | + Specify external parameters that have influenced the sample, such + as the surrounding medium, and varied parameters e.g. temperature, + pressure, pH value, optical excitation etc. + medium: + doc: | + Describe what was the medium above or around the sample. The + common model is built up from the substrate to the medium on the + other side. Both boundaries are assumed infinite in the model. + Here, define the name of the medium (e.g. water, air, UHV, etc.). + medium_refractive_indices(NX_FLOAT): + exists: optional + unit: NX_UNITLESS + doc: | + Array of pairs of complex refractive indices n + ik of the medium + for every measured spectral point/wavelength/energy. + Only necessary if the measurement was performed not in air, or + something very well known, e.g. high purity water. + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + PARAMETER(NXsensor): + exists: optional + doc: | + A sensor used to monitor an external condition influencing the + sample, such as temperature or pressure. It is suggested to + replace 'PARAMETER' by the type of the varied parameter defined + in 'parameter_type'. + The measured parameter values should be provided in 'values'. + For each parameter, a 'PARAMETER(NXsensor)' field needs to exist. + In other words, there are N_sensors 'PARAMETER(NXsensor)' fields. + parameter_type: + doc: | + Indicates which parameter was changed. Its definition must exist + below. The specified variable has to be N_measurements long, + providing the parameters for each data set. If you vary more than + one parameter simultaneously. + If the measured parameter is not contained in the list `other` + should be specified and the `parameter_type_name` should be provided. + enumeration: [conductivity, detection_angle, electric_field, flow, incident_angle, magnetic_field, optical_excitation, pH, pressure, resistance, shear, stage_positions, strain, stress, surface_pressure, temperature, voltage, other] + parameter_type_name: + exists: optional + doc: | + If the parameter_type is `other` a name should be specified here. + number_of_parameters(NX_POSINT): + unit: NX_UNITLESS + doc: | + Number of different parameter values at which the measurement + was performed. For example, if the measurement was performed at + temperatures of 4, 77 and 300 K, then number_of_parameters = 3. + values(NX_FLOAT): + unit: NX_ANY + doc: | + Vector containing the values of the varied parameter. Its + length is equal to N_measurements. The order of the values + should be as follows: + + * Order the sensors according to number_of_parameters starting + with the lowest number. If number_of_parameters is equal for + two sensors order them alphabetically (sensor/parameter name). + * The first sensor's j parameters should be ordered in the + following way. The first N_measurements/number_of_parameters + entries of the vector contain the first parameter (a1), the + second N_measurements/number_of_parameters contain the second + parameter (a2) etc., so the vector looks like: + [ + a1,a1,...,a1, + a2,a2,...,a2, + ... + aj,aj,...aj + ] + * The kth sensor's m parameters should be ordered in the + following way: + [ + p1,...p1,p2,...,p2,...pm,...,pm, + p1,...p1,p2,...,p2,...pm,...,pm, + ... + p1,...p1,p2,...,p2,...pm,...,pm + ] + * The last sensor's n parameters should be ordered in the + following way: + [ + z1,z2,...,zn, + z1,z2,...,zn, + ... + z1,z2,...,zn] + + For example, if the experiment was performed at three different + temperatures (T1, T2, T3), two different pressures (p1, p2) and + two different angles of incidence (a1, a2), then + N_measurements = 12 and the order of the values for the various + parameter vectors is: + + * angle_of_incidence: [a1,a1,a1,a1,a1,a1,a2,a2,a2,a2,a2,a2] + * pressure: [p1,p1,p1,p2,p2,p2,p1,p1,p1,p2,p2,p2] + * temperature: [T1,T2,T3,T1,T2,T3,T1,T2,T3,T1,T2,T3] + dimensions: + rank: 1 + dim: [[1, N_measurements]] + WINDOW(NXaperture): + exists: optional + doc: | + For environmental measurements, the environment (liquid, vapor + etc.) is enclosed in a cell, which has windows both in the + direction of the source (entry window) and the detector (exit + window) (looking from the sample). In case that the entry and exit + windows are not the same type and do not have the same properties, + use a second 'WINDOW(MXaperture)' field. + + The windows also add a phase shift to the light altering the + measured signal. This shift has to be corrected based on measuring + a known sample (reference sample) or the actual sample of interest + in the environmental cell. State if a window correction has been + performed in 'window_effects_corrected'. Reference data should be + considered as a separate experiment, and a link to the NeXus file + should be added in reference_data_link in measured_data. + + The window is considered to be a part of the sample stage but also + beam path. Hence, its position within the beam path should be + defined by the 'depends_on' field. + depends_on: + exists: recommended + doc: | + Specify the position of the window in the beam path by pointing + to the preceding element in the sequence of beam path elements. + window_effects_corrected(NX_BOOLEAN): + doc: | + Was a window correction performed? If 'True' describe the window + correction procedure in 'window_correction/procedure'. + window_correction(NXprocess): + exists: optional + doc: | + Was a window correction performed? If 'True' describe the + window correction procedure in '' + procedure: + doc: | + Describe when (before or after the main measurement + time + stamp in 'date') and how the window effects have been + corrected, i.e. either mathematically or by performing a + reference measurement. In the latter case, provide the link to + to the reference data in 'reference_data_link'. + reference_data_link: + exists: optional + doc: | + Link to the NeXus file which describes the reference data if a + reference measurement for window correction was performed. + Ideally, the reference measurement was performed on a reference + sample and on the same sample, and using the same conditions as + for the actual measurement with and without windows. It should + have been conducted as close in time to the actual measurement + as possible. + material(NX_CHAR): + doc: | + The material of the window. + enumeration: [quartz, diamond, calcium fluoride, zinc selenide, thallium bromoiodide, alkali halide compound, Mylar, other] + other_material(NX_CHAR): + exists: optional + doc: | + If you specified 'other' as material, decsribe here what it is. + thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the window. + orientation_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angle of the window normal (outer) vs. the substrate normal + (similar to the angle of incidence). + (NXsample): + doc: | + Properties of the sample, such as sample type, layer structure, + chemical formula, atom types, its history etc. + Information about the sample stage and sample environment should be + described in ENTRY/INSTRUMENT/sample_stage. + sample_name: + doc: | + Descriptive name of the sample + sample_type: + doc: | + Specify the type of sample, e.g. thin film, single crystal etc. + enumeration: [thin film, single crystal, poly crystal, single layer, multi layer] + layer_structure: + doc: | + Qualitative description of the layer structure for the sample, + starting with the top layer (i.e. the one on the front surface, on + which the light incident), e.g. native oxide/bulk substrate, or + Si/native oxide/thermal oxide/polymer/peptide. + chemical_formula: + doc: | + Chemical formula of the sample. Use the Hill system (explained here: + https://en.wikipedia.org/wiki/Chemical_formula#Hill_system) to write + the chemical formula. In case the sample consists of several layers, + this should be a list of the chemical formulas of the individual + layers, where the first entry is the chemical formula of the top + layer (the one on the front surface, on which the light incident). + The order must be consistent with layer_structure + atom_types: + doc: | + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + 'atom_types'. + sample_history: + doc: | + Ideally, a reference to the location or a unique (globally + persistent) identifier (e.g.) of e.g. another file which gives + as many as possible details of the material, its microstructure, + and its thermo-chemo-mechanical processing/preparation history. + In the case that such a detailed history of the sample is not + available, use this field as a free-text description to specify + details of the sample and its preparation. + preparation_date(NX_DATE_TIME): + exists: recommended + doc: | + ISO8601 date with time zone (UTC offset) specified. + substrate: + exists: recommended + doc: | + Description of the substrate. + sample_orientation: + exists: optional + doc: | + Specify the sample orientation. + data_collection(NXprocess): + doc: | + Measured data, data errors, and varied parameters. If reference data + were measured they should be considered a separate experiment and a + link to its NeXus file should be added in reference_data_link. + data_identifier(NX_NUMBER): + doc: | + An identifier to correlate data to the experimental conditions, + if several were used in this measurement; typically an index of 0-N. + data_type: + doc: | + Select which type of data was recorded, for example intensity, + reflectivity, transmittance, Psi and Delta etc. + It is possible to have multiple selections. The enumeration list + depends on the type of experiment and may differ for different + application definitions. + enumeration: [intensity, reflectivity, transmittance, Psi/Delta, tan(Psi)/cos(Delta), Mueller matrix, Jones matrix, N/C/S, raw data] + + # This should be a required field, but is set to 'optional' for the moment + NAME_spectrum(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Spectral values (e.g. wavelength or energy) used for the measurement. + An array of 1 or more elements. Length defines N_spectrum. Replace + 'SPECTRUM' by the physical quantity that is used, e.g. wavelength. + dimensions: + rank: 1 + dim: [[1, N_spectrum]] + \@units: + exists: optional + doc: | + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + measured_data(NX_FLOAT): + unit: NX_ANY + doc: | + Resulting data from the measurement, described by 'data_type'. + + The first dimension is defined by the number of measurements taken, + (N_measurements). The instructions on how to order the values + contained in the parameter vectors given in the doc string of + INSTRUMENT/sample_stage/environment_conditions/PARAMETER/values, + define the N_measurements parameter sets. For example, if the + experiment was performed at three different temperatures + (T1, T2, T3), two different pressures (p1, p2) and two different + angles of incidence (a1, a2), the first measurement was taken at the + parameters {a1,p1,T1}, the second measurement at {a1,p1,T2} etc. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, N_observables], [3, N_spectrum]] + \@units: + exists: optional + doc: | + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + measured_data_errors(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + Specified uncertainties (errors) of the data described by 'data_type' + and provided in 'measured_data'. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, N_observables], [3, N_spectrum]] + \@units: + exists: optional + doc: | + If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. + If the unit of the measured data is not covered by NXDL units state + here which unit was used. + varied_parameter_link: + exists: optional + doc: | + List of links to the values of the sensors. Add a link for each + varied parameter (i.e. for each sensor). + dimensions: + rank: 1 + dim: [[1, N_sensors]] + reference_data_link: + exists: optional + doc: | + Link to the NeXus file which describes the reference data if a + reference measurement was performed. Ideally, the reference + measurement was performed using the same conditions as the actual + measurement and should be as close in time to the actual measurement + as possible. + data_software(NXprocess): + exists: optional + program: + doc: | + Commercial or otherwise defined given name of the program that was + used to generate the result file(s) with measured data and/or + metadata (in most cases, this is the same as INSTRUMENT/software). + If home written, one can provide the actual steps in the NOTE + subfield here. + version: + doc: | + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + \@url: + exists: optional + doc: | + Website of the software. + (NXdata): + exists: optional + doc: | + A plot of the multi-dimensional data array provided in + ENTRY/data/measured_data. + \@axes: + doc: | + Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) + derived_parameters(NXprocess): + exists: optional + doc: | + Parameters that are derived from the measured data. + depolarization(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + Light loss due to depolarization as a value in [0-1]. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, 1], [3, N_spectrum]] + Jones_quality_factor(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + Jones quality factor. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, 1], [3, N_spectrum]] + reflectivity(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + Reflectivity. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, 1], [3, N_spectrum]] + transmittance(NX_NUMBER): + exists: optional + unit: NX_UNITLESS + doc: | + Transmittance. + dimensions: + rank: 3 + dim: [[1, N_measurements], [2, 1], [3, N_spectrum]] + ANALYSIS_program(NXprocess): + exists: optional + program: + doc: | + Commercial or otherwise defined given name of the program that was + used to generate or calculate the derived parameters. + If home written, one can provide the actual steps in the NOTE + subfield here. + version: + doc: | + Either version with build number, commit hash, or description of a + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + plot(NXdata): + doc: | + A default view of the data provided in ENTRY/data_collection/measured_data. This + should be the part of the data set which provides the most suitable + representation of the data. + \@axes: + doc: | + Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7d68d553b6c55f5cdd8fe8d92c325b137c71c875c2bd742f5cf2150df56f4398 +# +# +# +# +# +# +# +# +# Variables used throughout the document, e.g. dimensions or parameters. +# +# +# +# Length of the spectrum array (e.g. wavelength or energy) of the measured +# data. +# +# +# +# +# Number of sensors used to measure parameters that influence the sample, +# such as temperature or pressure. +# +# +# +# +# Number of measurements (1st dimension of measured_data array). This is +# equal to the number of parameters scanned. For example, if the experiment +# was performed at three different temperatures and two different pressures +# N_measurements = 2*3 = 6. +# +# +# +# +# Number of detection angles of the beam reflected or scattered off the +# sample. +# +# +# +# +# Number of angles of incidence of the incident beam. +# +# +# +# +# Number of observables that are saved in a measurement. e.g. one for +# intensity, reflectivity or transmittance, two for Psi and Delta etc. This +# is equal to the second dimension of the data array 'measured_data' and the +# number of column names. +# +# +# +# +# An application definition for optical spectroscopy experiments. +# +# +# +# An application definition template for optical spectroscopy experiments. +# +# A general optical experiment consists of a light or excitation source, a +# beam path, a sample + its stage + its environment, and a detection unit. +# Examples are reflection or transmission measurements, photoluminescence, +# Raman spectroscopy, ellipsometry etc. +# +# +# +# An application definition describing a general optical experiment. +# +# +# +# Version number to identify which definition of this application +# definition was used for this entry/data. +# +# +# +# +# URL where to find further material (documentation, examples) relevant +# to the application definition. +# +# +# +# +# +# +# +# +# A (globally persistent) unique identifier of the experiment. +# (i) The identifier is usually defined by the facility or principle +# investigator. +# (ii) The identifier enables to link experiments to e.g. proposals. +# +# +# +# +# An optional free-text description of the experiment. +# +# However, details of the experiment should be defined in the specific +# fields of this application definition rather than in this experiment +# description. +# +# +# +# +# Specify the type of the optical experiment. +# +# +# +# +# Start time of the experiment. UTC offset should be specified. +# +# +# +# +# Contact information of at least the user of the instrument or the +# investigator who performed this experiment. +# Adding multiple users, if relevant, is recommended. +# +# +# +# Name of the user. +# +# +# +# +# Name of the affiliation of the user at the point in time when the +# experiment was performed. +# +# +# +# +# Street address of the user's affiliation. +# +# +# +# +# Email address of the user. +# +# +# +# +# Author ID defined by https://orcid.org/. +# +# +# +# +# Telephone number of the user. +# +# +# +# +# +# Properties of the experimental setup. This includes general information +# about the instrument (such as model, company etc.), information about +# the calibration of the instrument, elements of the beam path including +# the excitation or light source and the detector unit, the sample stage +# (plus the sample environment, which also includes sensors used to +# monitor external conditions) and elements of the beam path. +# +# Meta data describing the sample should be specified in ENTRY/SAMPLE +# outside of ENTRY/INSTRUMENT. +# +# +# +# The name of the instrument. +# +# +# +# The used version of the hardware if available. If not a commercial +# instrument use date of completion of the hardware. +# +# +# +# +# +# Name of the company which build the instrument. +# +# +# +# +# ISO8601 date when the instrument was constructed. +# UTC offset should be specified. +# +# +# +# +# +# Commercial or otherwise defined given name of the program that was +# used to measure the data, i.e. the software used to start and +# record the measured data and/or metadata. +# If home written, one can provide the actual steps in the NOTE +# subfield here. +# +# +# +# +# Either version with build number, commit hash, or description of a +# (online) repository where the source code of the program and build +# instructions can be found so that the program can be configured in +# such a way that result files can be created ideally in a +# deterministic manner. +# +# +# +# +# Website of the software. +# +# +# +# +# +# Commercial or otherwise defined name of the firmware that was used +# for the measurement - if available. +# +# +# +# Version and build number or commit hash of the software source code. +# +# +# +# +# Website of the software. +# +# +# +# +# +# Was a calibration performed? If yes, when was it done? If the +# calibration time is provided, it should be specified in +# ENTRY/INSTRUMENT/calibration/calibration_time. +# +# +# +# +# +# +# +# +# +# +# +# The calibration data and metadata should be described in a separate NeXus file +# with the link provided in 'calibration_link'. +# +# +# +# If calibtration status is 'calibration time provided', specify the +# ISO8601 date when calibration was last performed before this +# measurement. UTC offset should be specified. +# +# +# +# +# Link to the NeXus file containing the calibration data and metadata. +# +# +# +# +# +# Describes an arrangement of optical or other elements, e.g. the beam +# path between the light source and the sample, or between the sample +# and the detector unit (including the sources and detectors +# themselves). +# +# If a beam splitter (i.e. a device that splits the incoming beam into +# two or more beams) is part of the beam path, two or more NXbeam_path +# fields may be needed to fully describe the beam paths and the correct +# sequence of the beam path elements. +# Use as many beam paths as needed to describe the setup. +# +# +# +# +# Angle(s) of the incident beam vs. the normal of the bottom reflective +# (substrate) surface in the sample. +# +# +# +# +# +# +# +# +# Detection angle(s) of the beam reflected or scattered off the sample +# vs. the normal of the bottom reflective (substrate) surface in the +# sample if not equal to the angle(s) of incidence. +# +# +# +# +# +# +# +# Sample stage, holding the sample at a specific position in X,Y,Z +# (Cartesian) coordinate system and at an orientation defined +# by three Euler angles (alpha, beta, gamma). +# +# +# +# Specify the type of the sample stage. +# +# +# +# +# +# +# +# +# +# +# +# If there is no motorized stage, we should at least qualify where +# the beam hits the sample and in what direction the sample stands +# in a free-text description, e.g. 'center of sample, long edge +# parallel to the plane of incidence'. +# +# +# +# +# Specify external parameters that have influenced the sample, such +# as the surrounding medium, and varied parameters e.g. temperature, +# pressure, pH value, optical excitation etc. +# +# +# +# Describe what was the medium above or around the sample. The +# common model is built up from the substrate to the medium on the +# other side. Both boundaries are assumed infinite in the model. +# Here, define the name of the medium (e.g. water, air, UHV, etc.). +# +# +# +# +# Array of pairs of complex refractive indices n + ik of the medium +# for every measured spectral point/wavelength/energy. +# Only necessary if the measurement was performed not in air, or +# something very well known, e.g. high purity water. +# +# +# +# +# +# +# +# +# A sensor used to monitor an external condition influencing the +# sample, such as temperature or pressure. It is suggested to +# replace 'PARAMETER' by the type of the varied parameter defined +# in 'parameter_type'. +# The measured parameter values should be provided in 'values'. +# For each parameter, a 'PARAMETER(NXsensor)' field needs to exist. +# In other words, there are N_sensors 'PARAMETER(NXsensor)' fields. +# +# +# +# Indicates which parameter was changed. Its definition must exist +# below. The specified variable has to be N_measurements long, +# providing the parameters for each data set. If you vary more than +# one parameter simultaneously. +# If the measured parameter is not contained in the list `other` +# should be specified and the `parameter_type_name` should be provided. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If the parameter_type is `other` a name should be specified here. +# +# +# +# +# Number of different parameter values at which the measurement +# was performed. For example, if the measurement was performed at +# temperatures of 4, 77 and 300 K, then number_of_parameters = 3. +# +# +# +# +# Vector containing the values of the varied parameter. Its +# length is equal to N_measurements. The order of the values +# should be as follows: +# +# * Order the sensors according to number_of_parameters starting +# with the lowest number. If number_of_parameters is equal for +# two sensors order them alphabetically (sensor/parameter name). +# * The first sensor's j parameters should be ordered in the +# following way. The first N_measurements/number_of_parameters +# entries of the vector contain the first parameter (a1), the +# second N_measurements/number_of_parameters contain the second +# parameter (a2) etc., so the vector looks like: +# [ +# a1,a1,...,a1, +# a2,a2,...,a2, +# ... +# aj,aj,...aj +# ] +# * The kth sensor's m parameters should be ordered in the +# following way: +# [ +# p1,...p1,p2,...,p2,...pm,...,pm, +# p1,...p1,p2,...,p2,...pm,...,pm, +# ... +# p1,...p1,p2,...,p2,...pm,...,pm +# ] +# * The last sensor's n parameters should be ordered in the +# following way: +# [ +# z1,z2,...,zn, +# z1,z2,...,zn, +# ... +# z1,z2,...,zn] +# +# For example, if the experiment was performed at three different +# temperatures (T1, T2, T3), two different pressures (p1, p2) and +# two different angles of incidence (a1, a2), then +# N_measurements = 12 and the order of the values for the various +# parameter vectors is: +# +# * angle_of_incidence: [a1,a1,a1,a1,a1,a1,a2,a2,a2,a2,a2,a2] +# * pressure: [p1,p1,p1,p2,p2,p2,p1,p1,p1,p2,p2,p2] +# * temperature: [T1,T2,T3,T1,T2,T3,T1,T2,T3,T1,T2,T3] +# +# +# +# +# +# +# +# +# +# For environmental measurements, the environment (liquid, vapor +# etc.) is enclosed in a cell, which has windows both in the +# direction of the source (entry window) and the detector (exit +# window) (looking from the sample). In case that the entry and exit +# windows are not the same type and do not have the same properties, +# use a second 'WINDOW(MXaperture)' field. +# +# The windows also add a phase shift to the light altering the +# measured signal. This shift has to be corrected based on measuring +# a known sample (reference sample) or the actual sample of interest +# in the environmental cell. State if a window correction has been +# performed in 'window_effects_corrected'. Reference data should be +# considered as a separate experiment, and a link to the NeXus file +# should be added in reference_data_link in measured_data. +# +# The window is considered to be a part of the sample stage but also +# beam path. Hence, its position within the beam path should be +# defined by the 'depends_on' field. +# +# +# +# Specify the position of the window in the beam path by pointing +# to the preceding element in the sequence of beam path elements. +# +# +# +# +# Was a window correction performed? If 'True' describe the window +# correction procedure in 'window_correction/procedure'. +# +# +# +# +# Was a window correction performed? If 'True' describe the +# window correction procedure in '' +# +# +# +# Describe when (before or after the main measurement + time +# stamp in 'date') and how the window effects have been +# corrected, i.e. either mathematically or by performing a +# reference measurement. In the latter case, provide the link to +# to the reference data in 'reference_data_link'. +# +# +# +# +# Link to the NeXus file which describes the reference data if a +# reference measurement for window correction was performed. +# Ideally, the reference measurement was performed on a reference +# sample and on the same sample, and using the same conditions as +# for the actual measurement with and without windows. It should +# have been conducted as close in time to the actual measurement +# as possible. +# +# +# +# +# +# The material of the window. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you specified 'other' as material, decsribe here what it is. +# +# +# +# +# Thickness of the window. +# +# +# +# +# Angle of the window normal (outer) vs. the substrate normal +# (similar to the angle of incidence). +# +# +# +# +# +# +# +# Properties of the sample, such as sample type, layer structure, +# chemical formula, atom types, its history etc. +# Information about the sample stage and sample environment should be +# described in ENTRY/INSTRUMENT/sample_stage. +# +# +# +# Descriptive name of the sample +# +# +# +# +# Specify the type of sample, e.g. thin film, single crystal etc. +# +# +# +# +# +# +# +# +# +# +# +# Qualitative description of the layer structure for the sample, +# starting with the top layer (i.e. the one on the front surface, on +# which the light incident), e.g. native oxide/bulk substrate, or +# Si/native oxide/thermal oxide/polymer/peptide. +# +# +# +# +# Chemical formula of the sample. Use the Hill system (explained here: +# https://en.wikipedia.org/wiki/Chemical_formula#Hill_system) to write +# the chemical formula. In case the sample consists of several layers, +# this should be a list of the chemical formulas of the individual +# layers, where the first entry is the chemical formula of the top +# layer (the one on the front surface, on which the light incident). +# The order must be consistent with layer_structure +# +# +# +# +# List of comma-separated elements from the periodic table that are +# contained in the sample. If the sample substance has multiple +# components, all elements from each component must be included in +# 'atom_types'. +# +# +# +# +# Ideally, a reference to the location or a unique (globally +# persistent) identifier (e.g.) of e.g. another file which gives +# as many as possible details of the material, its microstructure, +# and its thermo-chemo-mechanical processing/preparation history. +# In the case that such a detailed history of the sample is not +# available, use this field as a free-text description to specify +# details of the sample and its preparation. +# +# +# +# +# ISO8601 date with time zone (UTC offset) specified. +# +# +# +# +# Description of the substrate. +# +# +# +# +# Specify the sample orientation. +# +# +# +# +# +# Measured data, data errors, and varied parameters. If reference data +# were measured they should be considered a separate experiment and a +# link to its NeXus file should be added in reference_data_link. +# +# +# +# An identifier to correlate data to the experimental conditions, +# if several were used in this measurement; typically an index of 0-N. +# +# +# +# +# Select which type of data was recorded, for example intensity, +# reflectivity, transmittance, Psi and Delta etc. +# It is possible to have multiple selections. The enumeration list +# depends on the type of experiment and may differ for different +# application definitions. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Spectral values (e.g. wavelength or energy) used for the measurement. +# An array of 1 or more elements. Length defines N_spectrum. Replace +# 'SPECTRUM' by the physical quantity that is used, e.g. wavelength. +# +# +# +# +# +# +# If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. +# If the unit of the measured data is not covered by NXDL units state +# here which unit was used. +# +# +# +# +# +# Resulting data from the measurement, described by 'data_type'. +# +# The first dimension is defined by the number of measurements taken, +# (N_measurements). The instructions on how to order the values +# contained in the parameter vectors given in the doc string of +# INSTRUMENT/sample_stage/environment_conditions/PARAMETER/values, +# define the N_measurements parameter sets. For example, if the +# experiment was performed at three different temperatures +# (T1, T2, T3), two different pressures (p1, p2) and two different +# angles of incidence (a1, a2), the first measurement was taken at the +# parameters {a1,p1,T1}, the second measurement at {a1,p1,T2} etc. +# +# +# +# +# +# +# +# +# If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. +# If the unit of the measured data is not covered by NXDL units state +# here which unit was used. +# +# +# +# +# +# Specified uncertainties (errors) of the data described by 'data_type' +# and provided in 'measured_data'. +# +# +# +# +# +# +# +# +# If applicable, change 'unit: NX_ANY' to the appropriate NXDL unit. +# If the unit of the measured data is not covered by NXDL units state +# here which unit was used. +# +# +# +# +# +# List of links to the values of the sensors. Add a link for each +# varied parameter (i.e. for each sensor). +# +# +# +# +# +# +# +# Link to the NeXus file which describes the reference data if a +# reference measurement was performed. Ideally, the reference +# measurement was performed using the same conditions as the actual +# measurement and should be as close in time to the actual measurement +# as possible. +# +# +# +# +# +# Commercial or otherwise defined given name of the program that was +# used to generate the result file(s) with measured data and/or +# metadata (in most cases, this is the same as INSTRUMENT/software). +# If home written, one can provide the actual steps in the NOTE +# subfield here. +# +# +# +# +# Either version with build number, commit hash, or description of a +# (online) repository where the source code of the program and build +# instructions can be found so that the program can be configured in +# such a way that result files can be created ideally in a +# deterministic manner. +# +# +# +# +# Website of the software. +# +# +# +# +# +# A plot of the multi-dimensional data array provided in +# ENTRY/data/measured_data. +# +# +# +# Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) +# +# +# +# +# +# +# Parameters that are derived from the measured data. +# +# +# +# Light loss due to depolarization as a value in [0-1]. +# +# +# +# +# +# +# +# +# +# Jones quality factor. +# +# +# +# +# +# +# +# +# +# Reflectivity. +# +# +# +# +# +# +# +# +# +# Transmittance. +# +# +# +# +# +# +# +# +# +# +# Commercial or otherwise defined given name of the program that was +# used to generate or calculate the derived parameters. +# If home written, one can provide the actual steps in the NOTE +# subfield here. +# +# +# +# +# Either version with build number, commit hash, or description of a +# (online) repository where the source code of the program and build +# instructions can be found so that the program can be configured in +# such a way that result files can be created ideally in a +# deterministic manner. +# +# +# +# +# +# +# A default view of the data provided in ENTRY/data_collection/measured_data. This +# should be the part of the data set which provides the most suitable +# representation of the data. +# +# +# +# Spectrum, i.e. x-axis of the data (e.g. wavelength, energy etc.) +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXoptical_system_em.yaml b/contributed_definitions/nyaml/NXoptical_system_em.yaml new file mode 100644 index 0000000000..5ed2c4be33 --- /dev/null +++ b/contributed_definitions/nyaml/NXoptical_system_em.yaml @@ -0,0 +1,59 @@ +category: base +doc: | + A container for qualifying an electron optical system. +type: group +NXoptical_system_em(NXobject): + # NEW ISSUE: for now used to store difficult to place entries + # NEW ISSUE: all the definitions here should better be backed up by the + # work of the HMC EM glossary activities + camera_length(NX_NUMBER): + doc: | + Citing the JEOL TEM glossary this is *an effective distance from a specimen + to a plane where an observed diffraction pattern is formed*. + unit: NX_LENGTH + magnification(NX_NUMBER): # R+ otherwise it is demagnification + doc: | + The factor of enlargement of the apparent size, + not the physical size, of an object. + unit: NX_DIMENSIONLESS + defocus(NX_NUMBER): + unit: NX_LENGTH + doc: | + The defocus aberration constant (oftentimes referred to as C_1_0). + See respective details in :ref:`NXaberration` class instances. + semi_convergence_angle(NX_NUMBER): + doc: | + Citing the JEOL TEM glosssary this is the value *when a cone shaped, + convergent electron beam illuminates a specimen, the semi-angle of the cone + is termed convergence angle.* + unit: NX_ANGLE + field_of_view(NX_NUMBER): + doc: | + The extent of the observable parts of the specimen given the current + magnification and other settings of the instrument. + unit: NX_LENGTH + working_distance(NX_NUMBER): + doc: | + Citing `Globalsino `_ this is + *a distance between the specimen and the lower pole piece in SEM system*. + unit: NX_LENGTH + beam_current(NX_NUMBER): + # see AXON Dose monitoring paper doi:10.1017/S1551929522000840 + # this is the nominal dose rate e-/(angstrom^2*s) + doc: | + Beam current as measured relevant for the illumination of the specimen. + Users should specify further details like how the beam current + was measured using the beam_current_description field. + unit: NX_CURRENT + # replace with a dedicated base class to describe the dose rate, accumulated dose, dose rate history + # based on the AXON Dose monitoring suggestions, for this one could also have an NXdose_monitoring base class + # alternatively as that dose monitoring instrument as it is also described in the paper + # is a modified Faraday cup sensor one could also wrap that detector in this base dose monitoring base class + beam_current_description(NX_CHAR): + doc: | + Specify further details how the beam current was measured or estimated. + + # NEW ISSUE: the KIT/SCC propose: + # adding of the image_mode or field mode + # imageMode: enum: [normal_image, sad, eds, nbd, cbed] + # fieldMode: enum: [dark_field, bright_field] diff --git a/contributed_definitions/nyaml/NXpeak.yaml b/contributed_definitions/nyaml/NXpeak.yaml new file mode 100644 index 0000000000..401c3b497d --- /dev/null +++ b/contributed_definitions/nyaml/NXpeak.yaml @@ -0,0 +1,136 @@ +category: base +doc: | + Description of peaks, their functional form or measured support. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_support: | + Number of support points +type: group +NXpeak(NXobject): + label: + doc: | + Human-readable identifier to specify which concept/entity + the peak represents/identifies. + peak_model: + doc: | + Is the peak described analytically via a functional form + or is it empirically defined via measured/reported + intensity/counts as a function of an independent variable. + + If the functional form is not empirical or gaussian, users + should enter other for the peak_model and add relevant details + in the NXcollection. + enumeration: [empirical, gaussian, lorentzian, other] + position(NX_NUMBER): + unit: NX_ANY + doc: | + In the case of an empirical description of the peak and its shoulders, + this array holds the position values for the independent variable. + dimensions: + rank: 1 + dim: [[1, n_support]] + intensity(NX_NUMBER): + unit: NX_ANY + doc: | + In the case of an empirical description of the peak and its shoulders, + this array holds the intensity/count values at each position. + dimensions: + rank: 1 + dim: [[1, n_support]] + (NXcollection): + doc: | + In the case of an analytical description (or if peak_model is other) this + collection holds parameter of (and eventually) the functional form. + For example in the case of Gaussians mu, sigma, cut-off values, + and background intensity are relevant parameter. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 40c5d1ea859b17085a2dacf79ad49f540f43ddf2d8e2374a0adb1ef5cd9434ea +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of support points +# +# +# +# +# Description of peaks, their functional form or measured support. +# +# +# +# Human-readable identifier to specify which concept/entity +# the peak represents/identifies. +# +# +# +# +# Is the peak described analytically via a functional form +# or is it empirically defined via measured/reported +# intensity/counts as a function of an independent variable. +# +# If the functional form is not empirical or gaussian, users +# should enter other for the peak_model and add relevant details +# in the NXcollection. +# +# +# +# +# +# +# +# +# +# +# In the case of an empirical description of the peak and its shoulders, +# this array holds the position values for the independent variable. +# +# +# +# +# +# +# +# In the case of an empirical description of the peak and its shoulders, +# this array holds the intensity/count values at each position. +# +# +# +# +# +# +# +# In the case of an analytical description (or if peak_model is other) this +# collection holds parameter of (and eventually) the functional form. +# For example in the case of Gaussians mu, sigma, cut-off values, +# and background intensity are relevant parameter. +# +# +# diff --git a/contributed_definitions/nyaml/NXphysical_process.yaml b/contributed_definitions/nyaml/NXphysical_process.yaml new file mode 100644 index 0000000000..24a515e973 --- /dev/null +++ b/contributed_definitions/nyaml/NXphysical_process.yaml @@ -0,0 +1,92 @@ +category: base +doc: | + A planned or unplanned process which results in physical changes in a specified material. + + A physical change involve changes only in intermolecular forces, not in the chemical bonds. + Examples include sample preparation, material transformation, or (partially) destructive measurements. +type: group +NXphysical_process(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 formatted time code (with local time zone offset to UTC information + included) when this process ended. + description: + doc: | + Short description of the activity. + method: + doc: | + Method by which this process was performed. + notes(NXnote): + doc: | + This can be any data or other descriptor acquired during the physical process + (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5792f0ac3cb2c2b5c936e7046ea9dc831875bc6ab9e674c6f705fe2e252c08ce +# +# +# +# +# +# A planned or unplanned process which results in physical changes in a specified material. +# +# A physical change involve changes only in intermolecular forces, not in the chemical bonds. +# Examples include sample preparation, material transformation, or (partially) destructive measurements. +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this process started. +# +# +# +# +# ISO 8601 formatted time code (with local time zone offset to UTC information +# included) when this process ended. +# +# +# +# +# Short description of the activity. +# +# +# +# +# Method by which this process was performed. +# +# +# +# +# This can be any data or other descriptor acquired during the physical process +# (NXnote allows to add pictures, audio, movies). Alternatively, a +# reference to the location or a unique identifier or other metadata file. In the +# case these are not available, free-text description. +# +# +# diff --git a/contributed_definitions/nyaml/NXpid.yaml b/contributed_definitions/nyaml/NXpid.yaml new file mode 100644 index 0000000000..2804bf46a8 --- /dev/null +++ b/contributed_definitions/nyaml/NXpid.yaml @@ -0,0 +1,159 @@ +category: base +doc: | + Contains the settings of a PID controller. +type: group +NXpid(NXobject): + description: + doc: | + Description of how the Process Value for the PID controller is produced by sensor(s) in the setup. + + For example, a set of sensors could be averaged over before feeding it back into the loop. + pv_sensor(NXsensor): + doc: | + The sensor representing the Process Value used in the feedback loop for the PID. + + In case multiple sensors were used, this NXsensor should contain the proper calculated/aggregated value. + value_log(NXlog): + value(NX_NUMBER): + doc: | + The actual timeseries data fed back to the PID loop. + setpoint(NX_FLOAT): + unit: NX_ANY + doc: | + The Setpoint(s) used as an input for the PID controller. + + It can also be a link to an NXsensor.value field. + setpoint_log(NXlog): + doc: | + Time log of the setpoint(s) used as an input for the PID controller. + K_p_value(NX_NUMBER): + doc: | + Proportional term. The proportional term produces an output value + that is proportional to the current error value. + The proportional response can be adjusted by multiplying the error + by a constant Kp, called the proportional gain constant. + The Type switches controller parameters between P/I (proportional gain/integral gain) and P/T (proportional gain/time constant). The formula for the controller in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and time constant are related as follows I = P/T. + K_i_value(NX_NUMBER): + doc: | + The contribution from the integral term is proportional to both + the magnitude of the error and the duration of the error. + The integral in a PID controller is the sum of the instantaneous + error over time and gives the accumulated offset that should have + been corrected previously. The accumulated error is then + multiplied by the integral gain (Ki) and added to the + controller output. + K_d_value(NX_NUMBER): + doc: | + The derivative of the process error is calculated by determining + the slope of the error over time and multiplying this rate of + change by the derivative gain K_d. The magnitude of the + contribution of the derivative term to the overall control + action is termed the derivative gain, K_d + K_t_const(NX_NUMBER): + unit: NX_TIME + doc: | + The Type switches controller parameters between P/I (proportional gain/integral + gain) and P/T (proportional gain/time constant). The formula for the controller + in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and + time constant are related as follows I = P/T. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# aadcc7fe3aacdc2888a03ae22cc82dc7e65996a3dce2e0af4d6bd0a9fcfcecee +# +# +# +# +# +# Contains the settings of a PID controller. +# +# +# +# Description of how the Process Value for the PID controller is produced by sensor(s) in the setup. +# +# For example, a set of sensors could be averaged over before feeding it back into the loop. +# +# +# +# +# The sensor representing the Process Value used in the feedback loop for the PID. +# +# In case multiple sensors were used, this NXsensor should contain the proper calculated/aggregated value. +# +# +# +# +# The actual timeseries data fed back to the PID loop. +# +# +# +# +# +# +# The Setpoint(s) used as an input for the PID controller. +# +# It can also be a link to an NXsensor.value field. +# +# +# +# +# Time log of the setpoint(s) used as an input for the PID controller. +# +# +# +# +# Proportional term. The proportional term produces an output value +# that is proportional to the current error value. +# The proportional response can be adjusted by multiplying the error +# by a constant Kp, called the proportional gain constant. +# The Type switches controller parameters between P/I (proportional gain/integral gain) and P/T (proportional gain/time constant). The formula for the controller in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and time constant are related as follows I = P/T. +# +# +# +# +# The contribution from the integral term is proportional to both +# the magnitude of the error and the duration of the error. +# The integral in a PID controller is the sum of the instantaneous +# error over time and gives the accumulated offset that should have +# been corrected previously. The accumulated error is then +# multiplied by the integral gain (Ki) and added to the +# controller output. +# +# +# +# +# The derivative of the process error is calculated by determining +# the slope of the error over time and multiplying this rate of +# change by the derivative gain K_d. The magnitude of the +# contribution of the derivative term to the overall control +# action is termed the derivative gain, K_d +# +# +# +# +# The Type switches controller parameters between P/I (proportional gain/integral +# gain) and P/T (proportional gain/time constant). The formula for the controller +# in the frequency domain is G(s) = P + I/s = P(1 + 1/(Ts)). The integral gain and +# time constant are related as follows I = P/T. +# +# +# diff --git a/contributed_definitions/nyaml/NXpolarizer_opt.yaml b/contributed_definitions/nyaml/NXpolarizer_opt.yaml new file mode 100644 index 0000000000..71a1505e66 --- /dev/null +++ b/contributed_definitions/nyaml/NXpolarizer_opt.yaml @@ -0,0 +1,411 @@ +category: base +doc: | + An optical polarizer. + + Information on the properties of polarizer is provided e.g. + [here](https://www.rp-photonics.com/polarizers.html). +symbols: + N_spectrum: | + Size of the wavelength array for which the refractive index of the material + and/or coating is given. + N_spectrum_RT: | + Size of the wavelength array for which the reflectance or transmission of + the polarizer is given. + +# A draft of a new base class to describe an optical polarizer +# (NXpolarizer describes a spin polarizer) +type: group +NXpolarizer_opt(NXobject): + type: + doc: | + Type of the polarizer (e.g. dichroic, linear, circular etc.) + enumeration: [dichroic, linear, circular, Glan-Thompson prism, Nicol prism, Glan-Taylor prism, Glan-Focault prism, Wollaston prism, Normarski prism, Senarmont prism, thin-film polarizer, wire grid polarizer, other] + + # ??? Any other common polarizer types ??? + type_other: + doc: | + If you selected 'other' in type specify what it is. + polarizer_angle(NX_NUMBER): + exists: recommended + unit: NX_ANGLE + doc: | + Angle of the polarizer. + acceptance_angle(NX_NUMBER): + exists: recommended + unit: NX_ANGLE + doc: | + Acceptance angle of the polarizer (range). + dimensions: + rank: 1 + dim: [[1, 2]] + (NXshape): + exists: recommended + doc: | + Describe the geometry (shape, dimension etc.) of the device. + Specify the dimensions in 'SHAPE/size'. A sketch of the device should be + provided in the 'sketch(NXdata)' field to clarify (i) the shape and + dimensions of the device, and (ii) the input and outputs (i.e. the + direction of the incoming and outcoming (split) beams). + + # !!! NOTE: this class is the same as for NXbeam_path !!! + shape: + doc: | + Describe the shape (plate, cube, wedged, prism etc.). + enumeration: [cube, cylinder, plate, prism, wedged, other] + other_shape: + doc: | + If you chose 'other' in 'shape' describe what it is. + sketch(NXdata): + doc: | + Sketch of thedevice showing its geometry. The paths of the + incoming and outgoing beam should be illustrated and labelled (0 for + the incoming beam, and 1, 2,..., N_outputs for the outputs). + size: + doc: | + Physical extent of the device. The device might be made up of one or + more objects (NX_objects). The meaning and location of the axes used + will vary according to the value of the 'shape' variable. 'N_shapepar' + defines how many parameters: + + * For 'cube' the parameters are (width, length). + * For 'cylinder' the parameters are (diameter, length). + * For 'plate' the parameters are (width, height, length). + * For 'prism' the parameters are (width, height, length). + * For 'wedged' the parameters are (width, height, shortest length). + The wedge angle should be provided in 'SHAPE/wedge_angle'. + * For 'other' the parameters may be (A, B, C, ...) with the labels + defined in the sketch plotted in 'SHAPE/sketch'. + dimensions: + rank: 2 + dim: [[1, N_objects], [2, N_shapepar]] + wedge_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Wedge angle if 'shape' is 'wedged'. + wavelength_range(NX_FLOAT): + exists: recommended + unit: NX_WAVELENGTH + doc: | + Wavelength range for which the polarizer is designed. Enter the minimum + and maximum wavelength (lower and upper limit) of the range. + dimensions: + rank: 1 + dim: [[1, 2]] + substrate(NXsample): + doc: | + Properties of the substrate material of the polarizer. If the device has + a coating specify the coating material and its properties in 'coating'. + substrate_material: + doc: | + Specify the substrate material of the polarizer. + substrate_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the polarizer substrate. + index_of_refraction(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the polarizer material. Specify at given + spectral values (wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + COATING(NXsample): + + # Used captial letters for COATING so that more than one can be defined if + # the device has different coatings on the front and back side. + doc: | + If the device has a coating describe the material and its properties. + Some basic information can be found e.g. [here] + (https://www.opto-e.com/basics/reflection-transmission-and-coatings). + If the back and front side of the polarizer are coated with different + materials, you may define two coatings (e.g. COATING1 and COATING2). + coating_type: + doc: | + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + coating_material: + doc: | + Describe the coating material (e.g. MgF2). + coating_thickness(NX_FLOAT): + unit: NX_LENGTH + doc: | + Thickness of the coating. + index_of_refraction_coating(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum_coating]] + extinction_ratio(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Extinction ratio (maximum to minimum transmission). + dimensions: + rank: 1 + dim: [[1, N_spectrum]] + reflection(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Reflection of the polarizer at given wavelength values. + dimensions: + rank: 1 + dim: [[1, N_spectrum_RT]] + transmission(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Transmission of the polarizer at given wavelength values. + dimensions: + rank: 1 + dim: [[1, N_spectrum_RT]] + + # anything missing? + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 10666a419359fcc1d8eddc125ec51a4e8f41584fa36eaffc0c4e01cab6fc3704 +# +# +# +# +# +# +# +# +# Size of the wavelength array for which the refractive index of the material +# and/or coating is given. +# +# +# +# +# Size of the wavelength array for which the reflectance or transmission of +# the polarizer is given. +# +# +# +# +# An optical polarizer. +# +# Information on the properties of polarizer is provided e.g. +# [here](https://www.rp-photonics.com/polarizers.html). +# +# +# +# Type of the polarizer (e.g. dichroic, linear, circular etc.) +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you selected 'other' in type specify what it is. +# +# +# +# +# Angle of the polarizer. +# +# +# +# +# Acceptance angle of the polarizer (range). +# +# +# +# +# +# +# +# Describe the geometry (shape, dimension etc.) of the device. +# Specify the dimensions in 'SHAPE/size'. A sketch of the device should be +# provided in the 'sketch(NXdata)' field to clarify (i) the shape and +# dimensions of the device, and (ii) the input and outputs (i.e. the +# direction of the incoming and outcoming (split) beams). +# +# +# +# +# Describe the shape (plate, cube, wedged, prism etc.). +# +# +# +# +# +# +# +# +# +# +# +# +# If you chose 'other' in 'shape' describe what it is. +# +# +# +# +# Sketch of thedevice showing its geometry. The paths of the +# incoming and outgoing beam should be illustrated and labelled (0 for +# the incoming beam, and 1, 2,..., N_outputs for the outputs). +# +# +# +# +# Physical extent of the device. The device might be made up of one or +# more objects (NX_objects). The meaning and location of the axes used +# will vary according to the value of the 'shape' variable. 'N_shapepar' +# defines how many parameters: +# +# * For 'cube' the parameters are (width, length). +# * For 'cylinder' the parameters are (diameter, length). +# * For 'plate' the parameters are (width, height, length). +# * For 'prism' the parameters are (width, height, length). +# * For 'wedged' the parameters are (width, height, shortest length). +# The wedge angle should be provided in 'SHAPE/wedge_angle'. +# * For 'other' the parameters may be (A, B, C, ...) with the labels +# defined in the sketch plotted in 'SHAPE/sketch'. +# +# +# +# +# +# +# +# +# Wedge angle if 'shape' is 'wedged'. +# +# +# +# +# +# Wavelength range for which the polarizer is designed. Enter the minimum +# and maximum wavelength (lower and upper limit) of the range. +# +# +# +# +# +# +# +# Properties of the substrate material of the polarizer. If the device has +# a coating specify the coating material and its properties in 'coating'. +# +# +# +# Specify the substrate material of the polarizer. +# +# +# +# +# Thickness of the polarizer substrate. +# +# +# +# +# Complex index of refraction of the polarizer material. Specify at given +# spectral values (wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# +# If the device has a coating describe the material and its properties. +# Some basic information can be found e.g. [here] +# (https://www.opto-e.com/basics/reflection-transmission-and-coatings). +# If the back and front side of the polarizer are coated with different +# materials, you may define two coatings (e.g. COATING1 and COATING2). +# +# +# +# Specify the coating type (e.g. dielectric, anti-reflection (AR), +# multilayer coating etc.). +# +# +# +# +# Describe the coating material (e.g. MgF2). +# +# +# +# +# Thickness of the coating. +# +# +# +# +# Complex index of refraction of the coating. Specify at given spectral +# values (wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# Extinction ratio (maximum to minimum transmission). +# +# +# +# +# +# +# +# Reflection of the polarizer at given wavelength values. +# +# +# +# +# +# +# +# Transmission of the polarizer at given wavelength values. +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXpositioner_sts.yaml b/contributed_definitions/nyaml/NXpositioner_sts.yaml new file mode 100644 index 0000000000..5fc0546f75 --- /dev/null +++ b/contributed_definitions/nyaml/NXpositioner_sts.yaml @@ -0,0 +1,552 @@ +category: base +doc: | + A generic positioner such as a motor or piezo-electric transducer. +type: group +NXpositioner_sts(NXobject): + name: + doc: | + symbolic or mnemonic name (one word) + description: + doc: | + description of positioner + value(NX_NUMBER): + unit: NX_ANY + doc: | + best known value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + raw_value(NX_NUMBER): + unit: NX_ANY + doc: | + raw value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + target_value(NX_NUMBER): + unit: NX_ANY + doc: | + targeted (commanded) value of positioner - need [n] as may be scanned + dimensions: + rank: 1 + dim: [[1, n]] + tolerance(NX_NUMBER): + unit: NX_ANY + doc: | + maximum allowable difference between target_value and value + dimensions: + rank: 1 + dim: [[1, n]] + soft_limit_min(NX_NUMBER): + unit: NX_ANY + doc: | + minimum allowed limit to set value + soft_limit_max(NX_NUMBER): + unit: NX_ANY + doc: | + maximum allowed limit to set value + velocity(NX_NUMBER): + unit: NX_ANY + doc: | + velocity of the positioner (distance moved per unit time) + acceleration_time(NX_NUMBER): + unit: NX_ANY + doc: | + time to ramp the velocity up to full speed + controller_record: + doc: | + Hardware device record, e.g. EPICS process variable, taco/tango ... + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a positioner. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + position(NXtransformations): + doc: | + To clarify the frame laboratory frame. The scanning area in x, y, and z position in the + frame. + z_contronller(NX_NUMBER): + doc: | + This controllers task is to continuously adjust the Z position of the stm tip in order + to keep the selected control signal as close as possible to the Set Point. Different control + signals lead to different contronller beahvior. + z_offset(NX_NUMBER): + unit: NX_LENGTH + doc: | + Offset added to the initial averaged position Zaver before starting to swepp. + tip_position_z(NX_NUMBER): + unit: NX_LENGTH + doc: | + Indicate the tip position Z between tip and sample. The tip position can also be varied when + the controller is not running. + controller_name(NX_CHAR): + doc: | + Controller name. This name which will be displayed at places where you can select a + controller. + setpoint(NX_NUMBER): + unit: NX_CURRENT + doc: | + Set Point is the desired value of the control signal. It can be set by editing the number + or using the slider bar. Click the "Set" button above the input field to use the actual + value as Set Point. The slider shows the Set Point as well as the current value. + tip_lift(NX_NUMBER): + unit: NX_LENGTH + doc: | + Lifts the tip by the specified amount when then controller is switched off. This can be + a positive or a negative number, i.e. the tip can also be moved towards the sample. Be + careful with sign and value when using this feature. + switch_off_delay(NX_NUMBER): + unit: NX_TIME + doc: | + Use this parameter for a reproducible position when switching off the Z-controller. + When >0 and the Z-controller is switched off, it doesn't switch off immediately but continues + to run for the specified time and averages the Z position. + z_controller_hold(NX_BOOLEAN): + doc: | + (In bias spectroscopy) Select whether to set the Z-Controller on hold (i.e. disabled) during + the sweep. It is selected by default. When deselected, Z-offset and Z control time parameters + are disabled. + final_z(NX_NUMBER): + unit: NX_LENGTH + doc: | + The final z-position during the bias spectroscopy scan. The availability of values is + related to the mode of scanning. + + # scan_control(NXcollection): + # doc: | + # To control the tip and various scan operations. + scanfield(NX_NUMBER): + unit: NX_LENGTH + doc: | + Configure the scan frame like x position; y position; width; height. + pixels_line(NX_NUMBER): + unit: NX_COUNT + doc: | + Scan resolution by setting the Lines equal to Pixels. + lines(NX_NUMBER): + unit: NX_ANY + doc: | + Define the image resolution. + speed_forw(NX_NUMBER): + unit: NX_ANY + doc: | + Define the scan forward speed in the forward direction. + speed_backw(NX_NUMBER): + unit: NX_ANY + doc: | + Define the scan backward speed in the forward direction. + piezo_calibration: + doc: | + Piezo calibration module is used to define the X Y Z piezos calibration. + active_calib(NX_CHAR): + doc: | + The name of caliberation type. + calib_N(NX_NUMBER): + + # z_contronller(NXcollection): + # name: + # doc: | + # This controllers task is to continuously adjust the Z position of the stm tip in order to keep the selected control signal as close as possible to the Set Point. Different contro; signals lead to different contronller beahvior. + # z_offset(NX_NUMBER): + # doc: Offset added to the initial averaged position Zaver before starting to swepp. + # unit: NX_LENGTH + # tip_position_z(NX_NUMBER): + # doc: Indicate the tip position Z between tip and sample. The tip position can also be varied when the controller is not running. + # unit: NX_LENGTH + # controller_name: + # doc: Controller name. This name which will be displayed at places where you can select a controller. + # setpoint(NX_NUMBER): + # doc: Set Point is the desired value of the control signal. It can be set by editing the number or using the slider bar. Click the "Set" button above the input field to use the actual value as Set Point. The slider shows the Set Point as well as the current value. + # unit: NX_CUTTENT + # setpoint_unit: + # doc: The unit of setpoint during the scanning. + p_gain(NX_NUMBER): + unit: NX_UNITLESS + doc: | + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and :math:`P/T` + (proportional gain/time constant). The formula for the controller in the frequency domain is: + :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. + The integral gain and time constant are related as follows: :math:`I = P/T`. + i_gain(NX_NUMBER): + unit: NX_UNITLESS + doc: | + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and + P/T (proportional gain/time constant). The formula for the controller in the frequency + domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related + as follows: `:math:I = P/T`. + time_const(NX_NUMBER): + unit: NX_TIME + doc: | + The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and + :math:`P/T` (proportional gain/time constant). The formula for the controller in the frequency + domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related + as follows: :math:`I = P/T`. + + # tip_lift(NX_NUMBER): + # doc: | + # Lifts the tip by the specified amount when then controller is switched off. This + # can be a positive or a negative number, i.e. the tip can also be moved towards the sample. + # Be careful with sign and value when using this feature. + # unit: NX_LENGTH + # switch_off_delay(NX_NUMBER): + # doc: | + # Use this parameter for a reproducible position when switching off the Z-controller. + # When >0 and the Z-controller is switched off, it doesn't switch off immediately but + # continues to run for the specified time and averages the Z position. + # unit: NX_TIME + # z_controller_hold(NX_CHAR): + # doc: | + # (In biase spectroscopy) Select whether to set the Z-Controller on hold (i.e. disabled) + # during the sweep. It is selected by default. When deselected, Z-offset and Z control time + # parameters are disabled. + scan_contronller(NX_NUMBER): + doc: | + There are 2 parameters in X and Y directions. If you know them, you can enter the 2nd order + piezo characteristics to compensate for it. The following equation shows the interpretation + of the 2nd order correction parameter: For the X-piezo: + :math:`Ux = 1/cx · X + cxx · X2`; with units: :math:`[V] = [V/m] · [m] + [V/m2] · [m2]` + where cx is the calibration of the piezo X and cxx is the 2nd order correction. :math:`(V/m^2)` + drift(NX_NUMBER): + unit: NX_ANY + doc: | + There are 2 parameters in X and Y directions. Define the drift speed for all three axes. + When the compensation is on, the piezos will start to move at that speed. + drift_correction_status(NX_CHAR): + doc: | + Use the button to turn on/off the drift compensation. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 83beb3d0c95691e16420919cb753190e06479f7298b3d660ea515fc999f6dd53 +# +# +# +# +# +# A generic positioner such as a motor or piezo-electric transducer. +# +# +# +# symbolic or mnemonic name (one word) +# +# +# +# +# description of positioner +# +# +# +# +# best known value of positioner - need [n] as may be scanned +# +# +# +# +# +# +# +# raw value of positioner - need [n] as may be scanned +# +# +# +# +# +# +# +# targeted (commanded) value of positioner - need [n] as may be scanned +# +# +# +# +# +# +# +# maximum allowable difference between target_value and value +# +# +# +# +# +# +# +# minimum allowed limit to set value +# +# +# +# +# maximum allowed limit to set value +# +# +# +# +# velocity of the positioner (distance moved per unit time) +# +# +# +# +# time to ramp the velocity up to full speed +# +# +# +# +# Hardware device record, e.g. EPICS process variable, taco/tango ... +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a positioner. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# To clarify the frame laboratory frame. The scanning area in x, y, and z position in the +# frame. +# +# +# +# +# This controllers task is to continuously adjust the Z position of the stm tip in order +# to keep the selected control signal as close as possible to the Set Point. Different control +# signals lead to different contronller beahvior. +# +# +# +# +# Offset added to the initial averaged position Zaver before starting to swepp. +# +# +# +# +# Indicate the tip position Z between tip and sample. The tip position can also be varied when +# the controller is not running. +# +# +# +# +# Controller name. This name which will be displayed at places where you can select a +# controller. +# +# +# +# +# Set Point is the desired value of the control signal. It can be set by editing the number +# or using the slider bar. Click the "Set" button above the input field to use the actual +# value as Set Point. The slider shows the Set Point as well as the current value. +# +# +# +# +# Lifts the tip by the specified amount when then controller is switched off. This can be +# a positive or a negative number, i.e. the tip can also be moved towards the sample. Be +# careful with sign and value when using this feature. +# +# +# +# +# Use this parameter for a reproducible position when switching off the Z-controller. +# When >0 and the Z-controller is switched off, it doesn't switch off immediately but continues +# to run for the specified time and averages the Z position. +# +# +# +# +# (In bias spectroscopy) Select whether to set the Z-Controller on hold (i.e. disabled) during +# the sweep. It is selected by default. When deselected, Z-offset and Z control time parameters +# are disabled. +# +# +# +# +# The final z-position during the bias spectroscopy scan. The availability of values is +# related to the mode of scanning. +# +# +# +# +# +# Configure the scan frame like x position; y position; width; height. +# +# +# +# +# Scan resolution by setting the Lines equal to Pixels. +# +# +# +# +# Define the image resolution. +# +# +# +# +# Define the scan forward speed in the forward direction. +# +# +# +# +# Define the scan backward speed in the forward direction. +# +# +# +# +# Piezo calibration module is used to define the X Y Z piezos calibration. +# +# +# +# +# The name of caliberation type. +# +# +# +# +# +# +# The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and :math:`P/T` +# (proportional gain/time constant). The formula for the controller in the frequency domain is: +# :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. +# The integral gain and time constant are related as follows: :math:`I = P/T`. +# +# +# +# +# The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and +# P/T (proportional gain/time constant). The formula for the controller in the frequency +# domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related +# as follows: `:math:I = P/T`. +# +# +# +# +# The Type switches controller parameters between :math:`P/I` (proportional gain/integral gain) and +# :math:`P/T` (proportional gain/time constant). The formula for the controller in the frequency +# domain is: :math:`G(s) = P + I/s = P(1 + 1/(Ts))`. The integral gain and time constant are related +# as follows: :math:`I = P/T`. +# +# +# +# +# +# There are 2 parameters in X and Y directions. If you know them, you can enter the 2nd order +# piezo characteristics to compensate for it. The following equation shows the interpretation +# of the 2nd order correction parameter: For the X-piezo: +# :math:`Ux = 1/cx · X + cxx · X2`; with units: :math:`[V] = [V/m] · [m] + [V/m2] · [m2]` +# where cx is the calibration of the piezo X and cxx is the 2nd order correction. :math:`(V/m^2)` +# +# +# +# +# There are 2 parameters in X and Y directions. Define the drift speed for all three axes. +# When the compensation is on, the piezos will start to move at that speed. +# +# +# +# +# Use the button to turn on/off the drift compensation. +# +# +# diff --git a/contributed_definitions/nyaml/NXprocess_mpes.yaml b/contributed_definitions/nyaml/NXprocess_mpes.yaml new file mode 100644 index 0000000000..bf1833a521 --- /dev/null +++ b/contributed_definitions/nyaml/NXprocess_mpes.yaml @@ -0,0 +1,266 @@ +category: base +doc: | + :ref:`NXprocess_mpes` describes events of data processing, reconstruction, + or analysis for MPES-related data. + + It extends the NXprocess class and provides a glossary of explicitly named processes + and their metadata which are typical for MPES data. +type: group +NXprocess_mpes(NXprocess): + energy_calibration(NXcalibration): + doc: | + Calibration event on the energy axis. + + For XPS, the calibration should ideally be performed according to + `ISO 15472:2010`_ specification. + + .. _ISO 15472:2010: https://www.iso.org/standard/74811.html + calibrated_axis(NX_FLOAT): + doc: | + This is the calibrated energy axis to be used for data plotting. + angular_calibration(NXcalibration): + calibrated_axis(NX_FLOAT): + doc: | + This is the calibrated angular axis to be used for data plotting. + spatial_calibration(NXcalibration): + calibrated_axis(NX_FLOAT): + doc: | + This is the calibrated spatial axis to be used for data plotting. + momentum_calibration(NXcalibration): + exists: optional + calibrated_axis(NX_FLOAT): + doc: | + This is the momentum axis to be used for data plotting. + energy_referencing(NXcalibration): + doc: + - | + For energy referencing, the measured energies are corrected for the charging potential + (i.e., the electrical potential of the surface region of an insulating sample, caused by + irradiation) such that those energies correspond to a sample with no surface charge. + Usually, the energy axis is adjusted by shifting all energies uniformally until one + well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.74 ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 + level(NXelectron_level): + doc: | + Electronic core or valence level that was used for the calibration. + reference_peak: + doc: | + Reference peak that was used for the calibration. + + For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level + binding_energy(NX_FLOAT): + doc: + - | + The binding energy (in units of eV) that the specified emission line appeared at, + after adjusting the binding energy scale. + - | + xref: + spec: ISO 18115-1:2023 + term: 12.16_ ff. + url: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 + offset(NX_FLOAT): + doc: | + Offset between measured binding energy and calibrated binding energy of the + emission line. + calibrated_axis(NX_FLOAT): + doc: | + This is the calibrated energy axis to be used for data plotting. + + This should link to /entry/data/energy. + transmission_correction(NXcalibration): + doc: | + In the transmission correction, each intensity measurement for electrons of a given + kinetic energy is multiplied by the corresponding value in the relative_intensity + field of the transmission_function. This calibration procedure is used to account for + the different tranmsission efficiencies when using different lens modes. + transmission_function(NXdata): + doc: | + Transmission function of the electron analyser. + + The transmission function (TF) specifies the detection efficiency for electrons of + different kinetic energy passing through the electron analyser. + This can be a link to /entry/instrument/electronanalyser/transmission_function. + \@signal: + enumeration: [relative_intensity] + \@axes: + enumeration: [kinetic_energy] + kinetic_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Kinetic energy values + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + relative_intensity(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Relative transmission efficiency for the given kinetic energies + dimensions: + rank: 1 + dim: [[1, n_transmission_function]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8c2be91055cba41fd23b23cc1ec13a132da3afa32a9fb666f8242e34c864aa68 +# +# +# +# +# +# :ref:`NXprocess_mpes` describes events of data processing, reconstruction, +# or analysis for MPES-related data. +# +# It extends the NXprocess class and provides a glossary of explicitly named processes +# and their metadata which are typical for MPES data. +# +# +# +# Calibration event on the energy axis. +# +# For XPS, the calibration should ideally be performed according to +# `ISO 15472:2010`_ specification. +# +# .. _ISO 15472:2010: https://www.iso.org/standard/74811.html +# +# +# +# This is the calibrated energy axis to be used for data plotting. +# +# +# +# +# +# +# This is the calibrated angular axis to be used for data plotting. +# +# +# +# +# +# +# This is the calibrated spatial axis to be used for data plotting. +# +# +# +# +# +# +# This is the momentum axis to be used for data plotting. +# +# +# +# +# +# For energy referencing, the measured energies are corrected for the charging potential +# (i.e., the electrical potential of the surface region of an insulating sample, caused by +# irradiation) such that those energies correspond to a sample with no surface charge. +# Usually, the energy axis is adjusted by shifting all energies uniformally until one +# well-defined emission line peak (or the Fermi edge) is located at a known _correct_ energy. +# +# This concept is related to term `12.74 ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _12.74 ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.74 +# +# +# +# Electronic core or valence level that was used for the calibration. +# +# +# +# +# Reference peak that was used for the calibration. +# +# For example: adventitious carbon | C-C | metallic Au | elemental Si | Fermi edge | vacuum level +# +# +# +# +# The binding energy (in units of eV) that the specified emission line appeared at, +# after adjusting the binding energy scale. +# +# This concept is related to term `12.16_ ff.`_ of the ISO 18115-1:2023 standard. +# +# .. _12.16_ ff.: https://www.iso.org/obp/ui/en/#iso:std:iso:18115:-1:ed-3:v1:en:term:12.16 +# +# +# +# +# Offset between measured binding energy and calibrated binding energy of the +# emission line. +# +# +# +# +# This is the calibrated energy axis to be used for data plotting. +# +# This should link to /entry/data/energy. +# +# +# +# +# +# In the transmission correction, each intensity measurement for electrons of a given +# kinetic energy is multiplied by the corresponding value in the relative_intensity +# field of the transmission_function. This calibration procedure is used to account for +# the different tranmsission efficiencies when using different lens modes. +# +# +# +# Transmission function of the electron analyser. +# +# The transmission function (TF) specifies the detection efficiency for electrons of +# different kinetic energy passing through the electron analyser. +# This can be a link to /entry/instrument/electronanalyser/transmission_function. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Kinetic energy values +# +# +# +# +# +# +# +# Relative transmission efficiency for the given kinetic energies +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXprogram.yaml b/contributed_definitions/nyaml/NXprogram.yaml new file mode 100644 index 0000000000..a0dd2567bd --- /dev/null +++ b/contributed_definitions/nyaml/NXprogram.yaml @@ -0,0 +1,76 @@ +category: base +doc: | + Base class to describe a software tool or library. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXprogram(NXobject): + program: + doc: | + Given name of the program. Program can be a commercial one a script, + or a library or a library component. + \@version: + doc: | + Program version plus build number, or commit hash. + \@url: + doc: | + Description of an ideally ever persistent resource where the source code + of the program or this specific compiled version of the program can be + found so that the program yields repeatably exactly the same numerical + and categorical results. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e508f9d472f579d40e1573a0b3cdde6c70892cc9579735c5e3121cdf075554f8 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Base class to describe a software tool or library. +# +# +# +# Given name of the program. Program can be a commercial one a script, +# or a library or a library component. +# +# +# +# Program version plus build number, or commit hash. +# +# +# +# +# Description of an ideally ever persistent resource where the source code +# of the program or this specific compiled version of the program can be +# found so that the program yields repeatably exactly the same numerical +# and categorical results. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXpulser_apm.yaml b/contributed_definitions/nyaml/NXpulser_apm.yaml new file mode 100644 index 0000000000..0660ad266b --- /dev/null +++ b/contributed_definitions/nyaml/NXpulser_apm.yaml @@ -0,0 +1,281 @@ +category: base +doc: | + Metadata for laser- and/or voltage-pulsing in atom probe microscopy. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ions: | + Total number of ions collected. +type: group +NXpulser_apm(NXobject): + (NXfabrication): + pulse_mode: + doc: | + How is field evaporation physically triggered. + enumeration: [laser, voltage, laser_and_voltage] + pulse_frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Frequency with which the high voltage or laser pulser fires. + + # This can change over the course of the experiment, APT HDF defines it therefore as follows: "PulseFrequency : Real array, 2xn (Hz) This is the frequency of the high voltage or laser pulser. first entry : first pulse number where the spacing between this and all subsequent pulses are considered to be at the selected frequency. Each first entry must be strictly increasing in value. The second entry contains the frequency value" as data can be compressed in this case very efficiently we go for with an array of length 1xn_ions + dimensions: + rank: 1 + dim: [[1, n_ions]] + pulse_fraction(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Fraction of the pulse_voltage that is applied in addition + to the standing_voltage at peak voltage of a pulse. + + If a standing voltage is applied, this gives nominal pulse fraction + (as a function of standing voltage). Otherwise this field should not be + present. + dimensions: + rank: 1 + dim: [[1, n_ions]] + pulsed_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + In laser pulsing mode the values will be zero so the this field is recommended. + However, for voltage pulsing mode it is highly recommended that users report the pulsed_voltage. + dimensions: + rank: 1 + dim: [[1, n_ions]] + pulse_number(NX_UINT): + unit: NX_UNITLESS + doc: | + Absolute number of pulses starting from the beginning of the experiment. + dimensions: + rank: 1 + dim: [[1, n_ions]] + standing_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Direct current voltage between the specimen and the (local electrode) in + the case of local electrode atom probe (LEAP) instrument. + The standing voltage applied to the sample, relative to system ground. + dimensions: + rank: 1 + dim: [[1, n_ions]] + (NXsource): + doc: | + Atom probe microscopes use controlled laser, voltage, + or a combination of pulsing strategies to trigger the + excitation and eventual field evaporation/emission of + an ion during an experiment. + name: + doc: | + Given name/alias. + (NXfabrication): + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Nominal wavelength of the laser radiation. + power(NX_FLOAT): + unit: NX_POWER + doc: | + Nominal power of the laser source while illuminating the specimen. + + # NEW ISSUE: needs clearer specification/definition + pulse_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Average energy of the laser at peak of each pulse. + (NXbeam): + doc: | + Details about specific positions along the focused laser beam + which illuminates the (atom probe) specimen. + incidence_vector(NXcollection): + doc: | + Track time-dependent settings over the course of the + measurement how the laser beam in tip space/reconstruction space + laser impinges on the sample, i.e. the mean vector is parallel to + the laser propagation direction. + pinhole_position(NXcollection): + doc: | + Track time-dependent settings over the course of the + measurement where the laser beam exits the + focusing optics. + spot_position(NXcollection): + doc: | + Track time-dependent settings over the course of the + measurement where the laser hits the specimen. + (NXtransformations): + doc: | + Affine transformations which describe the geometry how the + laser focusing optics/pinhole-attached coordinate system is + defined, how it has to be transformed so that it aligns with + the specimen coordinate system. + A right-handed Cartesian coordinate system, the so-called laser space, + should be assumed, whose positive z-axis points + into the direction of the propagating laser beam. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 84fa67d6c1df34589f01c80d3eb014e43f7ba7a6cdfab06afba597d89f3e8377 +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Total number of ions collected. +# +# +# +# +# Metadata for laser- and/or voltage-pulsing in atom probe microscopy. +# +# +# +# +# How is field evaporation physically triggered. +# +# +# +# +# +# +# +# +# +# Frequency with which the high voltage or laser pulser fires. +# +# +# +# +# +# +# +# +# Fraction of the pulse_voltage that is applied in addition +# to the standing_voltage at peak voltage of a pulse. +# +# If a standing voltage is applied, this gives nominal pulse fraction +# (as a function of standing voltage). Otherwise this field should not be +# present. +# +# +# +# +# +# +# +# In laser pulsing mode the values will be zero so the this field is recommended. +# However, for voltage pulsing mode it is highly recommended that users report the pulsed_voltage. +# +# +# +# +# +# +# +# Absolute number of pulses starting from the beginning of the experiment. +# +# +# +# +# +# +# +# Direct current voltage between the specimen and the (local electrode) in +# the case of local electrode atom probe (LEAP) instrument. +# The standing voltage applied to the sample, relative to system ground. +# +# +# +# +# +# +# +# Atom probe microscopes use controlled laser, voltage, +# or a combination of pulsing strategies to trigger the +# excitation and eventual field evaporation/emission of +# an ion during an experiment. +# +# +# +# Given name/alias. +# +# +# +# +# +# Nominal wavelength of the laser radiation. +# +# +# +# +# Nominal power of the laser source while illuminating the specimen. +# +# +# +# +# +# Average energy of the laser at peak of each pulse. +# +# +# +# +# Details about specific positions along the focused laser beam +# which illuminates the (atom probe) specimen. +# +# +# +# Track time-dependent settings over the course of the +# measurement how the laser beam in tip space/reconstruction space +# laser impinges on the sample, i.e. the mean vector is parallel to +# the laser propagation direction. +# +# +# +# +# Track time-dependent settings over the course of the +# measurement where the laser beam exits the +# focusing optics. +# +# +# +# +# Track time-dependent settings over the course of the +# measurement where the laser hits the specimen. +# +# +# +# +# +# Affine transformations which describe the geometry how the +# laser focusing optics/pinhole-attached coordinate system is +# defined, how it has to be transformed so that it aligns with +# the specimen coordinate system. +# A right-handed Cartesian coordinate system, the so-called laser space, +# should be assumed, whose positive z-axis points +# into the direction of the propagating laser beam. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXpump.yaml b/contributed_definitions/nyaml/NXpump.yaml new file mode 100644 index 0000000000..a5a803a64d --- /dev/null +++ b/contributed_definitions/nyaml/NXpump.yaml @@ -0,0 +1,14 @@ +category: base +doc: | + Device to reduce an atmosphere (real or simulated) to a controlled pressure. +type: group +NXpump(NXobject): + (NXfabrication): + design(NX_CHAR): + doc: | + Principle type of the pump. + enumeration: [membrane, rotary_vane, roots, turbo_molecular] + + # NEW ISSUE: take community input and work further to store what is relevant to report about pumps + # NEW ISSUE: see e.g. https://www.youtube.com/watch?v=Nsr_AdTiIIA for a discussion about + # NEW ISSUE: the role, pros and cons of pump used for atom probe microscopy diff --git a/contributed_definitions/nyaml/NXquadric.yaml b/contributed_definitions/nyaml/NXquadric.yaml new file mode 100644 index 0000000000..f220b55003 --- /dev/null +++ b/contributed_definitions/nyaml/NXquadric.yaml @@ -0,0 +1,117 @@ +category: base +doc: | + definition of a quadric surface. +type: group +NXquadric(NXobject): + parameters(NX_NUMBER): + unit: NX_PER_LENGTH + doc: | + Ten real values of the matrix that defines the quadric surface + in projective space. Ordered Q11, Q12, Q13, Q22, Q23, Q33, P1, + P2, P3, R. Takes a units attribute of dimension reciprocal + length. R is scalar. P has dimension reciprocal length, and the + given units. Q has dimension reciprocal length squared, and + units the square of those given. + dimensions: + dim: [[1, 10]] + surface_type: + exists: ['min', '0', 'max', '1'] + doc: | + An optional description of the form of the quadric surface: + enumeration: [ELLIPSOID, ELLIPTIC_PARABOLOID, HYPERBOLIC_PARABOLOID, ELLIPTIC_HYPERBOLOID_OF_1_SHEET, ELLIPTIC_HYPERBOLOID_OF_2_SHEETS, ELLIPTIC_CONE, ELLIPTIC_CYLINDER, HYPERBOLIC_CYLINDER, PARABOLIC_CYLINDER, SPHEROID, SPHERE, PARABOLOID, HYPERBOLOID_1_SHEET, HYPERBOLOID_2_SHEET, CONE, CYLINDER, PLANE, IMAGINARY, UNKNOWN] + depends_on(NX_CHAR): + exists: ['min', '0', 'max', '1'] + doc: | + Path to an :ref:`NXtransformations` that defining the axis on + which the orientation of the surface depends. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 267b94fd8c62dec6dbb2c835d40cda184ec544f98b054c545c067c0206a6680f +# +# +# +# +# definition of a quadric surface. +# +# +# Ten real values of the matrix that defines the quadric surface +# in projective space. Ordered Q11, Q12, Q13, Q22, Q23, Q33, P1, +# P2, P3, R. Takes a units attribute of dimension reciprocal +# length. R is scalar. P has dimension reciprocal length, and the +# given units. Q has dimension reciprocal length squared, and +# units the square of those given. +# +# +# +# +# +# +# +# An optional description of the form of the quadric surface: +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Path to an :ref:`NXtransformations` that defining the axis on +# which the orientation of the surface depends. +# +# +# diff --git a/contributed_definitions/nyaml/NXquadrupole_magnet.yaml b/contributed_definitions/nyaml/NXquadrupole_magnet.yaml new file mode 100644 index 0000000000..62bec22844 --- /dev/null +++ b/contributed_definitions/nyaml/NXquadrupole_magnet.yaml @@ -0,0 +1,84 @@ +category: base +doc: | + definition for a quadrupole magnet. +type: group +NXquadrupole_magnet(NXobject): + description(NX_CHAR): + doc: | + extended description of the magnet. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + set_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on supply. + read_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from supply. + value: + unit: NX_CURRENT + read_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 87dac0535ae7038f0b632b817a8a67683a20a6257cea6283e449a7b8bd0f3587 +# +# +# +# +# definition for a quadrupole magnet. +# +# extended description of the magnet. +# +# +# define position of beamline element relative to production target +# +# +# current set on supply. +# +# +# current read from supply. +# +# +# +# voltage read from supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXreflectron.yaml b/contributed_definitions/nyaml/NXreflectron.yaml new file mode 100644 index 0000000000..85174758ce --- /dev/null +++ b/contributed_definitions/nyaml/NXreflectron.yaml @@ -0,0 +1,87 @@ +category: base +doc: | + Device for reducing flight time differences of ions in ToF experiments. + For atom probe the reflectron can be considered an energy_compensation + device, which can e.g. be realized technically as via a Poschenrieder lens + (see US patent 3863068 or US patents for the reflectron 6740872, or the curved reflectron 8134119 design). +type: group +NXreflectron(NXobject): + name: + doc: | + Given name/alias. + (NXfabrication): + description: + doc: | + Free-text field to specify further details about the reflectron. + The field can be used to inform e. g. if the reflectron is flat or curved. + + # IFES_APT_TC "ReflectronVoltage: Real, 1xn array (V) Must be present if ReflectronInfo is not “None” The maximum voltage applied to the reflectron, relative to system ground." + (NXtransformations): + doc: | + Affine transformation(s) which detail where the reflectron + is located relative to e.g. the origin of the specimen space + reference coordinate system. + This group can also be used for specifying how the reflectron + is rotated relative to the specimen axis. + The purpose of these more detailed instrument descriptions + is to support the creation of a digital twin of the instrument + for computational science. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 6f932a14554bc463bc83d9d2da179443e89636ee2de15fce04bcf8c8950669ee +# +# +# +# +# +# Device for reducing flight time differences of ions in ToF experiments. +# For atom probe the reflectron can be considered an energy_compensation +# device, which can e.g. be realized technically as via a Poschenrieder lens +# (see US patent 3863068 or US patents for the reflectron 6740872, or the curved reflectron 8134119 design). +# +# +# +# Given name/alias. +# +# +# +# +# +# Free-text field to specify further details about the reflectron. +# The field can be used to inform e. g. if the reflectron is flat or curved. +# +# +# +# +# +# Affine transformation(s) which detail where the reflectron +# is located relative to e.g. the origin of the specimen space +# reference coordinate system. +# This group can also be used for specifying how the reflectron +# is rotated relative to the specimen axis. +# The purpose of these more detailed instrument descriptions +# is to support the creation of a digital twin of the instrument +# for computational science. +# +# +# diff --git a/contributed_definitions/nyaml/NXregion.yaml b/contributed_definitions/nyaml/NXregion.yaml new file mode 100644 index 0000000000..b074a5f157 --- /dev/null +++ b/contributed_definitions/nyaml/NXregion.yaml @@ -0,0 +1,340 @@ +category: base +doc: | + Geometry and logical description of a region of data in a parent group. When used, it could be a child group to, say, :ref:`NXdetector`. + + This can be used to describe a subset of data used to create downsampled data or to derive + some data from that subset. + + Note, the fields for the rectangular region specifiers follow HDF5’s dataspace hyperslab parameters + (see https://portal.hdfgroup.org/display/HDF5/H5S_SELECT_HYPERSLAB). Note when **block** :math:`= 1`, + then **stride** :math:`\equiv` **step** in Python slicing. + + For example, a ROI sum of an area starting at index of [20,50] and shape [220,120] in image data:: + + detector:NXdetector/ + data[60,256,512] + region:NXregion/ + @region_type = "rectangular" + parent = "data" + start = [20,50] + count = [220,120] + statistics:NXdata/ + @signal = "sum" + sum[60] + + the ``sum`` dataset contains the summed areas in each frame. + Another example, a hyperspectral image downsampled 16-fold in energy:: + + detector:NXdetector/ + data[128,128,4096] + region:NXregion/ + @region_type = "rectangular" + parent = "data" + start = [2] + count = [20] + stride = [32] + block = [16] + downsampled:NXdata/ + @signal = "maximum" + @auxiliary_signals = "copy" + maximum[128,128,20] + copy[128,128,320] + + the ``copy`` dataset selects 20 16-channel blocks that start 32 channels apart, + the ``maximum`` dataset will show maximum values in each 16-channel block + in every spectra. +symbols: + doc: | + These symbols will denote how the shape of the parent group's data field, + + .. math:: (D_0, ..., D_{\mathbf{O}-1}, d_0, ..., d_{\mathbf{R}-1}) + + could be split into a left set of **O** outer dimensions, :math:`\boldsymbol{D}`, + and a right set of **R** region dimensions, :math:`\boldsymbol{d}`, + where the data field has rank **O** + **R**. Note **O** :math:`>= 0`. + O: | + Outer rank + R: | + Region rank +type: group +NXregion(NXobject): + \@region_type: + exists: optional + doc: | + This is ``rectangular`` to describe the region as a hyper-rectangle in + the index space of its parent group's data field. + enumeration: [rectangular] + parent: + doc: | + The name of data field in the parent group or the path of a data field relative + to the parent group (so it could be a field in a subgroup of the parent group) + parent_mask: + doc: | + The name of an optional mask field in the parent group with rank :math:`\boldsymbol{R}` and + dimensions :math:`\boldsymbol{d}`. For example, this could be ``pixel_mask`` of an + :ref:`NXdetector`. + start(NX_NUMBER): + exists: recommended + doc: | + The starting position for region in detector data field array. + This is recommended as it also defines the region rank. + If omitted then defined as an array of zeros. + dimensions: + rank: 1 + dim: [[1, R]] + count(NX_INT): + exists: recommended + doc: | + The number of blocks or items in the hyperslab selection. + If omitted then defined as an array of dimensions that take into account + the other hyperslab selection fields to span the parent data field's shape. + dimensions: + rank: 1 + dim: [[1, R]] + stride(NX_INT): + doc: | + An optional field to define striding used to downsample data. + If omitted then defined as an array of ones. + dimensions: + rank: 1 + dim: [[1, R]] + block(NX_INT): + doc: | + An optional field to define the block size used to copy or downsample data. In the + :math:`i`-th dimension, if :math:`\mathbf{block}[i] < \mathbf{stride}[i]` + then the downsampling blocks have gaps between them; when ``block`` matches ``stride`` + then the blocks are contiguous; otherwise the blocks overlap. + If omitted then defined as an array of ones. + dimensions: + rank: 1 + dim: [[1, R]] + scale(NX_NUMBER): + doc: | + An optional field to define a divisor for scaling of reduced data. For example, in a + downsampled sum, it can reduce the maximum values to fit in the domain of the result + data type. In an image that is downsampled by summing 2x2 blocks, using + :math:`\mathrm{scale}=4` allows the result to fit in the same integer type dataset as + the parent dataset. + If omitted then no scaling occurs. + dimensions: + rank: 1 + dim: [[1, R]] + downsampled(NXdata): + doc: | + An optional group containing data copied/downsampled from parent group’s data. Its dataset name + must reflect how the downsampling is done over each block. So it could be a reduction operation + such as sum, minimum, maximum, mean, mode, median, etc. If downsampling is merely copying each + block then use "copy" as the name. Where more than one downsample dataset is written + (specified with ``@signal``) then add ``@auxiliary_signals`` listing the others. In the copy case, + the field should have a shape of :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{block}[0] * \mathbf{count}[0], ..., \mathbf{block}[\mathbf{R}-1] * \mathbf{count}[\mathbf{R}-1])`, + otherwise the expected shape is :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{count}[0], ..., \mathbf{count}[\mathbf{R}-1])`. + + The following figure shows how blocks are used in downsampling: + + .. figure:: region/NXregion-example.png + :width: 60% + + A selection with :math:`\mathbf{start}=2, \mathbf{count}=4, \mathbf{stride}=3, \mathbf{block}=2` from + a dataset with shape [13] will result in the ``reduce`` dataset of shape [4] and a ``copy`` dataset of shape [8]. + statistics(NXdata): + doc: | + An optional group containing any statistics derived from the region in parent group’s data + such as sum, minimum, maximum, mean, mode, median, rms, variance, etc. Where more than one + statistical dataset is written (specified with ``@signal``) then add ``@auxiliary_signals`` + listing the others. All data fields should have shapes of :math:`\boldsymbol{D}`. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8426e78db8c7bfc828d27cea0e29c7cc255b78f1ca7e809672cb6b0174497dd0 +# +# +# +# +# +# +# These symbols will denote how the shape of the parent group's data field, +# +# .. math:: (D_0, ..., D_{\mathbf{O}-1}, d_0, ..., d_{\mathbf{R}-1}) +# +# could be split into a left set of **O** outer dimensions, :math:`\boldsymbol{D}`, +# and a right set of **R** region dimensions, :math:`\boldsymbol{d}`, +# where the data field has rank **O** + **R**. Note **O** :math:`>= 0`. +# +# Outer rank +# Region rank +# +# +# Geometry and logical description of a region of data in a parent group. When used, it could be a child group to, say, :ref:`NXdetector`. +# +# This can be used to describe a subset of data used to create downsampled data or to derive +# some data from that subset. +# +# Note, the fields for the rectangular region specifiers follow HDF5’s dataspace hyperslab parameters +# (see https://portal.hdfgroup.org/display/HDF5/H5S_SELECT_HYPERSLAB). Note when **block** :math:`= 1`, +# then **stride** :math:`\equiv` **step** in Python slicing. +# +# For example, a ROI sum of an area starting at index of [20,50] and shape [220,120] in image data:: +# +# detector:NXdetector/ +# data[60,256,512] +# region:NXregion/ +# @region_type = "rectangular" +# parent = "data" +# start = [20,50] +# count = [220,120] +# statistics:NXdata/ +# @signal = "sum" +# sum[60] +# +# the ``sum`` dataset contains the summed areas in each frame. +# Another example, a hyperspectral image downsampled 16-fold in energy:: +# +# detector:NXdetector/ +# data[128,128,4096] +# region:NXregion/ +# @region_type = "rectangular" +# parent = "data" +# start = [2] +# count = [20] +# stride = [32] +# block = [16] +# downsampled:NXdata/ +# @signal = "maximum" +# @auxiliary_signals = "copy" +# maximum[128,128,20] +# copy[128,128,320] +# +# the ``copy`` dataset selects 20 16-channel blocks that start 32 channels apart, +# the ``maximum`` dataset will show maximum values in each 16-channel block +# in every spectra. +# +# +# +# This is ``rectangular`` to describe the region as a hyper-rectangle in +# the index space of its parent group's data field. +# +# +# +# +# +# +# +# The name of data field in the parent group or the path of a data field relative +# to the parent group (so it could be a field in a subgroup of the parent group) +# +# +# +# +# The name of an optional mask field in the parent group with rank :math:`\boldsymbol{R}` and +# dimensions :math:`\boldsymbol{d}`. For example, this could be ``pixel_mask`` of an +# :ref:`NXdetector`. +# +# +# +# +# The starting position for region in detector data field array. +# This is recommended as it also defines the region rank. +# If omitted then defined as an array of zeros. +# +# +# +# +# +# +# +# The number of blocks or items in the hyperslab selection. +# If omitted then defined as an array of dimensions that take into account +# the other hyperslab selection fields to span the parent data field's shape. +# +# +# +# +# +# +# +# An optional field to define striding used to downsample data. +# If omitted then defined as an array of ones. +# +# +# +# +# +# +# +# An optional field to define the block size used to copy or downsample data. In the +# :math:`i`-th dimension, if :math:`\mathbf{block}[i] < \mathbf{stride}[i]` +# then the downsampling blocks have gaps between them; when ``block`` matches ``stride`` +# then the blocks are contiguous; otherwise the blocks overlap. +# If omitted then defined as an array of ones. +# +# +# +# +# +# +# +# An optional field to define a divisor for scaling of reduced data. For example, in a +# downsampled sum, it can reduce the maximum values to fit in the domain of the result +# data type. In an image that is downsampled by summing 2x2 blocks, using +# :math:`\mathrm{scale}=4` allows the result to fit in the same integer type dataset as +# the parent dataset. +# If omitted then no scaling occurs. +# +# +# +# +# +# +# +# An optional group containing data copied/downsampled from parent group’s data. Its dataset name +# must reflect how the downsampling is done over each block. So it could be a reduction operation +# such as sum, minimum, maximum, mean, mode, median, etc. If downsampling is merely copying each +# block then use "copy" as the name. Where more than one downsample dataset is written +# (specified with ``@signal``) then add ``@auxiliary_signals`` listing the others. In the copy case, +# the field should have a shape of :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{block}[0] * \mathbf{count}[0], ..., \mathbf{block}[\mathbf{R}-1] * \mathbf{count}[\mathbf{R}-1])`, +# otherwise the expected shape is :math:`(D_0, ..., D_{\mathbf{O}-1}, \mathbf{count}[0], ..., \mathbf{count}[\mathbf{R}-1])`. +# +# The following figure shows how blocks are used in downsampling: +# +# .. figure:: region/NXregion-example.png +# :width: 60% +# +# A selection with :math:`\mathbf{start}=2, \mathbf{count}=4, \mathbf{stride}=3, \mathbf{block}=2` from +# a dataset with shape [13] will result in the ``reduce`` dataset of shape [4] and a ``copy`` dataset of shape [8]. +# +# +# +# +# +# An optional group containing any statistics derived from the region in parent group’s data +# such as sum, minimum, maximum, mean, mode, median, rms, variance, etc. Where more than one +# statistical dataset is written (specified with ``@signal``) then add ``@auxiliary_signals`` +# listing the others. All data fields should have shapes of :math:`\boldsymbol{D}`. +# +# +# diff --git a/contributed_definitions/nyaml/NXregistration.yaml b/contributed_definitions/nyaml/NXregistration.yaml new file mode 100644 index 0000000000..a2c1e12cc5 --- /dev/null +++ b/contributed_definitions/nyaml/NXregistration.yaml @@ -0,0 +1,80 @@ +category: base +doc: | + Describes image registration procedures. +type: group +NXregistration(NXobject): + applied(NX_BOOLEAN): + doc: | + Has the registration been applied? + last_process(NX_CHAR): + doc: | + Indicates the name of the last operation applied in the NXprocess sequence. + depends_on(NX_CHAR): + doc: | + Specifies the position by pointing to the last transformation in the + transformation chain in the NXtransformations group. + (NXtransformations): + doc: | + To describe the operations of image registration (combinations of rigid + translations and rotations) + description(NX_CHAR): + doc: | + Description of the procedures employed. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cc7ade75e51e97bb8a6cb9c2f6b233cca38c45fb8ebcead76a3014a6653d731a +# +# +# +# +# +# Describes image registration procedures. +# +# +# +# Has the registration been applied? +# +# +# +# +# Indicates the name of the last operation applied in the NXprocess sequence. +# +# +# +# +# Specifies the position by pointing to the last transformation in the +# transformation chain in the NXtransformations group. +# +# +# +# +# To describe the operations of image registration (combinations of rigid +# translations and rotations) +# +# +# +# +# Description of the procedures employed. +# +# +# diff --git a/contributed_definitions/nyaml/NXresolution.yaml b/contributed_definitions/nyaml/NXresolution.yaml new file mode 100644 index 0000000000..b999a7ee73 --- /dev/null +++ b/contributed_definitions/nyaml/NXresolution.yaml @@ -0,0 +1,160 @@ +category: base +doc: | + Describes the resolution of a physical quantity. +type: group +NXresolution(NXobject): + physical_quantity: + doc: | + The physical quantity of the resolution, e.g., + energy, momentum, time, etc. + type: + doc: | + The process by which the resolution was determined. + enumeration: [estimated, derived, calibrated, other] + note(NXnote): + doc: | + Additional details of the estimate or description of the calibration procedure + resolution(NX_FLOAT): + unit: NX_ANY + doc: | + The resolution of the physical quantity. + resolution_errors(NX_FLOAT): + unit: NX_ANY + doc: | + Standard deviation of the resolution of the physical quantity. + response_function(NXdata): + doc: | + The response of the instrument or part to a infinitesimally sharp input signal + along the physical quantity of this group. + This is also sometimes called instrument response function for time resolution or + point spread function for spatial response. + The resolution is typically determined by taking the full width at half maximum (FWHM) + of the response function. + input(NX_FLOAT): + unit: NX_ANY + doc: | + The input axis or grid of the response function. + The unit should match the one of the resolution field. + magnitude(NX_FLOAT): + doc: | + The magnitude of the response function corresponding to the points + in the input axis or grid. + This field should have the same dimensions as `input`. + formula_SYMBOL(NX_CHAR): + doc: | + A symbol linking to another path in this appdef to be referred to from the + `resolution_formula` field. This should be a valid path inside this application + definition, i.e., of the form /entry/instrument/my_part/my_field. + resolution_formula(NX_CHAR): + doc: | + A resolution formula to determine the resolution from a set of symbols as + entered by the `formula_...` fields. + The output unit should match the provided unit of this field. + (NXcalibration): + doc: | + For storing details and data of a calibration to derive a resolution from data. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e450b40edd82c4031bf6e7d9195ad6a844aceb9a6effced07c8001bb25f8a01b +# +# +# +# +# +# Describes the resolution of a physical quantity. +# +# +# +# The physical quantity of the resolution, e.g., +# energy, momentum, time, etc. +# +# +# +# +# The process by which the resolution was determined. +# +# +# +# +# +# +# +# +# +# +# Additional details of the estimate or description of the calibration procedure +# +# +# +# +# The resolution of the physical quantity. +# +# +# +# +# Standard deviation of the resolution of the physical quantity. +# +# +# +# +# The response of the instrument or part to a infinitesimally sharp input signal +# along the physical quantity of this group. +# This is also sometimes called instrument response function for time resolution or +# point spread function for spatial response. +# The resolution is typically determined by taking the full width at half maximum (FWHM) +# of the response function. +# +# +# +# The input axis or grid of the response function. +# The unit should match the one of the resolution field. +# +# +# +# +# The magnitude of the response function corresponding to the points +# in the input axis or grid. +# This field should have the same dimensions as `input`. +# +# +# +# +# +# A symbol linking to another path in this appdef to be referred to from the +# `resolution_formula` field. This should be a valid path inside this application +# definition, i.e., of the form /entry/instrument/my_part/my_field. +# +# +# +# +# A resolution formula to determine the resolution from a set of symbols as +# entered by the `formula_...` fields. +# The output unit should match the provided unit of this field. +# +# +# +# +# For storing details and data of a calibration to derive a resolution from data. +# +# +# diff --git a/contributed_definitions/nyaml/NXroi.yaml b/contributed_definitions/nyaml/NXroi.yaml new file mode 100644 index 0000000000..a8ba2426ad --- /dev/null +++ b/contributed_definitions/nyaml/NXroi.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to describe a region-of-interest analyzed. +type: group +NXroi(NXobject): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): diff --git a/contributed_definitions/nyaml/NXrotation_set.yaml b/contributed_definitions/nyaml/NXrotation_set.yaml new file mode 100644 index 0000000000..a83f889344 --- /dev/null +++ b/contributed_definitions/nyaml/NXrotation_set.yaml @@ -0,0 +1,177 @@ +category: base +doc: | + Base class to detail a set of rotations, orientations, and disorientations. + + For getting a more detailed insight into the discussion of the + parameterized description of orientations in materials science see: + + * `H.-J. Bunge `_ + * `T. B. Britton et al. `_ + * `D. Rowenhorst et al. `_ + * `A. Morawiec `_ + + Once orientations are defined, one can continue to characterize the + misorientation and specifically the disorientation. The misorientation describes + the rotation that is required to register the lattices of two oriented objects + (like crystal lattice) into a crystallographic equivalent orientation: + + * `R. Bonnet `_ + +# This class stores a set of specifically parameterized NXtransformations which describe +# how each object is oriented/rotated with respect to a reference coordinate system. +# we should offer here support for d==2, d==3 +# several well accepted parameterizations for rotations exists in Materials Science +# thus not using NXtransformations, different Materials Science groups follow +# different conventions not every reporting of rotations is consistent and correct +# having a base class like the one proposed here offers a suggestion to start +# discussing at all about how to convert between groups who report using +# different conventions +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + The cardinality of the set, i.e. the number of value tuples. + n_phases: | + How many phases with usually different crystal and symmetry are distinguished. +type: group +NXrotation_set(NXobject): + \@depends_on(NX_CHAR): + doc: | + Reference to an instance of :ref:`NXem_conventions` which contextualizes + how the here reported parameterized quantities can be interpreted. + # 2D rotations are a special type of 3D rotations and thus treated in 3D + # just how to rotate the object into the reference frame defined by depends_on + crystal_symmetry(NX_CHAR): + doc: | + Point group which defines the symmetry of the crystal. + + This has to be at least a single string. If crystal_symmetry is not + provided point group 1 is assumed. + + In the case that misorientation or disorientation fields are used + and the two crystal sets resolve for phases with a different + crystal symmetry, this field has to encode two string. + In this case the first string is for phase A the second one for phase B. + An example of this most complex case is the description of the + disorientation between crystals adjoining a hetero-phase boundary. + dim: (n_phases,) + sample_symmetry(NX_CHAR): + doc: | + Point group which defines an assumed symmetry imprinted upon processing + the material/sample which could give rise to or may justify to use a + simplified description of rotations, orientations, misorientations, + and disorientations via numerical procedures that are known as + symmetrization. + + If sample_symmetry is not provided point group 1 is assumed. + + The traditionally used symmetrization operations within the texture + community in Materials Science, though, are thanks to methodology and + software improvements no longer strictly needed. Therefore, users are + encouraged to set the sample_symmetry to 1 (triclinic) and thus assume + there is no justification to assume the imprinting of additional + symmetry because of the processing. + + In practice one often faces situations where indeed these assumed + symmetries are anyway not fully observed, and thus an accepting of + eventual inaccuracies just for the sake of reporting a simplified + symmetrized description should be avoided. + dim: (n_phases,) + rotation_quaternion(NX_NUMBER): # H \in SO3 + doc: | + The set of rotations expressed in quaternion parameterization considering + crystal_symmetry and sample_symmetry. Rotations which should be + interpreted as antipodal are not marked as such. + unit: NX_DIMENSIONLESS + dim: (c, 4) + rotation_euler(NX_NUMBER): + doc: | + The set of rotations expressed in Euler angle parameterization considering + the same applied symmetries as detailed for the field rotation_quaternion. + To interpret Euler angles correctly, it is necessary to inspect the + conventions behind depends_on to resolve which of the many Euler-angle + conventions possible (Bunge ZXZ, XYZ, Kocks, Tait, etc.) were used. + unit: NX_ANGLE + dim: (c, 3) + # rotation_rodrigues(NX_NUMBER): + # rotation_homochoric(NX_NUMBER): + # rotation_axis_angle(NX_NUMBER): + + # orientation how to rotate the crystal into sample and vice versa obeying crystal and sample symmetry + is_antipodal(NX_BOOLEAN): + doc: | + True for all those value tuples which have assumed antipodal symmetry. + False for all others. + dim: (c,) + orientation_quaternion(NX_NUMBER): + doc: | + The set of orientations expressed in quaternion parameterization and + obeying symmetry for equivalent cases as detailed in crystal_symmetry + and sample_symmetry. The supplementary field is_antipodal can be used + to mark orientations with the antipodal property. + unit: NX_DIMENSIONLESS + dim: (c, 4) + orientation_euler(NX_NUMBER): + unit: NX_ANGLE + doc: | + The set of orientations expressed in Euler angle parameterization following + the same assumptions like for orientation_quaternion. + To interpret Euler angles correctly, it is necessary to inspect the + conventions behind depends_on to resolve which of the many Euler-angle + conventions possible (Bunge ZXZ, XYZ, Kocks, Tait, etc.) were used. + dim: (c, 3) + # orientation_rodrigues(NX_NUMBER): + # orientation_homochoric(NX_NUMBER): + # orientation_axis_angle(NX_NUMBER): + + # misorientation between two orientations + # not the disorientation because for misorientation we ignore + # if the angular argument may not have the absolute smallest amount, i.e. + # misorientation is not necessarily in the fundamental zone + misorientation_quaternion(NX_NUMBER): + doc: | + The set of misorientations expressed in quaternion parameterization + obeying symmetry operations for equivalent misorientations + as defined by crystal_symmetry and sample_symmetry. + unit: NX_DIMENSIONLESS + dim: (c, 4) + misorientation_angle(NX_NUMBER): + doc: | + Misorientation angular argument (eventually signed) following the same + symmetry assumptions as expressed for the field misorientation_quaternion. + unit: NX_ANGLE + dim: (c,) + misorientation_axis(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Misorientation axis (normalized) and signed following the same + symmetry assumptions as expressed for the field misorientation_angle. + dim: (c, 3) + + # disorientation, misorientation with smallest angular argument inside + # fundamental zone of SO3 for given crystal and sample symmetry + disorientation_quaternion(NX_NUMBER): + doc: | + The set of disorientation expressed in quaternion parameterization + obeying symmetry operations for equivalent misorientations + as defined by crystal_symmetry and sample_symmetry. + unit: NX_DIMENSIONLESS + dim: (c, 4) + disorientation_angle(NX_NUMBER): + doc: | + Disorientation angular argument (should not be signed, see + `D. Rowenhorst et al. `_) + following the same symmetry assumptions as expressed for the field + disorientation_quaternion. + unit: NX_ANGLE + dim: (c,) + disorientation_axis(NX_NUMBER): + doc: | + Disorientation axis (normalized) following the same symmetry assumptions + as expressed for the field disorientation_angle. + unit: NX_DIMENSIONLESS + dim: (c, 3) + # e.g. in this way one could easily, efficiently, store and map familiar habits of microscopists + # to store e.g. orientations of measurement points or of grains via a (c := Ngrains, n_p := 3) + # matrix of Bunge-Euler angles, or of (c := Ngrains, n_p := 4) matrix of quaternions. + # the benefit of such a representation is that with a known NXorientation_set base class one can implement a common parameterization transformation library (of which several already exist) in the microstructure modelling communities so that a program can read the information in the (NXorientation_set) instance and automatically transform/compute between different parameterizations. Super relevant for interoperability e.g. in SEM/EBSD, where this was a long standing issue and right now the most frequently accepted consensus is to report either Bunge-Euler angles or quaternions and then use existent transformation libraries (as implemented by e.g. Marc de Graeff for SEM/EBSD and used by many but not yet the majority of people in the computational materials modelling community within crystal plasticity, crystal growth modeling, DREAM.3D) diff --git a/contributed_definitions/nyaml/NXsample_component_set.yaml b/contributed_definitions/nyaml/NXsample_component_set.yaml new file mode 100644 index 0000000000..2567b25d49 --- /dev/null +++ b/contributed_definitions/nyaml/NXsample_component_set.yaml @@ -0,0 +1,123 @@ +category: base +doc: | + Set of sample components and their configuration. + + The idea here is to have a united place for all materials descriptors that are not + part of the individual sample components, but rather their configuration. +symbols: + n_comp: | + number of components +type: group +NXsample_component_set(NXobject): + \@components: + doc: | + Array of strings referring to the names of the NXsample_components. + The order of these components serves as an index (starting at 1). + concentration(NX_FLOAT): + unit: NX_ANY + doc: | + Concentration of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + volume_fraction(NX_FLOAT): + unit: NX_ANY + doc: | + Volume fraction of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + scattering_length_density(NX_FLOAT): + unit: NX_ANY + doc: | + Scattering length density of each component + dimensions: + rank: 1 + dim: [[1, n_comp]] + (NXsample_component): + doc: | + Each component set can contain multiple components. + (NXsample_component_set): + doc: | + For description of a sub-component set. Can contain multiple components itself. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e4d79347fce002e76308abff05f0abadc367858578fa4b9429ebff02d069f395 +# +# +# +# +# +# +# +# number of components +# +# +# +# +# Set of sample components and their configuration. +# +# The idea here is to have a united place for all materials descriptors that are not +# part of the individual sample components, but rather their configuration. +# +# +# +# Array of strings referring to the names of the NXsample_components. +# The order of these components serves as an index (starting at 1). +# +# +# +# +# Concentration of each component +# +# +# +# +# +# +# +# Volume fraction of each component +# +# +# +# +# +# +# +# Scattering length density of each component +# +# +# +# +# +# +# +# Each component set can contain multiple components. +# +# +# +# +# For description of a sub-component set. Can contain multiple components itself. +# +# +# diff --git a/contributed_definitions/nyaml/NXsample_history.yaml b/contributed_definitions/nyaml/NXsample_history.yaml new file mode 100644 index 0000000000..779dfd02aa --- /dev/null +++ b/contributed_definitions/nyaml/NXsample_history.yaml @@ -0,0 +1,108 @@ +category: base +doc: | + A set of activities that occurred to the sample prior/during experiment. + + Ideally, a full report of the previous operations (or links to a chain of operations). + Alternatively, notes allow for additional descriptors in any format. +type: group +NXsample_history(NXobject): + (NXactivity): + doc: | + Any activity that was performed on the sample prior or during the experiment. In + the future, if there is base class inheritance, this can describe any activity, + including processes and measurements. + + # For now, one workaround would be to have NXactivity as a application definition with a subentry. + # subentry(NXsuxbentry): + # doc: | + # Any activity that was performed on the sample prior or during the experiment. + # definition: ["NXactivity"] + (NXphysical_process): + doc: | + Any physical process that was performed on the sample prior or during the + experiment. + (NXchemical_process): + doc: | + Any chemical process that was performed on the sample prior or during the + experiment. + + # There should be more activities here, like measurement. + notes(NXnote): + doc: | + A descriptor to keep track of the treatment of the sample before or during the + experiment (NXnote allows to add pictures, audio, movies). Alternatively, a + reference to the location or a unique identifier or other metadata file. In the + case these are not available, free-text description. + This should only be used in case that there is no rigorous description + using the base classes above. This field can also be used to pull in any activities + that are not well described by an existing base class definition. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# bbf87f9c949f2f8af78e20e6f7b447ef3c970fa8d5c142863c3416a5826c4893 +# +# +# +# +# +# A set of activities that occurred to the sample prior/during experiment. +# +# Ideally, a full report of the previous operations (or links to a chain of operations). +# Alternatively, notes allow for additional descriptors in any format. +# +# +# +# Any activity that was performed on the sample prior or during the experiment. In +# the future, if there is base class inheritance, this can describe any activity, +# including processes and measurements. +# +# +# +# +# +# Any physical process that was performed on the sample prior or during the +# experiment. +# +# +# +# +# Any chemical process that was performed on the sample prior or during the +# experiment. +# +# +# +# +# +# A descriptor to keep track of the treatment of the sample before or during the +# experiment (NXnote allows to add pictures, audio, movies). Alternatively, a +# reference to the location or a unique identifier or other metadata file. In the +# case these are not available, free-text description. +# This should only be used in case that there is no rigorous description +# using the base classes above. This field can also be used to pull in any activities +# that are not well described by an existing base class definition. +# +# +# diff --git a/contributed_definitions/nyaml/NXscanbox_em.yaml b/contributed_definitions/nyaml/NXscanbox_em.yaml new file mode 100644 index 0000000000..7fa3588434 --- /dev/null +++ b/contributed_definitions/nyaml/NXscanbox_em.yaml @@ -0,0 +1,50 @@ +category: base +doc: | + Scan box and coils which deflect a beam of charged particles in a controlled manner. + + The scan box is instructed by an instance of :ref:`NXprogram`, some control software, + which is not necessarily the same program as for all components of a microscope. + + The scanbox directs the probe of charged particles (electrons, ions) + to controlled locations according to a scan scheme and plan. + + To achieve this task, the scanbox typically contains deflection coils, + which should be modelled as instances of :ref:`NXdeflector`. +type: group +NXscanbox_em(NXcomponent_em): + calibration_style(NX_CHAR): + doc: | + TODO discuss with the electron microscopists. + center(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_ANY + flyback_time(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_TIME + line_time(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_TIME + # pixel_dwell_time? + pixel_time(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_TIME + requested_pixel_time(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_TIME + rotation(NX_NUMBER): + doc: | + TODO discuss with the electron microscopists. + unit: NX_ANGLE + ac_line_sync(NX_BOOLEAN): + doc: | + TODO discuss with the electron microscopists. + (NXdeflector): + + # (NXcg_point_set): + # NEW ISSUE: build on work of EMglossary with HMC and use duty cycle instead + # NEW ISSUE: make use of and define duty cycle diff --git a/contributed_definitions/nyaml/NXsensor_scan.yaml b/contributed_definitions/nyaml/NXsensor_scan.yaml new file mode 100644 index 0000000000..0eea319826 --- /dev/null +++ b/contributed_definitions/nyaml/NXsensor_scan.yaml @@ -0,0 +1,335 @@ +category: application +doc: | + Application definition for a generic scan using sensors. + + In this application definition, times should be specified always together + with an UTC offset. +symbols: + doc: | + Variables used to set a common size for collected sensor data. + N_scanpoints: | + The number of scan points measured in this scan. +type: group +NXsensor_scan(NXobject): + (NXentry): + definition(NX_CHAR): + \@version: + enumeration: [NXsensor_scan] + experiment_identifier(NX_CHAR): + exists: recommended + experiment_description(NX_CHAR): + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + (NXprocess): + doc: | + Define the program that was used to generate the results file(s) + with measured data and metadata. + program(NX_CHAR): + doc: | + Commercial or otherwise defined given name of the program + (or a link to the instrument software). + \@version: + doc: | + Either version with build number, commit hash, or description of an + (online) repository where the source code of the program and build + instructions can be found so that the program can be configured in + such a way that result files can be created ideally in a + deterministic manner. + \@program_url: + doc: | + Website of the software. + (NXuser): + doc: | + Contact information of at least the user of the instrument or the + investigator who performed this experiment. Adding multiple users if + relevant is recommended. + name(NX_CHAR): + doc: | + Name of the user. + affiliation(NX_CHAR): + exists: recommended + doc: | + Name of the affiliation of the user at the point in time when + the experiment was performed. + address(NX_CHAR): + exists: recommended + doc: | + Full address (street, street number, ZIP, city, country) + of the user's affiliation. + email(NX_CHAR): + exists: recommended + doc: | + Email address of the user. + orcid(NX_CHAR): + exists: recommended + doc: | + Author ID defined by https://orcid.org/. + telephone_number(NX_CHAR): + exists: recommended + doc: | + Official telephone number of the user. + (NXinstrument): + (NXenvironment): + doc: | + Describes an environment setup for the experiment. + + All the setting values of the independently scanned controllers are listed under corresponding + NXsensor groups. Similarly, seperate NXsensor groups are used to store the readings from each + measurement sensor. + + For example, in a temperature-dependent IV measurement, the temperature and voltage must be + present as independently scanned controllers and the current sensor must also be present with + its readings. + (NXsensor): + (NXdata): + exists: recommended + doc: | + Plot of measured signal as a function of the timestamp of when they have been + acquired is also possible. + value(NX_FLOAT): + unit: NX_ANY + doc: | + For each point in the scan space, either the nominal setpoint of an independently scanned controller + or a representative average value of a measurement sensor is registered. + + The length of each sensor's data value array stored in this group should be equal to the number of scan points + probed in this scan. For every scan point [N], the corresponding sensor value can be picked from index [N]. + This allows the scan to be made in any order as the user describes above in the experiment. We get matching + values simply using the index of the scan point. + dimensions: + rank: 1 + dim: [[1, N_scanpoints]] + value_timestamp(NX_DATE_TIME): + exists: recommended + doc: | + Timestamp for when the values provided in the value field were registered. + + Individual readings can be stored with their timestamps under value_log. This is to timestamp + the nominal setpoint or average reading values listed above in the value field. + run_control(NX_CHAR): + exists: recommended + \@description: + doc: | + Free-text describing the data acquisition control: an internal + sweep using the built-in functionality of the controller device, + or a set/wait/read/repeat mechanism. + calibration_time(NX_DATE_TIME): + doc: | + ISO8601 datum when calibration was last performed + before this measurement. UTC offset should be specified. + (NXpid): + independent_controllers: + doc: | + A list of names of NXsensor groups used as independently scanned controllers. + measurement_sensors: + doc: | + A list of names of NXsensor groups used as measurement sensors. + (NXsample): + name(NX_CHAR): + (NXdata): + doc: | + A scan specific representation of the measured signals as a function of the independently controlled environment settings. + Plot of every measured signal as a function of the timestamp of when they have been acquired is also possible. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5eb0510291ac6f2adfa9fae7ce4425bfb6c9b9a584bbca2d28d32d7beb291a58 +# +# +# +# +# +# +# Variables used to set a common size for collected sensor data. +# +# +# +# The number of scan points measured in this scan. +# +# +# +# +# Application definition for a generic scan using sensors. +# +# In this application definition, times should be specified always together +# with an UTC offset. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Define the program that was used to generate the results file(s) +# with measured data and metadata. +# +# +# +# Commercial or otherwise defined given name of the program +# (or a link to the instrument software). +# +# +# +# Either version with build number, commit hash, or description of an +# (online) repository where the source code of the program and build +# instructions can be found so that the program can be configured in +# such a way that result files can be created ideally in a +# deterministic manner. +# +# +# +# +# Website of the software. +# +# +# +# +# +# +# Contact information of at least the user of the instrument or the +# investigator who performed this experiment. Adding multiple users if +# relevant is recommended. +# +# +# +# Name of the user. +# +# +# +# +# Name of the affiliation of the user at the point in time when +# the experiment was performed. +# +# +# +# +# Full address (street, street number, ZIP, city, country) +# of the user's affiliation. +# +# +# +# +# Email address of the user. +# +# +# +# +# Author ID defined by https://orcid.org/. +# +# +# +# +# Official telephone number of the user. +# +# +# +# +# +# +# Describes an environment setup for the experiment. +# +# All the setting values of the independently scanned controllers are listed under corresponding +# NXsensor groups. Similarly, seperate NXsensor groups are used to store the readings from each +# measurement sensor. +# +# For example, in a temperature-dependent IV measurement, the temperature and voltage must be +# present as independently scanned controllers and the current sensor must also be present with +# its readings. +# +# +# +# +# Plot of measured signal as a function of the timestamp of when they have been +# acquired is also possible. +# +# +# +# +# For each point in the scan space, either the nominal setpoint of an independently scanned controller +# or a representative average value of a measurement sensor is registered. +# +# The length of each sensor's data value array stored in this group should be equal to the number of scan points +# probed in this scan. For every scan point [N], the corresponding sensor value can be picked from index [N]. +# This allows the scan to be made in any order as the user describes above in the experiment. We get matching +# values simply using the index of the scan point. +# +# +# +# +# +# +# +# Timestamp for when the values provided in the value field were registered. +# +# Individual readings can be stored with their timestamps under value_log. This is to timestamp +# the nominal setpoint or average reading values listed above in the value field. +# +# +# +# +# +# Free-text describing the data acquisition control: an internal +# sweep using the built-in functionality of the controller device, +# or a set/wait/read/repeat mechanism. +# +# +# +# +# +# ISO8601 datum when calibration was last performed +# before this measurement. UTC offset should be specified. +# +# +# +# +# +# +# A list of names of NXsensor groups used as independently scanned controllers. +# +# +# +# +# A list of names of NXsensor groups used as measurement sensors. +# +# +# +# +# +# +# +# +# +# A scan specific representation of the measured signals as a function of the independently controlled environment settings. +# Plot of every measured signal as a function of the timestamp of when they have been acquired is also possible. +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsensor_sts.yaml b/contributed_definitions/nyaml/NXsensor_sts.yaml new file mode 100644 index 0000000000..9403c62f77 --- /dev/null +++ b/contributed_definitions/nyaml/NXsensor_sts.yaml @@ -0,0 +1,384 @@ +category: base +doc: | + A sensor used to monitor an external condition + + The condition itself is described in :ref:`NXenvironment`. +type: group +NXsensor_sts(NXobject): + model: + doc: | + Sensor identification code/model number + name: + doc: | + Name for the sensor + short_name: + doc: | + Short name of sensor used e.g. on monitor display program + attached_to: + doc: | + where sensor is attached to ("sample" | "can") + geometry(NXgeometry): + deprecated: | + Use the field `depends_on` and :ref:`NXtransformations` to position the beamstop and NXoff_geometry to describe its shape instead + doc: | + Defines the axes for logged vector quantities if they are not the global + instrument axes. + measurement: + doc: | + name for measured signal + enumeration: [temperature, pH, magnetic_field, electric_field, conductivity, resistance, voltage, current, pressure, flow, stress, strain, shear, surface_pressure] + type: + doc: | + The type of hardware used for the measurement. + Examples (suggestions but not restrictions): + + :Temperature: + J | K | T | E | R | S | Pt100 | Pt1000 | Rh/Fe + :pH: + Hg/Hg2Cl2 | Ag/AgCl | ISFET + :Ion selective electrode: + specify species; e.g. Ca2+ + :Magnetic field: + Hall + :Surface pressure: + wilhelmy plate + amplifier(NXamplifier): + second_amplifier(NXcircuit): + doc: | + link to second amplifer circuit with 1MOhm + run_control(NX_BOOLEAN): + doc: | + Is data collection controlled or synchronised to this quantity: + 1=no, 0=to "value", 1=to "value_deriv1", etc. + high_trip_value(NX_FLOAT): + unit: NX_ANY + doc: | + Upper control bound of sensor reading if using run_control + low_trip_value(NX_FLOAT): + unit: NX_ANY + doc: | + Lower control bound of sensor reading if using run_control + value(NX_FLOAT): + unit: NX_ANY + doc: | + nominal setpoint or average value + - need [n] as may be a vector + dimensions: + dim: [[1, n]] + value_deriv1(NX_FLOAT): + unit: NX_ANY + doc: | + Nominal/average first derivative of value + e.g. strain rate + - same dimensions as "value" (may be a vector) + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['value'] + value_deriv2(NX_FLOAT): + unit: NX_ANY + doc: | + Nominal/average second derivative of value + - same dimensions as "value" (may be a vector) + dimensions: + dim: [[1, ]] + dim_parameters: + ref: ['value'] + value_log(NXlog): + doc: | + Time history of sensor readings + value_deriv1_log(NXlog): + doc: | + Time history of first derivative of sensor readings + value_deriv2_log(NXlog): + doc: | + Time history of second derivative of sensor readings + external_field_brief: + enumeration: [along beam, across beam, transverse, solenoidal, flow shear gradient, flow vorticity] + external_field_full(NXorientation): + doc: | + For complex external fields not satisfied by External_field_brief + (NXoff_geometry): + exists: ['min', '0'] + doc: | + This group describes the shape of the sensor when necessary. + \@default: + doc: | + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + depends_on(NX_CHAR): + doc: | + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + .. todo:: + Add a definition for the reference point of a sensor. + (NXtransformations): + doc: | + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + doc: | + External sensors connected to the device. For example, T1, temperature of STM + head. T2, temperature of bottom of LHe helium cryostat. T3, temperature of LN2 + nitrogen shield. + pressure(NX_NUMBER): + unit: NX_PRESSURE + doc: | + External sensors connected to the device. Pressure of each chamber or ion pump, + such as prepare chamber and analysis chamber + power_spectral_density(NX_NUMBER): + doc: | + The power present in the signal as a function of frequency. Used to characterise + the vibration and noise of scanning probes to detect and reduce the impact on + resolution during STM imaging + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e9d1c4dfb1ffa31931d46320db4e37890c8876331bee6ecc729f3ac844d23a01 +# +# +# +# +# +# A sensor used to monitor an external condition +# +# The condition itself is described in :ref:`NXenvironment`. +# +# +# +# Sensor identification code/model number +# +# +# +# +# Name for the sensor +# +# +# +# +# Short name of sensor used e.g. on monitor display program +# +# +# +# +# where sensor is attached to ("sample" | "can") +# +# +# +# +# Defines the axes for logged vector quantities if they are not the global +# instrument axes. +# +# +# +# +# name for measured signal +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# The type of hardware used for the measurement. +# Examples (suggestions but not restrictions): +# +# :Temperature: +# J | K | T | E | R | S | Pt100 | Pt1000 | Rh/Fe +# :pH: +# Hg/Hg2Cl2 | Ag/AgCl | ISFET +# :Ion selective electrode: +# specify species; e.g. Ca2+ +# :Magnetic field: +# Hall +# :Surface pressure: +# wilhelmy plate +# +# +# +# +# +# link to second amplifer circuit with 1MOhm +# +# +# +# +# Is data collection controlled or synchronised to this quantity: +# 1=no, 0=to "value", 1=to "value_deriv1", etc. +# +# +# +# +# Upper control bound of sensor reading if using run_control +# +# +# +# +# Lower control bound of sensor reading if using run_control +# +# +# +# +# nominal setpoint or average value +# - need [n] as may be a vector +# +# +# +# +# +# +# +# Nominal/average first derivative of value +# e.g. strain rate +# - same dimensions as "value" (may be a vector) +# +# +# +# +# +# +# +# Nominal/average second derivative of value +# - same dimensions as "value" (may be a vector) +# +# +# +# +# +# +# +# Time history of sensor readings +# +# +# +# +# Time history of first derivative of sensor readings +# +# +# +# +# Time history of second derivative of sensor readings +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# For complex external fields not satisfied by External_field_brief +# +# +# +# +# This group describes the shape of the sensor when necessary. +# +# +# +# +# .. index:: plotting +# +# Declares which child group contains a path leading +# to a :ref:`NXdata` group. +# +# It is recommended (as of NIAC2014) to use this attribute +# to help define the path to the default dataset to be plotted. +# See https://www.nexusformat.org/2014_How_to_find_default_data.html +# for a summary of the discussion. +# +# +# +# +# NeXus positions components by applying a set of translations and rotations +# to apply to the component starting from 0, 0, 0. The order of these operations +# is critical and forms what NeXus calls a dependency chain. The depends_on +# field defines the path to the top most operation of the dependency chain or the +# string "." if located in the origin. Usually these operations are stored in a +# NXtransformations group. But NeXus allows them to be stored anywhere. +# +# .. todo:: +# Add a definition for the reference point of a sensor. +# +# +# +# +# This is the group recommended for holding the chain of translation +# and rotation operations necessary to position the component within +# the instrument. The dependency chain may however traverse similar groups in +# other component groups. +# +# +# +# +# External sensors connected to the device. For example, T1, temperature of STM +# head. T2, temperature of bottom of LHe helium cryostat. T3, temperature of LN2 +# nitrogen shield. +# +# +# +# +# External sensors connected to the device. Pressure of each chamber or ion pump, +# such as prepare chamber and analysis chamber +# +# +# +# +# The power present in the signal as a function of frequency. Used to characterise +# the vibration and noise of scanning probes to detect and reduce the impact on +# resolution during STM imaging +# +# +# diff --git a/contributed_definitions/nyaml/NXseparator.yaml b/contributed_definitions/nyaml/NXseparator.yaml new file mode 100644 index 0000000000..f3d94ab6ac --- /dev/null +++ b/contributed_definitions/nyaml/NXseparator.yaml @@ -0,0 +1,108 @@ +category: base +doc: | + definition for an electrostatic separator. +type: group +NXseparator(NXobject): + description(NX_CHAR): + doc: | + extended description of the separator. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + set_Bfield_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on magnet supply. + read_Bfield_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from magnet supply. + value: + unit: NX_CURRENT + read_Bfield_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from magnet supply. + value: + unit: NX_VOLTAGE + set_Efield_voltage(NX_FLOAT): + unit: NX_VOLTAGE + exists: ['min', '0', 'max', '1'] + doc: | + current set on HT supply. + read_Efield_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from HT supply. + value: + unit: NX_CURRENT + read_Efield_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from HT supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0221be104fb3192c4a5b942ad422bee251f3519e222030df39dbc3acf85b4fc4 +# +# +# +# +# definition for an electrostatic separator. +# +# extended description of the separator. +# +# +# define position of beamline element relative to production target +# +# +# current set on magnet supply. +# +# +# current read from magnet supply. +# +# +# +# voltage read from magnet supply. +# +# +# +# current set on HT supply. +# +# +# current read from HT supply. +# +# +# +# voltage read from HT supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXserialized.yaml b/contributed_definitions/nyaml/NXserialized.yaml new file mode 100644 index 0000000000..6aa90f4b45 --- /dev/null +++ b/contributed_definitions/nyaml/NXserialized.yaml @@ -0,0 +1,37 @@ +category: base +doc: | + Metadata to a set of pieces of information of a resource that has been serialized. + + A typical use case is the documentation of the source (file) or database (entry) + from which pieces of information have been extracted for consumption in e.g. a + research data management system (RDMS). This may be for reasons of enabling + services such as providing access to normalized information for which reading + again from the resource may not be desired, possibe, or feasible. + + Possible reasons could be the extraction of specific information for caching, + performance reasons, or re-evaluate given pieces of information based on other + views and interaction patterns with the data where information has been formatted + differently by tools than how these pieces of information were originally + serialized. +type: group +NXserialized(NXobject): + type(NX_CHAR): + doc: | + Answers into what resource the information was serialized. + enumeration: [file, database] + path(NX_CHAR): + doc: | + Path to the resource. + + E.g. the name of a file or its absolute or relative path, or the + identifier to a resource in another database. + checksum(NX_CHAR): + doc: | + Value of the checksum obtain when running algorithm on the resource. + algorithm(NX_CHAR): + doc: | + Name of the algorithm whereby the checksum was computed. + enumeration: [md5, sha256] + file(NXnote): + doc: | + Extracted file containing the serialized information. \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXsimilarity_grouping.yaml b/contributed_definitions/nyaml/NXsimilarity_grouping.yaml new file mode 100644 index 0000000000..36c2607eb5 --- /dev/null +++ b/contributed_definitions/nyaml/NXsimilarity_grouping.yaml @@ -0,0 +1,290 @@ +category: base +doc: | + Metadata to the results of a similarity grouping analysis. + + Similarity grouping analyses can be supervised segmentation or machine learning + clustering algorithms. These are routine methods which partition the member of + a set of objects/geometric primitives into (sub-)groups, features of + different type. A plethora of algorithms have been proposed which can be applied + also on geometric primitives like points, triangles, or (abstract) features aka + objects (including categorical sub-groups). + + This base class considers metadata and results of one similarity grouping + analysis applied to a set in which objects are either categorized as noise + or belonging to a cluster. + As the results of the analysis each similarity group, here called feature + aka object can get a number of numerical and/or categorical labels. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + c: | + Cardinality of the set. + n_lbl_num: | + Number of numerical labels per object. + n_lbl_cat: | + Number of categorical labels per object. + n_features: | + Total number of similarity groups aka features, objects, clusters. +type: group +NXsimilarity_grouping(NXobject): + cardinality(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of members in the set which is partitioned into features. + number_of_numeric_labels(NX_UINT): + unit: NX_UNITLESS + doc: | + How many numerical labels does each feature have. + number_of_categorical_labels(NX_UINT): + unit: NX_UNITLESS + doc: | + How many categorical labels does each feature have. + + # features: + # doc: | + # Reference to a set of features investigated in a cluster analysis. + # Features need to have disjoint numeric identifier. + identifier_offset(NX_UINT): + unit: NX_UNITLESS + doc: | + Which identifier is the first to be used to label a cluster. + + The value should be chosen in such a way that special values can be resolved: + * identifier_offset-1 indicates an object belongs to no cluster. + * identifier_offset-2 indicates an object belongs to the noise category. + Setting for instance identifier_offset to 1 recovers the commonly used + case that objects of the noise category get values to -1 and unassigned points to 0. + Numerical identifier have to be strictly increasing. + dimensions: + rank: 1 + dim: [[1, n_lbl_num]] + numerical_label(NX_UINT): + unit: NX_UNITLESS + doc: | + Matrix of numerical label for each member in the set. + For classical clustering algorithms this can for instance + encode the cluster_identifier. + dimensions: + rank: 2 + dim: [[1, c], [2, n_lbl_num]] + categorical_label(NX_CHAR): + doc: | + Matrix of categorical attribute data for each member in the set. + + # list instances of base classes of an applied cluster algorithm + # e.g. (NXclustering_hdbscan): + dimensions: + rank: 2 + dim: [[1, c], [2, n_lbl_cat]] + statistics(NXprocess): + doc: | + In addition to the detailed storage which members was grouped to which + feature/group summary statistics are stored under this group. + + # at the level of the set + number_of_unassigned_members(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of members in the set which are categorized as unassigned. + dimensions: + rank: 1 + dim: [[1, n_lbl_num]] + noise(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of members in the set which are categorized as noise. + dimensions: + rank: 1 + dim: [[1, n_lbl_num]] + + # at the level of the feature set + number_of_features(NX_UINT): + unit: NX_UNITLESS + doc: | + Total number of clusters (excluding noise and unassigned). + feature_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of numerical identifier of each feature (cluster). + dimensions: + rank: 2 + dim: [[1, n_features], [2, n_lbl_num]] + feature_member_count(NX_UINT): + unit: NX_UNITLESS + doc: | + Array of number of members for each feature. + dimensions: + rank: 2 + dim: [[1, n_features], [2, n_lbl_num]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b6a955e00d978d62e58fa73c93c262a104d7b49152e2a9cf054abbc8eaa1d46b +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Cardinality of the set. +# +# +# +# +# Number of numerical labels per object. +# +# +# +# +# Number of categorical labels per object. +# +# +# +# +# Total number of similarity groups aka features, objects, clusters. +# +# +# +# +# Metadata to the results of a similarity grouping analysis. +# +# Similarity grouping analyses can be supervised segmentation or machine learning +# clustering algorithms. These are routine methods which partition the member of +# a set of objects/geometric primitives into (sub-)groups, features of +# different type. A plethora of algorithms have been proposed which can be applied +# also on geometric primitives like points, triangles, or (abstract) features aka +# objects (including categorical sub-groups). +# +# This base class considers metadata and results of one similarity grouping +# analysis applied to a set in which objects are either categorized as noise +# or belonging to a cluster. +# As the results of the analysis each similarity group, here called feature +# aka object can get a number of numerical and/or categorical labels. +# +# +# +# Number of members in the set which is partitioned into features. +# +# +# +# +# How many numerical labels does each feature have. +# +# +# +# +# How many categorical labels does each feature have. +# +# +# +# +# +# Which identifier is the first to be used to label a cluster. +# +# The value should be chosen in such a way that special values can be resolved: +# * identifier_offset-1 indicates an object belongs to no cluster. +# * identifier_offset-2 indicates an object belongs to the noise category. +# Setting for instance identifier_offset to 1 recovers the commonly used +# case that objects of the noise category get values to -1 and unassigned points to 0. +# Numerical identifier have to be strictly increasing. +# +# +# +# +# +# +# +# Matrix of numerical label for each member in the set. +# For classical clustering algorithms this can for instance +# encode the cluster_identifier. +# +# +# +# +# +# +# +# +# Matrix of categorical attribute data for each member in the set. +# +# +# +# +# +# +# +# +# +# In addition to the detailed storage which members was grouped to which +# feature/group summary statistics are stored under this group. +# +# +# +# +# Total number of members in the set which are categorized as unassigned. +# +# +# +# +# +# +# +# Total number of members in the set which are categorized as noise. +# +# +# +# +# +# +# +# +# Total number of clusters (excluding noise and unassigned). +# +# +# +# +# Array of numerical identifier of each feature (cluster). +# +# +# +# +# +# +# +# +# Array of number of members for each feature. +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsingle_crystal.yaml b/contributed_definitions/nyaml/NXsingle_crystal.yaml new file mode 100644 index 0000000000..c249281bcd --- /dev/null +++ b/contributed_definitions/nyaml/NXsingle_crystal.yaml @@ -0,0 +1,113 @@ +category: base +doc: | + Description of a single crystal material or a single crystalline phase in a material. + + There is the option of using Busing-Levy convention (as orginally designed in NXsample) + or using a more detailed description with NXrotation_set. +type: group +NXsingle_crystal(NXobject): + sample_orientation(NX_FLOAT): + unit: NX_ANGLE + doc: | + This will follow the Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 1 + dim: [[1, 3]] + orientation_matrix(NX_FLOAT): + doc: | + Orientation matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + ub_matrix(NX_FLOAT): + doc: | + UB matrix of single crystal sample using Busing-Levy convention: + W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is + the multiplication of the orientation_matrix, given above, + with the :math:`B` matrix which can be derived from the lattice constants. + dimensions: + rank: 2 + dim: [[1, 3], [2, 3]] + rotation_set(NXrotation_set): + doc: | + Detailed description of single crystal orientation and misorientation. + (NXunit_cell): + doc: | + Unit cell of the single crystal. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ece5215b46fffec7506fe8a5894f26facb19f44a56424615404f4cf3bd2f6334 +# +# +# +# +# +# Description of a single crystal material or a single crystalline phase in a material. +# +# There is the option of using Busing-Levy convention (as orginally designed in NXsample) +# or using a more detailed description with NXrotation_set. +# +# +# +# This will follow the Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# Orientation matrix of single crystal sample using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464 +# +# +# +# +# +# +# +# +# UB matrix of single crystal sample using Busing-Levy convention: +# W. R. Busing and H. A. Levy (1967). Acta Cryst. 22, 457-464. This is +# the multiplication of the orientation_matrix, given above, +# with the :math:`B` matrix which can be derived from the lattice constants. +# +# +# +# +# +# +# +# +# Detailed description of single crystal orientation and misorientation. +# +# +# +# +# Unit cell of the single crystal. +# +# +# diff --git a/contributed_definitions/nyaml/NXslip_system_set.yaml b/contributed_definitions/nyaml/NXslip_system_set.yaml new file mode 100644 index 0000000000..6eb2bdf13e --- /dev/null +++ b/contributed_definitions/nyaml/NXslip_system_set.yaml @@ -0,0 +1,135 @@ +category: base +doc: | + Base class for describing a set of crystallographic slip systems. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n: | + Number of slip systems. +type: group +NXslip_system_set(NXobject): + + # number_of_objects(NX_UINT): + # identifier_offset(NX_UINT): + # identifier(NX_UINT): + lattice_type: + + # doc: Array of lattice types. + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, trigonal, hexagonal, cubic] + + # dimensions: + # rank: 1 + # dim: [[1, n]] + miller_plane(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of Miller indices which describe the crystallographic plane. + dimensions: + rank: 2 + dim: [[1, n], [2, i]] + + # fastest changing dimension needs to be i because for instance for hexagonal hkil is needed + miller_direction(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Array of Miller indices which describe the crystallographic direction. + dimensions: + rank: 2 + dim: [[1, n], [2, i]] + is_specific(NX_BOOLEAN): + unit: NX_UNITLESS + doc: | + For each slip system a marker whether the specified Miller indices + refer to the specific slip system or the set of crystallographic equivalent + slip systems of the respective family of slip systems. + dimensions: + rank: 1 + dim: [[1, n]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# e8cb089ac11808b81d9b8ee99ffc53037c3b26e4ded58f03a4053e327d5e68af +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of slip systems. +# +# +# +# +# Base class for describing a set of crystallographic slip systems. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Array of Miller indices which describe the crystallographic plane. +# +# +# +# +# +# +# +# +# +# Array of Miller indices which describe the crystallographic direction. +# +# +# +# +# +# +# +# +# For each slip system a marker whether the specified Miller indices +# refer to the specific slip system or the set of crystallographic equivalent +# slip systems of the respective family of slip systems. +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsnsevent.yaml b/contributed_definitions/nyaml/NXsnsevent.yaml new file mode 100644 index 0000000000..759031086d --- /dev/null +++ b/contributed_definitions/nyaml/NXsnsevent.yaml @@ -0,0 +1,640 @@ +category: application +doc: | + This is a definition for event data from Spallation Neutron Source (SNS) at ORNL. +type: group +NXsnsevent(NXobject): + (NXentry): + exists: ['min', '1'] + (NXcollection)DASlogs: + doc: | + Details of all logs, both from cvinfo file and from HistoTool (frequency and proton_charge). + (NXlog): + exists: ['min', '1'] + average_value(NX_FLOAT): + average_value_error(NX_FLOAT): + exists: optional + deprecated: | + see https://github.com/nexusformat/definitions/issues/821 + average_value_errors(NX_FLOAT): + description: + duration(NX_FLOAT): + maximum_value(NX_FLOAT): + minimum_value(NX_FLOAT): + time(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nvalue]] + value(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nvalue]] + (NXpositioner): + exists: ['min', '0'] + doc: | + Motor logs from cvinfo file. + average_value(NX_FLOAT): + average_value_error(NX_FLOAT): + exists: optional + deprecated: | + see https://github.com/nexusformat/definitions/issues/821 + average_value_errors(NX_FLOAT): + description: + duration(NX_FLOAT): + maximum_value(NX_FLOAT): + minimum_value(NX_FLOAT): + time(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, numvalue]] + value(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, numvalue]] + (NXnote)SNSHistoTool: + SNSbanking_file_name: + SNSmapping_file_name: + author: + command1: + doc: | + Command string for event2nxl. + date: + description: + version: + (NXdata): + exists: ['min', '1'] + + # for all NXdata/banks + data_x_y(link): + target: /NXentry/NXinstrument/NXdetector/data_x_y + x_pixel_offset(link): + target: /NXentry/NXinstrument/NXdetector/x_pixel_offset + y_pixel_offset(link): + target: /NXentry/NXinstrument/NXdetector/y_pixel_offset + (NXevent_data): + exists: ['min', '1'] + + # for all NXdata/banks + event_index(link): + target: /NXentry/NXinstrument/NXdetector/event_index + event_pixel_id(link): + target: /NXentry/NXinstrument/NXdetector/event_pixel_id + event_time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/event_time_of_flight + pulse_time(link): + target: /NXentry/NXinstrument/NXdetector/pulse_time + collection_identifier: + collection_title: + definition: + doc: | + Official NXDL schema after this file goes to applications. + enumeration: [NXsnsevent] + duration(NX_FLOAT): + unit: NX_TIME + end_time(NX_DATE_TIME): + entry_identifier: + experiment_identifier: + (NXinstrument)instrument: + (NXsource)SNS: + frequency(NX_FLOAT): + unit: NX_FREQUENCY + name: + probe: + type: + SNSdetector_calibration_id: + doc: | + Detector calibration id from DAS. + SNSgeometry_file_name: + + # SNSnxtranslate + SNStranslation_service: + (NXdetector): + exists: ['min', '1'] + + # for all NXdetector/banks + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + data_x_y(NX_UINT): + doc: | + expect ``signal=2 axes="x_pixel_offset,y_pixel_offset``" + + # axes are set in data files + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + event_index(NX_UINT): + dimensions: + rank: 1 + dim: [[1, numpulses]] + event_pixel_id(NX_UINT): + dimensions: + rank: 1 + dim: [[1, numevents]] + event_time_of_flight(NX_FLOAT): + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, numevents]] + (NXgeometry)origin: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + pixel_id(NX_UINT): + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + pulse_time(NX_FLOAT): + unit: NX_TIME + dimensions: + rank: 1 + dim: [[1, numpulses]] + total_counts(NX_UINT): + x_pixel_offset(NX_FLOAT): + axis: 1 + primary: 1 + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, numx]] + y_pixel_offset(NX_FLOAT): + axis: 2 + primary: 1 + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, numy]] + beamline: + (NXdisk_chopper): + exists: ['min', '0'] + distance(NX_FLOAT): + unit: NX_LENGTH + (NXmoderator)moderator: + coupling_material: + distance(NX_FLOAT): + unit: NX_LENGTH + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + type: + name: + (NXaperture): + exists: ['min', '0'] + (NXgeometry)origin: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + x_pixel_offset(NX_FLOAT): + unit: NX_LENGTH + (NXattenuator): + exists: ['min', '0'] + distance(NX_FLOAT): + unit: NX_LENGTH + + # motor links from DASlogs when exist + (NXpolarizer): + exists: ['min', '0'] + + # motor links from DASlogs when exist + (NXcrystal): + exists: ['min', '0'] + (NXgeometry)origin: + description: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + type: + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + (NXmonitor): + exists: ['min', '0'] + data(NX_UINT): + doc: | + expect ``signal=1 axes="time_of_flight"`` + dimensions: + rank: 1 + dim: [[1, numtimechannels]] + distance(NX_FLOAT): + unit: NX_LENGTH + mode: + time_of_flight(NX_FLOAT): + unit: NX_TIME + dimensions: + rank: 1 + dim: [[1, numtimechannels + 1]] + notes: + proton_charge(NX_FLOAT): + unit: NX_CHARGE + raw_frames(NX_INT): + run_number: + (NXsample)sample: + changer_position: + holder: + identifier: + name: + doc: | + Descriptive name of sample + nature: + start_time(NX_DATE_TIME): + title: + total_counts(NX_UINT): + unit: NX_UNITLESS + total_uncounted_counts(NX_UINT): + unit: NX_UNITLESS + (NXuser): + exists: ['min', '1'] + facility_user_id: + name: + role: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d0da2705c1153ff2021e04b4c5abe571adccba0be8c90abb9ff59fdca205ea53 +# +# +# +# +# This is a definition for event data from Spallation Neutron Source (SNS) at ORNL. +# +# +# +# Details of all logs, both from cvinfo file and from HistoTool (frequency and proton_charge). +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Motor logs from cvinfo file. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Command string for event2nxl. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Official NXDL schema after this file goes to applications. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Detector calibration id from DAS. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# expect ``signal=2 axes="x_pixel_offset,y_pixel_offset``" +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# expect ``signal=1 axes="time_of_flight"`` +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsnshisto.yaml b/contributed_definitions/nyaml/NXsnshisto.yaml new file mode 100644 index 0000000000..ba06411749 --- /dev/null +++ b/contributed_definitions/nyaml/NXsnshisto.yaml @@ -0,0 +1,670 @@ +category: application +doc: | + This is a definition for histogram data from Spallation Neutron Source (SNS) at ORNL. +type: group +NXsnshisto(NXobject): + (NXentry): + exists: ['min', '1'] + (NXcollection)DASlogs: + doc: | + Details of all logs, both from cvinfo file and from HistoTool (frequency and proton_charge). + (NXlog): + exists: ['min', '1'] + average_value(NX_FLOAT): + average_value_error(NX_FLOAT): + exists: optional + deprecated: | + see https://github.com/nexusformat/definitions/issues/821 + average_value_errors(NX_FLOAT): + description: + duration(NX_FLOAT): + maximum_value(NX_FLOAT): + minimum_value(NX_FLOAT): + time(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nvalue]] + value(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nvalue]] + (NXpositioner): + exists: ['min', '0'] + doc: | + Motor logs from cvinfo file. + average_value(NX_FLOAT): + average_value_error(NX_FLOAT): + exists: optional + deprecated: | + see https://github.com/nexusformat/definitions/issues/821 + average_value_errors(NX_FLOAT): + description: + duration(NX_FLOAT): + maximum_value(NX_FLOAT): + minimum_value(NX_FLOAT): + time(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, numvalue]] + value(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, numvalue]] + (NXnote)SNSHistoTool: + SNSbanking_file_name: + SNSmapping_file_name: + author: + command1: + doc: | + Command string for event2histo_nxl. + date: + description: + version: + (NXdata): + exists: ['min', '1'] + + # for all NXdata/banks + data(link): + target: /NXentry/NXinstrument/NXdetector/data + data_x_time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/data_x_time_of_flight + data_x_y(link): + target: /NXentry/NXinstrument/NXdetector/data_x_y + data_y_time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/data_y_time_of_flight + pixel_id(link): + target: /NXentry/NXinstrument/NXdetector/pixel_id + time_of_flight(link): + target: /NXentry/NXinstrument/NXdetector/time_of_flight + total_counts(link): + target: /NXentry/NXinstrument/NXdetector/total_counts + x_pixel_offset(link): + target: /NXentry/NXinstrument/NXdetector/x_pixel_offset + y_pixel_offset(link): + target: /NXentry/NXinstrument/NXdetector/y_pixel_offset + collection_identifier: + collection_title: + definition: + doc: | + Official NXDL schema after this file goes to applications. + enumeration: [NXsnshisto] + duration(NX_FLOAT): + unit: NX_TIME + end_time(NX_DATE_TIME): + entry_identifier: + experiment_identifier: + (NXinstrument)instrument: + (NXsource)SNS: + frequency(NX_FLOAT): + unit: NX_FREQUENCY + name: + probe: + type: + SNSdetector_calibration_id: + doc: | + Detector calibration id from DAS. + SNSgeometry_file_name: + + # SNSnxtranslate + SNStranslation_service: + (NXdetector): + exists: ['min', '1'] + + # for all NXdetector/banks + azimuthal_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + data(NX_UINT): + signal: 1 + axes: x_pixel_offset,y_pixel_offset,time_of_flight + dimensions: + rank: 3 + dim: [[1, numx], [2, numy], [3, numtof]] + data_x_time_of_flight(NX_UINT): + signal: 3 + axes: x_pixel_offset,time_of_flight + dimensions: + rank: 2 + dim: [[1, numx], [2, numtof]] + data_x_y(NX_UINT): + signal: 2 + axes: x_pixel_offset,y_pixel_offset + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + data_y_time_of_flight(NX_UINT): + signal: 4 + axes: y_pixel_offset,time_of_flight + dimensions: + rank: 2 + dim: [[1, numy], [2, numtof]] + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + (NXgeometry)origin: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + pixel_id(NX_UINT): + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + polar_angle(NX_FLOAT): + unit: NX_ANGLE + dimensions: + rank: 2 + dim: [[1, numx], [2, numy]] + time_of_flight(NX_FLOAT): + axis: 3 + primary: 1 + unit: NX_TIME_OF_FLIGHT + dimensions: + rank: 1 + dim: [[1, numtof + 1]] + total_counts(NX_UINT): + x_pixel_offset(NX_FLOAT): + axis: 1 + primary: 1 + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, numx]] + y_pixel_offset(NX_FLOAT): + axis: 2 + primary: 1 + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, numy]] + beamline: + (NXdisk_chopper): + exists: ['min', '0'] + doc: | + Original specification called for NXchopper, + which is not a valid NeXus base class. + Select either NXdisk_chopper or NXfermi_chopper, as appropriate. + distance(NX_FLOAT): + unit: NX_LENGTH + (NXfermi_chopper): + exists: ['min', '0'] + doc: | + Original specification called for NXchopper, + which is not a valid NeXus base class. + Select either NXdisk_chopper or NXfermi_chopper, as appropriate. + distance(NX_FLOAT): + unit: NX_LENGTH + (NXmoderator)moderator: + coupling_material: + distance(NX_FLOAT): + unit: NX_LENGTH + temperature(NX_FLOAT): + unit: NX_TEMPERATURE + type: + name: + (NXaperture): + exists: ['min', '0'] + (NXgeometry)origin: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + x_pixel_offset(NX_FLOAT): + unit: NX_LENGTH + (NXattenuator): + exists: ['min', '0'] + distance(NX_FLOAT): + unit: NX_LENGTH + + # motor links from DASlogs when exist + (NXpolarizer): + exists: ['min', '0'] + + # motor links from DASlogs when exist + (NXcrystal): + exists: ['min', '0'] + (NXgeometry)origin: + description: + (NXorientation)orientation: + value(NX_FLOAT): + doc: | + Six out of nine rotation parameters. + dimensions: + rank: 1 + dim: [[1, 6]] + (NXshape)shape: + description: + shape: + size(NX_FLOAT): + unit: NX_LENGTH + (NXtranslation)translation: + distance(NX_FLOAT): + unit: NX_LENGTH + dimensions: + rank: 1 + dim: [[1, 3]] + type: + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + (NXmonitor): + exists: ['min', '0'] + data(NX_UINT): + signal: 1 + axes: time_of_flight + dimensions: + rank: 1 + dim: [[1, numtimechannels]] + distance(NX_FLOAT): + unit: NX_LENGTH + mode: + time_of_flight(NX_FLOAT): + unit: NX_TIME + dimensions: + rank: 1 + dim: [[1, numtimechannels + 1]] + notes: + proton_charge(NX_FLOAT): + unit: NX_CHARGE + raw_frames(NX_INT): + run_number: + (NXsample)sample: + changer_position: + holder: + identifier: + name: + doc: | + Descriptive name of sample + nature: + start_time(NX_DATE_TIME): + title: + total_counts(NX_UINT): + unit: NX_UNITLESS + total_uncounted_counts(NX_UINT): + unit: NX_UNITLESS + (NXuser): + exists: ['min', '1'] + facility_user_id: + name: + role: + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# aeae16f4bdba7aa9f6f48be75c35f0024eec1adb3900b632d04b4abb50670053 +# +# +# +# +# This is a definition for histogram data from Spallation Neutron Source (SNS) at ORNL. +# +# +# +# Details of all logs, both from cvinfo file and from HistoTool (frequency and proton_charge). +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Motor logs from cvinfo file. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Command string for event2histo_nxl. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Official NXDL schema after this file goes to applications. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Detector calibration id from DAS. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Original specification called for NXchopper, +# which is not a valid NeXus base class. +# Select either NXdisk_chopper or NXfermi_chopper, as appropriate. +# +# +# +# +# +# Original specification called for NXchopper, +# which is not a valid NeXus base class. +# Select either NXdisk_chopper or NXfermi_chopper, as appropriate. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Six out of nine rotation parameters. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# Descriptive name of sample +# +# +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsolenoid_magnet.yaml b/contributed_definitions/nyaml/NXsolenoid_magnet.yaml new file mode 100644 index 0000000000..ae5f355fa5 --- /dev/null +++ b/contributed_definitions/nyaml/NXsolenoid_magnet.yaml @@ -0,0 +1,84 @@ +category: base +doc: | + definition for a solenoid magnet. +type: group +NXsolenoid_magnet(NXobject): + description(NX_CHAR): + doc: | + extended description of the magnet. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + set_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on supply. + read_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from supply. + value: + unit: NX_CURRENT + read_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1364b1b892354a667957c67d8d4d7b6ebb5f1a1bd7fc2dc5876622ed45239995 +# +# +# +# +# definition for a solenoid magnet. +# +# extended description of the magnet. +# +# +# define position of beamline element relative to production target +# +# +# current set on supply. +# +# +# current read from supply. +# +# +# +# voltage read from supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXsolid_geometry.yaml b/contributed_definitions/nyaml/NXsolid_geometry.yaml new file mode 100644 index 0000000000..3d752e4626 --- /dev/null +++ b/contributed_definitions/nyaml/NXsolid_geometry.yaml @@ -0,0 +1,76 @@ +category: base +doc: | + the head node for constructively defined geometry +type: group +NXsolid_geometry(NXobject): + (NXquadric): + exists: ['min', '0'] + doc: | + Instances of :ref:`NXquadric` making up elements of the geometry. + (NXoff_geometry): + exists: ['min', '0'] + doc: | + Instances of :ref:`NXoff_geometry` making up elements of the geometry. + (NXcsg): + exists: ['min', '0'] + doc: | + The geometries defined, made up of instances of :ref:`NXquadric` and :ref:`NXoff_geometry`. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 71a1b3ca39b88fdae9499a10284ddc6fd89423b5d2e3e1d544bacfa3793bb5c0 +# +# +# +# +# +# the head node for constructively defined geometry +# +# +# +# Instances of :ref:`NXquadric` making up elements of the geometry. +# +# +# +# +# Instances of :ref:`NXoff_geometry` making up elements of the geometry. +# +# +# +# +# The geometries defined, made up of instances of :ref:`NXquadric` and :ref:`NXoff_geometry`. +# +# +# diff --git a/contributed_definitions/nyaml/NXspatial_filter.yaml b/contributed_definitions/nyaml/NXspatial_filter.yaml new file mode 100644 index 0000000000..f78214d27f --- /dev/null +++ b/contributed_definitions/nyaml/NXspatial_filter.yaml @@ -0,0 +1,134 @@ +category: base +doc: | + Spatial filter to filter entries within a region-of-interest based on their + position. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ellipsoids: | + Number of ellipsoids. + n_hexahedra: | + Number of hexahedra. + n_cylinders: | + Number of cylinders. + +# n_polyhedra: Number of polyhedra. +# n_vertices: Number of vertices for polyhedra. +# n_facets: Number of facets for polyhedra. +type: group +NXspatial_filter(NXobject): + windowing_method: + doc: | + Qualitative statement which specifies which spatial filtering with respective + geometric primitives or bitmask is used. These settings are possible: + + * entire_dataset, no filter is applied, the entire dataset is used. + * union_of_primitives, a filter with (rotated) geometric primitives. + All ions in or on the surface of the primitives are considered + while all other ions are ignored. + * bitmasked_points, a boolean array whose bits encode with 1 + which ions should be included. Those ions whose bit is set to 0 + will be excluded. Users of python can use the bitfield operations + of the numpy package to define such bitfields. + + Conditions: + In the case that windowing_method is entire_dataset all entries are processed. + In the case that windowing_method is union_of_primitives, + it is possible to specify none or all types of primitives + (ellipsoids, cylinder, hexahedra). If no primitives are specified + the filter falls back to entire_dataset. + In the case that windowing_method is bitmask, the bitmask has to be defined; + otherwise the filter falls back to entire dataset. + enumeration: [entire_dataset, union_of_primitives, bitmask] + (NXcg_ellipsoid_set): + (NXcg_cylinder_set): + (NXcg_hexahedron_set): + (NXcs_filter_boolean_mask): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 791b662f16e375b77792d796be1d1f955b3d65c46016e3ecde10353845d23079 +# +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Number of ellipsoids. +# +# +# +# +# Number of hexahedra. +# +# +# +# +# Number of cylinders. +# +# +# +# +# Spatial filter to filter entries within a region-of-interest based on their +# position. +# +# +# +# Qualitative statement which specifies which spatial filtering with respective +# geometric primitives or bitmask is used. These settings are possible: +# +# * entire_dataset, no filter is applied, the entire dataset is used. +# * union_of_primitives, a filter with (rotated) geometric primitives. +# All ions in or on the surface of the primitives are considered +# while all other ions are ignored. +# * bitmasked_points, a boolean array whose bits encode with 1 +# which ions should be included. Those ions whose bit is set to 0 +# will be excluded. Users of python can use the bitfield operations +# of the numpy package to define such bitfields. +# +# Conditions: +# In the case that windowing_method is entire_dataset all entries are processed. +# In the case that windowing_method is union_of_primitives, +# it is possible to specify none or all types of primitives +# (ellipsoids, cylinder, hexahedra). If no primitives are specified +# the filter falls back to entire_dataset. +# In the case that windowing_method is bitmask, the bitmask has to be defined; +# otherwise the filter falls back to entire dataset. +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXspectrum_set.yaml b/contributed_definitions/nyaml/NXspectrum_set.yaml new file mode 100644 index 0000000000..5cbc597b61 --- /dev/null +++ b/contributed_definitions/nyaml/NXspectrum_set.yaml @@ -0,0 +1,143 @@ +category: base +doc: | + Base class container for reporting a set of spectra. +symbols: + n_p: | + Number of scan points. + n_y: | + Number of pixel in the slow direction. + n_x: | + Number of pixel in the fast direction. + n_energy: | + Number of energy bins. +type: group +NXspectrum_set(NXobject): + # for EELS we likely need a complex-valued NXspectrum_c_set to this + # NXspectrum_set base class here which should then be splitted into an + # NXspectrum_set to reduce redundant fields and specialized NXspectrum_r/c_set + (NXprocess): + doc: | + Details how spectra were processed from the detector readings. + source(NXserialized): + doc: | + Resolvable data artifact (e.g. filename) from which the all values in + the :ref:`NXdata` instances in this :ref:`NXspectrum_set` were + loaded during parsing. + mode(NX_CHAR): + doc: | + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXspectrum_set` instance. + detector_identifier(NX_CHAR): + doc: | + Link or name of an :ref:`NXdetector` instance with which the data were collected. + (NXprogram): + ##MK::feel free to contact us when you would like to include + # lik omega/q mapping more complicated scan pattern than rectangular ones. + stack(NXdata): + doc: | + Collected spectra for all pixels of a rectangular region-of-interest. + + This representation supports rectangular scan pattern with equidistant + energy bins. For randomly or dissimilarly spaced scan points + use collection instead. + intensity(NX_NUMBER): + doc: | + Counts + unit: NX_UNITLESS + dim: (n_y, n_x, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + # \@signal: counts + # \@axes: [ypos, xpos, energy] + # \@ypos_indices: 0 + # \@xpos_indices: 1 + # \@energy_indices: 2 + axis_y(NX_NUMBER): + doc: | + Coordinate along y direction. + unit: NX_LENGTH + dim: (n_y,) + \@long_name(NX_CHAR): + doc: | + Pixel coordinate along y direction + axis_x(NX_NUMBER): + doc: | + Coordinate along x direction. + unit: NX_LENGTH + dim: (n_x,) + \@long_name(NX_CHAR): + doc: | + Pixel coordinate along x direction + axis_energy(NX_NUMBER): + doc: | + Energy axis + unit: NX_ENERGY + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + + # in the majority of cases rectangular or line scans are performed + # if there is interest to support arbitrary scan pattern one should use + # scan points and contact us to generalize this base class and related + # base classes + summary(NXdata): + doc: | + Accumulated counts over all pixels of the region-of-interest. + This representation supports a rectangular scan pattern with + equidistant energy bins. + intensity(NX_NUMBER): + doc: | + Accumulated counts + unit: NX_UNITLESS + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Counts + # \@signal: counts + # \@axes: [energy] + # \@energy_indices: 0 + axis_energy(NX_NUMBER): + doc: | + Energy axis + unit: NX_ENERGY + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + + collection(NXdata): + doc: | + Collected spectra for each scan point. + + This representation supports equidistant energy bins. + For rectangular sampling use stack and summary instead. + intensity(NX_NUMBER): + doc: | + Counts + unit: NX_UNITLESS + dim: (n_p, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + # \@signal: counts + # \@axes: [scan_point_id, energy] + # \@scan_point_indices: 1 + # \@energy_indices: 0 + axis_scan_point_id(NX_INT): + doc: | + Scan point identifier + unit: NX_UNITLESS + dim: (n_p,) + \@long_name(NX_CHAR): + doc: | + Scan point identifier + axis_energy(NX_NUMBER): + doc: | + Energy axis + unit: NX_ENERGY + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy diff --git a/contributed_definitions/nyaml/NXspin_rotator.yaml b/contributed_definitions/nyaml/NXspin_rotator.yaml new file mode 100644 index 0000000000..8cdf66348c --- /dev/null +++ b/contributed_definitions/nyaml/NXspin_rotator.yaml @@ -0,0 +1,108 @@ +category: base +doc: | + definition for a spin rotator. +type: group +NXspin_rotator(NXobject): + description(NX_CHAR): + doc: | + extended description of the spin rotator. + beamline_distance(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + define position of beamline element relative to production target + set_Bfield_current(NX_FLOAT): + unit: NX_CURRENT + exists: ['min', '0', 'max', '1'] + doc: | + current set on magnet supply. + read_Bfield_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from magnet supply. + value: + unit: NX_CURRENT + read_Bfield_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from magnet supply. + value: + unit: NX_VOLTAGE + set_Efield_voltage(NX_FLOAT): + unit: NX_VOLTAGE + exists: ['min', '0', 'max', '1'] + doc: | + current set on HT supply. + read_Efield_current(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + current read from HT supply. + value: + unit: NX_CURRENT + read_Efield_voltage(NXlog): + exists: ['min', '0', 'max', '1'] + doc: | + voltage read from HT supply. + value: + unit: NX_VOLTAGE + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 260f697bca7fcdb6e806e85e0cb1459de350eab0f1eb633c5b15ac31d38c1572 +# +# +# +# +# definition for a spin rotator. +# +# extended description of the spin rotator. +# +# +# define position of beamline element relative to production target +# +# +# current set on magnet supply. +# +# +# current read from magnet supply. +# +# +# +# voltage read from magnet supply. +# +# +# +# current set on HT supply. +# +# +# current read from HT supply. +# +# +# +# voltage read from HT supply. +# +# +# diff --git a/contributed_definitions/nyaml/NXspindispersion.yaml b/contributed_definitions/nyaml/NXspindispersion.yaml new file mode 100644 index 0000000000..7b37920b94 --- /dev/null +++ b/contributed_definitions/nyaml/NXspindispersion.yaml @@ -0,0 +1,154 @@ +category: base +doc: | + Subclass of NXelectronanalyser to describe the spin filters in photoemission + experiments. +type: group +NXspindispersion(NXobject): + type(NX_CHAR): + doc: | + Type of spin detector, VLEED, SPLEED, Mott, etc. + figure_of_merit(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Figure of merit of the spin detector + shermann_function(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Effective Shermann function, calibrated spin selectivity factor + scattering_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Energy of the spin-selective scattering + scattering_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Angle of the spin-selective scattering + target(NX_CHAR): + doc: | + Name of the target + target_preparation(NX_CHAR): + doc: | + Preparation procedure of the spin target + target_preparation_date(NX_DATE_TIME): + doc: | + Date of last preparation of the spin target + depends_on(NX_CHAR): + doc: | + Specifies the position of the lens by pointing to the last transformation in the + transformation chain in the NXtransformations group. + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the location and + geometry of the deflector as a component in the instrument. Conventions from the + NXtransformations base class are used. In principle, the McStas coordinate + system is used. The first transformation has to point either to another + component of the system or . (for pointing to the reference frame) to relate it + relative to the experimental setup. Typically, the components of a system should + all be related relative to each other and only one component should relate to + the reference coordinate system. + (NXdeflector): + doc: | + Deflectors in the spin dispersive section + (NXlens_em): + doc: | + Individual lenses in the spin dispersive section + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 5f68e83a10b4fa836b7ab5fafa790e5d55657315050706de79f99356f2b01872 +# +# +# +# +# +# Subclass of NXelectronanalyser to describe the spin filters in photoemission +# experiments. +# +# +# +# Type of spin detector, VLEED, SPLEED, Mott, etc. +# +# +# +# +# Figure of merit of the spin detector +# +# +# +# +# Effective Shermann function, calibrated spin selectivity factor +# +# +# +# +# Energy of the spin-selective scattering +# +# +# +# +# Angle of the spin-selective scattering +# +# +# +# +# Name of the target +# +# +# +# +# Preparation procedure of the spin target +# +# +# +# +# Date of last preparation of the spin target +# +# +# +# +# Specifies the position of the lens by pointing to the last transformation in the +# transformation chain in the NXtransformations group. +# +# +# +# +# Collection of axis-based translations and rotations to describe the location and +# geometry of the deflector as a component in the instrument. Conventions from the +# NXtransformations base class are used. In principle, the McStas coordinate +# system is used. The first transformation has to point either to another +# component of the system or . (for pointing to the reference frame) to relate it +# relative to the experimental setup. Typically, the components of a system should +# all be related relative to each other and only one component should relate to +# the reference coordinate system. +# +# +# +# +# Deflectors in the spin dispersive section +# +# +# +# +# Individual lenses in the spin dispersive section +# +# +# diff --git a/contributed_definitions/nyaml/NXstage_lab.yaml b/contributed_definitions/nyaml/NXstage_lab.yaml new file mode 100644 index 0000000000..a79ef91524 --- /dev/null +++ b/contributed_definitions/nyaml/NXstage_lab.yaml @@ -0,0 +1,138 @@ +category: base +doc: | + Base class for a stage (lab) used to hold, orient, and prepare a specimen. + + Modern stages are multi-functional devices. Stages provide a controlled + environment around the specimen. Stages enable experimentalists to apply + controlled external stimuli on the specimen. A stage_lab is a multi-purpose + /-functional tool that is constructed from multiple actuators, sensors, + and other components. + + With such stages comes the need for storing various (meta)data + that are generated while working and modifying the sample. + + Modern stages realize a hierarchy of components. Two examples are given to help + clarify how :ref:`NXstage_lab` instances should be used: Take a specimen that is + mounted on a multi-axial tilt rotation holder. This holder is fixed in the + support unit which connects the holder to the rest of the instrument. + Evidently different components are all considerable as to represent instances + of stages. + + In another example, taken from atom probe microscopy, researchers may work + with wire samples which are clipped into a larger fixing unit to enable + careful specimen handling. Alternatively, a microtip is a silicon post + upon which e.g. an atom probe specimen is mounted. + Multiple microtips are grouped into a microtip array to conveniently enable + loading of multiple specimens into the instrument with fewer operations. + That microtip array is fixed on a holder. Fixture units in atom probe are known + as stubs. Stubs in turn are positioned onto pucks. Pucks are then loaded onto + carousels. A carousel is a carrier unit with which eventually entire sets of + specimens can be moved in between parts of the microscope. All of these units + can be considered stage_lab instances. + + The :ref:`NXstage_lab` base class reflects this hierarchy. To cover for an as flexible + design of complex stages as possible, users should nest multiple instances of + :ref:`NXstage_lab` according to their needs to reflect the differences between what + they consider as the holder and what they consider is the stage. + The alias field can be used to specify the community jargon if necessary. + + However, a much clearer approach to reflect the hierarchy of all :ref:`NXstage_lab` + instances is postfix each instance named stage_lab with integers starting + from 1 as the top level unit. + In the microtip example one could thus use stage_lab1 for the microtip, + stage_lab2 for the microtip array, stage_lab3 holder, etc. + The depends_on keyword should be used to additional clarify the hierarchy + especially when users decide to not follow the above-mentioned postfixing + notation or when is not obvious from the postfixes which stage_lab is at + which level of the stage_lab hierarchy. + + Some examples for stage_labs in applications: + + * A nanoparticle on a copper grid. The copper grid is the holder. + The grid itself is fixed to a stage. + * An atom probe specimen fixed in a stub. In this case the stub can be + considered the holder, while the cryostat temperature control unit is + a component of the stage. + * Samples with arrays of specimens, like a microtip on a microtip array + is an example of an at least three-layer hierarchy commonly employed for + efficient sequential processing of atom probe experiments. + * With one entry of an application definition only one microtip should be + described. Therefore, the microtip is the specimen, + the array is the holder and the remaining mounting unit + that is attached to the cryo-controller is the stage. + * For in-situ experiments with e.g. chips with read-out electronics + as actuators, the chips are again placed in a larger unit. A typical + example are in-situ experiments using e.g. the tools of `Protochips `_. + * Other examples are (quasi) in-situ experiments where experimentalists + anneal or deform the specimen via e.g. in-situ tensile testing machines + which are mounted on the specimen holder. + + For specific details and inspiration about stages in electron microscopes: + + * `Holders with multiple axes `_ + * `Chip-based designs `_ + * `Further chip-based designs `_ + * `Stages in transmission electron microscopy `_ (page 103, table 4.2) + * `Further stages in transmission electron microscopy `_ (page 124ff) + * `Specimens in atom probe `_ (page 47ff) + * `Exemplar micro-manipulators `_ + + We are looking forward to suggestions from the scientists. +type: group +NXstage_lab(NXcomponent_em): + design(NX_CHAR): + doc: | + Principal design of the stage. + + Exemplar terms could be side_entry, top_entry, + single_tilt, quick_change, multiple_specimen, + bulk_specimen, double_tilt, tilt_rotate, + heating_chip, atmosphere_chip, + electrical_biasing_chip, liquid_cell_chip + alias(NX_CHAR): + doc: | + Free-text field to give a term how that a stage_lab at this level of the + stage_lab hierarchy is commonly referred to. Examples could be stub, + puck, carousel, microtip, clip, holder, etc. + tilt_1(NX_NUMBER): + doc: | + The interpretation of this tilt should be specialized + and thus detailed via the application definition. + unit: NX_ANGLE + tilt_2(NX_NUMBER): + doc: | + The interpretation of this tilt should be specialized + and thus detailed via the application definition. + unit: NX_ANGLE + rotation(NX_NUMBER): + doc: | + The interpretation of this tilt should be specialized + and thus detailed via the application definition. + unit: NX_ANGLE + position(NX_NUMBER): + doc: | + The interpretation of this tilt should be specialized + and thus detailed via the application definition. + unit: NX_LENGTH + dim: (3,) + bias_voltage(NX_NUMBER): + doc: | + Voltage applied to the stage to decelerate electrons. + unit: NX_VOLTAGE + # NEW ISSUE: rather the field if possible should be specified + (NXpositioner): + + # see for complicated positioning tools like an eucentric five-axis table stage in an SEM + # https://www.nanotechnik.com/e5as.html + # shipswing_tilt(NXpositioner): + # normal_rotate(NXpositioner): + # normal_height(NXpositioner): + # inplane_translate1(NXpositioner): + # inplane_translate2(NXpositioner): + # NEW ISSUE: add temperature control units and components to apply external stimuli + # NEW ISSUE: on the specimen such as NXmech_testing_unit and NXfurnace, NXreaction_cell + # NEW ISSUE: by contrast, the purpose and design of so-called nano/or micromanipulators, + # i.e. automatable devices to perform e.g. site-specific lift out, procedures warrants + # to define an own class NXspecimen_manipulator given this is nothing else than + # miniature robot arm essential one could also think about creating an own NXrobotarm class, + # below are two examples of such tools as they are used in FIB and SEMs diff --git a/contributed_definitions/nyaml/NXsts.yaml b/contributed_definitions/nyaml/NXsts.yaml new file mode 100644 index 0000000000..03e16760e9 --- /dev/null +++ b/contributed_definitions/nyaml/NXsts.yaml @@ -0,0 +1,1747 @@ +category: application +doc: | + Application definition for temperature-dependent IV curve measurements + #2023.19.7 This Nexus file is currently only for STS data, it will be updated to handle the + STM image mode in the future with a focus on bias spectroscopy in Scanning Tunneling Microscopy. + + In this application definition, times should be specified always together with a UTC offset. + + This is the application definition describing temperature (T) dependent current voltage (IV) curve + measurements. For this, a temperature is set. After reaching the temperature, a voltage sweep + is performed. For each voltage, a current is measured. + Then, the next desired temperature is set and an IV measurement is performed. + The data can be visualized in a tensor with: + I (NXsensor_C, NXsoftware_Read_offset, NXcircuit) + parameters: + V has (NXsource+offset, NXsoftware_Scan_offset, NXsensor_V, NXcircuit) + T has (NXsource, NXsoftware_Scan_offset, NXsensor_T) + x has (NXsoftware_Scan_offset) + y has (NXsoftware_Scan_offset) + z has (NXsoftware_Scan_offset) + +# 2023.19.7 This Nexus file is currently only for STS data, it will be updated to handle the +type: group +NXsts(NXsensor_scan): + (NXentry): + definition: + enumeration: [NXsts] + experiment_type: + doc: | + Name of the experiment where the application is applicable. + enumeration: [sts, stm] + type: + doc: | + The equipments and techniques as well as the parameter settings and reference signals + are used during the experiments used in Scanning Tunneling Microscopy (STM). + + # NOTE_: What does the enum refer, scan could be forward or backward. (not in data file) + # What is about [constant current mode, constant height mode] + enumeration: [background, reference, sample] + entry_identifier: + exists: optional + doc: | + The name of the output file, with the number of scans at the end. (e.g. + 221122_Au_5K00014) + collection_identifier: + doc: | + The name of the series output file, which represents only the public part of the + output file. (e.g. 221122_Au_5K) + experiment_identifier: + exists: optional + doc: | + Path to storage of output files. + (e.g. Path C:\Users\SPM-PEEM\Desktop\DATA_Nanonis\20220711_CreaTec_Service_Benchmarks_LHe\Nanonis-Session-PMD100-HVHU_CreaTec_Service_PalmaLabBerlin220711) + experiment_description: + exists: optional + doc: | + Descriptive comments for this experiment, added by the experimenter, coming from the + output file. (e.g. Comment01 SYNC & Filter LP 8order WITHDRAW 600 steps, locked Au(111), + 50pA, 100 mV set point, 1mV DCA, 973Hz,138 1st H, -84 2nd H) + (NXinstrument): + hardware(NXfabrication): + exists: optional + doc: | + Hardware type used in SPM experiment, includes hardware manufacturers and type. + (e.g. Nanonis BP5e) + + # hardware: Current amplifier> hardware: CreaTec GmbH + # any or specifique 'harware' and 'software'? + software(NXfabrication): + exists: optional + doc: | + Type of software used in SPM experiments, such as software version serial number, UI and + RT probe release method. (e.g. SW Version Generic 5e -- RT Release 10771) + version: + exists: optional + doc: | + Version of the software. + + # amplification: Current amplifier> factor (V/V): 1E-10 + # crosstalk_compensation: Current amplifier> Capacitive cross-talk compensation: Yes/No + current_amplifier(NXamplifier): + exists: optional + doc: | + The Amplifier description that improves or helps to determine tunnel current (current + between tip and bias). + lock_in(NXlockin): + exists: optional + status: + exists: optional + + # status: Lock-in>Lock-in status ON # ON/OFF of Lock-in amplifier + doc: | + Status of Lock-in device whether while performing the experiment + + # amplifier_status: -> amplifier/active_channels + # Lock-in Amplifier>Yes/No + # doc: Lock-in Amplifier>Yes/No # If a lock-in amplifier employed to filter or obtain + # the electronic derivatives dI/dV of the signal + # hardware: Lock-in Amplifier>Hardware: Nanonis + modulation_signal: + exists: optional + unit: NX_VOLTAGE + doc: | + This is the signal on which the modulation (sine) will be added. + + # modulate_signal: Lock-in>Modulated signal Bias (V) + modulation_frequency(NX_NUMBER): + unit: NX_FREQUENCY + + # Lock-in>Frequency (Hz) 973E+0 + doc: | + The signal is modulated by adding the frequency of the sine modulation. The + modulation frequency spans can be from 10 mHz to 40 kHz, corresponding to the output filter + cut-off range. When dealing with harmonics, it's essential to ensure that the + harmonic frequencies remain below ~100 kHz, which aligns with the input filter cut-off. + Be mindful that hardware filters might impact the amplitude as the signal approaches + their cut-off frequencies." (e.g. 973E+0) + modulation_amplitude(NX_NUMBER): + + # amplitude: Lock-in>Amplitude 2E-3 + doc: | + The amplitude (in physical units of modulated signal) of the sine modulation. + demodulated_signal: + exists: optional + + # Lock-in>Demodulated signal Current (A) # This is the signal which + # will be demodulated, in order to determine the amplitude and phase at the frequency + # set in the Frequency field (“4”) or harmonics. + doc: | + The input signal (STS signal) will be demodulated, in order to determine the amplitude + and phase at the frequency set in the Frequency field or harmonics, such as current, + bias, et.al. + harmonic_order_N(NX_NUMBER): + + # Lock-in>Harmonic D1 1 + # Lock-in>Harmonic D2 2 # See below. + doc: | + N denotes 1 or 2. The order of the harmonic oscillation to be detected in the demodulated + signal should be considered relative to the modulation frequency. When dealing with + higher harmonics, it's essential to ensure that their frequencies do not surpass + the analogue signal bandwidth (e.g. harmonic_order_1). + ref_phase_N(NX_NUMBER): + exists: optional + + # Lock-in>Reference phase D1 (deg) 137.597E+0 + # Lock-in>Reference phase D2 (deg) -83.6562E+0 # See below. + doc: | + Reference phase for the sine on the demodulated signal with respect to the + modulation signal. The determined phase is displayed with respect to the + reference phase. + lock_in_data_flip_number(NX_NUMBER): + + # items below should go to bias/spectroscopy/...!!! + # recorded_channels: + # doc: Select the channels to record. (e.g. Current (A);LI Demod 2 X (A);LI Demod 2 Y (A); + # LI Demod 1 X (A);LI Demod 1 Y (A) # Select the channels to record.) + # bias_reset: + # doc: When selected, the Bias voltage returns to the initial value (before starting the + # sweep) at the end of the spectroscopy measurement (default). When not selected, Bias + # remains at the last value of the sweep. This is useful e.g. when combining several + # sweep segments. Example for an automated measurement (using Programming Interface): + # switch off Z-Controller, start spectroscopy sweep segments (only fwd sweep, no reset + # bias), set bias back to initial value, switch on Z-Controller. (e.g. TRUE) + # record_final_z: + # doc: Select whether to record the Z position during Z averaging time at the end of the + # sweep (after Z control time) and store the average value in the header of the file + # when saving. Using this option increases the sweep time by Z averaging time. (e.g. FALSE) + # run: + # doc: Bias Spectroscopy>Lock-In run FALSE # Select whether to set the Lock-In to run + # during the measurement. When using this feature, make sure the Lock-In is configured + # correctly and settling times are set to twice the Lock-In period at least. This + # option is ignored when Lock-In is already running. This option is disabled if the + # Sweep Mode is MLS and the flag to configure the Lock-In per segment in the Multiline + # segment editor is set. + sample_bias(NXiv_bias): + bias(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Applied a voltage between tip and sample. + bias_calibration(NX_NUMBER): + bias_offset(NX_NUMBER): + unit: NX_VOLTAGE + + # sample_bias(NXbias): + # Tip bias/Sample bias If the spectroscopy V bias is applied to the + # Modulated signal Bias (V) 1E-3 Applied modulation to the bias voltage. + # ModulationBias> Tip bias/Sample bias + # modulated_signal_bias(NX_NUMBER): + # unit: NX_VOLTAGE + # doc: Same directional representation as bias. (e.g. 1E-3) + stm_head_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Temperature of STM head. Note: At least one field from stm_head_temperature, + cryo_bottom_temp and cryo_sheild_temp must be provided. + cryo_bottom_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Temperature of liquid helium cryostat. Note: At least one field from + stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp must be provided. + cryo_shield_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Temperature of liquid nitrogen shield. Temperature 3 (K) (e.g 78.00000E+0). Note: At + least one field from stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp + must be provided. + output_cabling(NXcircuit): + exists: optional + + # Cabling & Config + # output_mode: + # doc: Number of output channels. (e.g. User Output) + # output_value(NX_NUMBER): + # doc: The user output in each monitor mode. (e.g. 0E+0) + # output_name: + # doc: User outputs whose name can be modified in the corresponding module. (e.g. Input 24 (V)) + # output_slew_rate(NX_NUMBER): + # doc: The rate at which the one of the signal changes when ramping to the starting point. (V/s) (e.g. Inf) + piezo_config(NXcollection): + exists: optional + doc: | + Configuration for piezoelectric scanner used to move tip along X and Y direction. The + material of the Piezoelectric scanner composed of polycrystalline solids and sensitive to + applied voltage. + active_calib: + doc: | + The name of calibration type. (e.g. LHe) + calib_N(NX_NUMBER): + exists: optional + doc: | + N denotes X or Y or Z. There are three parameters in the X, Y, and Z directions, + along with three available controls: Calibration (m/V), Range (m), and HV gain. Only + two of these parameters are required to define the calibration. Consequently, when any + value is changed, one of the other values will be automatically updated. (e.g. calib_X = 3.8E-9) + hv_gain_N(NX_NUMBER): + exists: optional + doc: | + N denotes X or Y or Z. In some systems, there is an HV gain readout feature. For + these systems, the HV gain should be automatically adjusted whenever the gain is + changed at the high voltage amplifier. (e.g. 14.5) + + # (e.g. 0.318343) + tilt_N(NX_NUMBER): + exists: optional + unit: NX_ANGLE + doc: | + N denotes X or Y. There are 2 parameters in X and Y directions, and tilt needs to be + adjusted according to the actual surface. (in degrees, first order correction). + + # Inf + curvature_radius_N(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + N denotes X or Y. There are 2 parameters in X and Y directions. (can be set + approximately to the length of the piezotube). + 2nd_order_corr_N(NX_NUMBER): + exists: optional + doc: | + N denotes X or Y. There are 2 parameters in X and Y directions. If you know them, + you can enter the 2nd order piezo characteristics to compensate for it. The + following equation shows the interpretation of the 2nd order correction parameter: + For the X-piezo: "Ux = 1/cx · X + cxx · X2" with units: + [V] = [V/m] · [m] + [V/m2] · [m2] where cx is the calibration of the piezo X and cxx + is the 2nd order correction. (V/m^2). (e.g. 0E+0) + drift_N(NX_NUMBER): + exists: optional + doc: | + N denotes X, Y or Z. There are 3 parameters in X, Y and Z directions. Define the + drift speed for all three axes. When the compensation is on, the piezos will start to + move at that speed. (e.g. 0E+0) + drift_correction_status(NX_BOOLEAN): + doc: | + Use the button to enable or disable the drift compensation. (e.g. FALSE) + (NXenvironment): + exists: optional + doc: | + Describes an environment setup for a temperature-dependent IV measurement experiment. + The temperature and voltage must be present as independently scanned controllers and + the current sensor must also be present with its readings. + current_sensor(NXsensor): + exists: optional + current(NX_NUMBER): + unit: NX_CURRENT + doc: | + This is set-point of tip current (in the constant current mode should be equal to set-point, + in the constant height mode means the real tunnelling current between tip and sample). + current_calibration(NX_NUMBER): + unit: NX_CURRENT + doc: | + Value of calibration that comes as A/V. + current_offset(NX_NUMBER): + unit: NX_CURRENT + current_gain: + unit: NX_UNITLESS + calibration_time(NX_DATE_TIME): + exists: optional + value(NX_NUMBER): + exists: optional + position(NXpositioner_sts): + doc: | + Clarify the frame laboratory frame. + x(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + The scanning area in x position in the frame. (e.g. -890.53E-12) + y(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + The scanning area in y position in the frame. (e.g. 29.6968E-9) + z(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + The scanning area in z position in the frame. (e.g. 130.5E-9) + z_controller(NXcollection): + z(NX_NUMBER): + unit: NX_LENGTH + doc: | + Indicate the relative tip position z between tip and sample. The tip position can also + be varied when the z_controller is not running. (e.g. 130.5E-9) + + # TODO: Is if this are uncomment than getting error. + # voltage_controller(NXsensor): + # temperature_controller(NXsensor): + # parameters for a measurement at a single location during the scan + sweep_control(NXcollection): + bias_spectroscopy(NXbias_spectroscopy): + exists: optional + integration_time(NX_NUMBER): + unit: NX_TIME + doc: | + Time during which the spectroscopy data are acquired and averaged. (e.g. 150E-6) + number_of_sweeps(NX_NUMBER): + doc: | + Number of sweeps to measure and average. (e.g. 100) + sweep_start(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The start bias values of the sweep. (e.g. -300E-3) + sweep_end(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + The end bias values of the sweep. (e.g. 300E-3) + num_pixel(NX_NUMBER): + doc: | + The sweep number of points is defined as the maximum spectrum resolution, which + is equal to the bias sweep window divided by the number of pixels. (e.g. 4096) + z_avg_time(NX_NUMBER): + unit: NX_TIME + doc: | + The Z position is recorded and averaged for a certain duration both before and + after the sweep. After the initial Z averaging time, if "Z-Controller to Hold" + is selected, the Z-Controller is set to hold mode, and the tip is positioned at + the previously averaged Z position (adjusted by the Z offset). (e.g. 100E-3) + circuit(NXcollection): + exists: optional + rt_frequency(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + The bandwidth of the Hardware and/or Software is instrument specific. + For example, Nanonis Generic 5 has 'RT Frequency' (e.g. 20E+3). + signals_oversampling(NX_NUMBER): + doc: | + The Signals Period represents the rate at which signals are transferred to + the host computer, which operates the control software. This rate may + be 10 times lower than the sampling rate, as the real-time engine internally + oversamples the signal. If desired, you may have the option to reduce the oversampling + to 1, enabling higher frequency resolution in the Spectrum Analyzer. (e.g. 10) + acquisition_period(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + The update rate is utilized in various processes, including the History Graph, + Auto-Approach, and multiple Programming Interface functions. It may be + configured to a 20 ms interval. Any additional timings must strictly be integer + multiples of this base value. While it is possible to set these additional + timings to different values, the actual timing value will automatically be + adjusted to become a multiple of the Acquisition Period. (e.g. 20E-3) + animations_period(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + The update rate of animated graphical indicators, such as graphs and sliders, + can be adjusted. A normal value may be 40 ms, which corresponds to 25 updates + per second. Increasing this period can help reduce the processor load on the + graphical user interface, particularly on slower computers. It is important to + note that this update rate solely impacts the user interface and does not affect + measurements in any manner. (e.g. 20E-3) + indicators_period(NX_NUMBER): + unit: NX_TIME + doc: | + The update rate of digital indicators, such as the numbers displayed, can be set + to 3 updates per second, equivalent to 300 ms. This interval is sufficient for + the user interface and does not impact measurements in any manner. (e.g. 300E-3) + measurements_period(NX_NUMBER): + exists: optional + unit: NX_TIME + doc: | + The Measurements period determines the integration time required for precise + measurements, primarily utilized in sweep modules. It is particularly useful for + tasks such as recording force-distance curves or cantilever resonances. For + swift measurements with small steps, a value of 40 ms is often adequate. For + regular use, a range of 300-500 ms may be recommended, but when capturing the + resonance of a high-Q cantilever, longer values in the range of several seconds + might be necessary. Usually, this parameter does not require manual adjustment + within this module, as the sweep modules automatically set this value according + to the sweep timings. (e.g. 500E-3) + + # parameters how to change the location from measurement to measurement during the scan + scan_control(NXcollection): + exists: optional + roi(NXtransformations): + frame: + doc: | + Also clarify the frame for the ROI of the scan in lab frame, the middle of the lab + frame is (0, 0), and positive in x means right and in y means up. + circuit(NXcollection): + channels_current: + doc: | + The scan channels are selected by users. (e.g. (A);Bias (V);Z (m);LI Demod 2 X + (A);LI Demod 2 Y (A);LI Demod 1 X (A);LI Demod 1 Y (A)) + positioner(NXcollection): + scanfield(NX_NUMBER): + doc: | + Configure the scan frame like x position; y position; width; height. (e.g. + 3.11737E-9;29.1583E-9;15E-9;15E-9;0E+0) + pixels_line(NX_NUMBER): + doc: | + Scan resolution by setting the Lines equal to Pixels. (e.g. 512) + lines(NX_NUMBER): + doc: | + Define the image resolution. (e.g. 512) + speed_forw(NX_NUMBER): + doc: | + Define the scan forward speed in the forward direction. (m/s) (e.g. 11.7187E-9) + speed_backw(NX_NUMBER): + doc: | + Define the scan backward speed in the forward direction. (m/s) (e.g. 11.7187E-9) + + # RESOLUTION (calculation input) + # TODO: After fix resolution_indicators back to required + # As all of the bellow are linked + # should be NXcollection not NXprocess + resolution_indicators(NXprocess): + exists: optional + + # Temperature 1>link to INSTR/STM/head Temperature 1 (K) (e.g. 4.92997E+0) # Temperature of STM head. + stm_head_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Link to target:/NXentry/NXinstrument/stm_head_temp + + # Temperature 2>link to Temperature 2 (K) - # Temperature of bottom of LHe helium cryostat. + cryo_bottom_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Link to target:/NXentry/NXinstrument/cryo_bottom_temp + + # Temperature 3>link to Temperature 3 (K) - # Temperature of LN2 nitrogen shield. + cryo_shield_temp(NX_NUMBER): + exists: optional + unit: NX_TEMPERATURE + doc: | + Link to target:/NXentry/NXinstrument/temp_cryo_shield + + # Lock-in>link to Modulated signal Bias (V) (e.g. 1E-3) # Applied modulation to the bias voltage. + modulation_signal: + exists: optional + unit: NX_VOLTAGE + doc: | + Link to target:/NXentry/NXinstrument/NXlock_in/modulation_signal + + # link to Integration time (s) (e.g. 150E-6) + # Time during which the spectroscopy data are acquired and averaged. + integration_time(NX_NUMBER): + unit: NX_TIME + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/NXintegration_time + + # link to Bias Spectroscopy>Number of sweeps (e.g. 100) Number of sweeps to measure and average. + number_of_sweeps(NX_NUMBER): + unit: NX_UNITLESS + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/number_of_sweeps + + # link to Bias Spectroscopy>Sweep Start (V) (e.g. -300E-3) # The first bias values of the sweep. + sweep_start(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_start + + # link to Bias Spectroscopy>Sweep End (V) (e.g. 300E-3) # The last bias values of the sweep. + sweep_end(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_end + + # link to Bias Spectroscopy>Num Pixel (e.g. 4096) # Define the sweep number of points, that is, the maximum spectrum resolution eq. Bias window divide by Num Pixel. + num_pixel(NX_NUMBER): + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/num_pixel + + # link to Bias Spectroscopy>Z Avg time (s) (e.g. 100E-3) # Duration over which the Z + # position is recorded and averaged before and after the sweep (the latter only if Record + # final Z position is selected in the Advanced section). After the initial Z averaging + # time, if Z-Controller to Hold is selected in the Advanced section, the Z-Controller is + # set to hold and the tip is placed at the previously averaged Z position (plus Z offset). + z_avg_time(NX_NUMBER): + unit: NX_TIME + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_avg_time + + # link to SoftwareMain>RT Frequency (Hz) (e.g. 20E+3) # The bandwitdh of the + # Hardware and/or Software + rt_frequency(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/rt_frequency + + # link to SoftwareMain>Signals Oversampling (e.g. 10) # (Signals Periods) + # The Signals Period is the rate at which the signals are transferred to the host computer + # running the control software. This is usually lower by a factor of 10 than the sampling + # rate, because an internal oversampling of the signal is done on the real time engine. + # You can reduce the oversampling down to 1 in order to resolve higher frequencies in the + # Spectrum Analyzer. + signals_oversampling(NX_NUMBER): + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/signals_oversampling + + # link to SoftwareMain>Acquisition Period (s) (e.g. 20E-3) # Update rate for several + # processes like History Graph, Auto-Approach, and for many Programming Interface functions. + # This is usually set to 20 ms. All additional timings (7-9) can only be integer multiples + # of this value. They can be set to different values, but the actual timing value will be + # coerced to a multiple of the Acquisition Period. + acquisition_period(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/acquisition_period + + # link to SoftwareMain>Animations Period (s) (e.g. 20E-3) # Update rate of animated + # graphical indicators. These are e.g. some graphs & sliders. A reasonable value is + # 40 ms (25 updates per second). Increase this period to reduce the processor load + # for the graphical user interface, especially on slow computers. This value is purely a + # user interface update rate and does not affect measurements in any way. + animations_period(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/animations_period + + # link to SoftwareMain>Indicators Period (s) (e.g. 300E-3) # Update rate of digital + # indicators, e.g. the numbers displayed besides each slider. Here, 3 updates per + # second, or 300 ms is enough. This value is purely a user interface update rate and + # does not affect measurements in any way. + indicators_period(NX_NUMBER): + unit: NX_TIME + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/indicators_period + + # link to SoftwareMain>Measurements Period (s) (e.g. 500E-3) # The Measurements + # period is the integration time for precise measurements (averaging over specified period), + # mostly used in sweep modules. Examples are recording of a force-distance curve or a + # resonance of a cantilever. For fast measurements with small steps, a value of 40 ms may be + # reasonable. For normal use, 300-500 ms is a good value, but for recording a resonance of a + # high-Q cantilever, values of several seconds might be necessary. Usually this parameter doesn’t need to be set from this module; the sweep modules will set this value according to the sweep timings. + measurements_period(NX_NUMBER): + exists: optional + unit: NX_TIME + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/measurements_period + + # TODO: Later fix REPRODUCIBILITY_indicator + # as all of the bellow are linked + reproducibility_indicators(NXprocess): + exists: optional + + # Bias>Bias(NXBias) (V) (e.g. 100E-3) # Applied bias voltage. + bias(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Link to target:/NXentry/NXinstrument/NXsample_bias/bias + + # Current>Current(NXcircuit) (A) (e.g. -5.3429E-15) # The tunneling current is displayed here. + current(NX_NUMBER): + unit: NX_CURRENT + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current + + # Bias>Calibration(NXbias) (V/V) (e.g. 1E+0) Calibration of the Bias output. If you have + # a Range switch the calibration is stored per range setting. + bias_calibration(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Link to target:/NXentry/NXnstrument/NXsample_bias/bias_calibration + bias_offset(NX_NUMBER): + unit: NX_VOLTAGE + doc: | + Link to target:/NXentry/NXinstrument/NXsample_bias/bias_offset + + # Current>Calibration(NXcircuit) (A/V) (e.g. 100E-12) + # The signals voltages are converted to real world physical values according to the calibration & offset parameters: + # Physical signal = (Voltage * calibration) + offset. + current_calibration(NX_NUMBER): + unit: NX_CURRENT + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_calibration + + # Current>Offset(NXcircuit) (A) (e.g. 16.2897E-15) # The same as "Current>Calibration (A/V)" tag + current_offset(NX_NUMBER): + unit: NX_CURRENT + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_offset + + # Current>Gain(NXcircuit) (e.g. Not switchable) # None + current_gain(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_gain + + # Z offset(NXpositioner_sts) (m) (e.g. 0E+0) # Offset added to the initial averaged position + # Zaver before starting to sweep. This parameter is disabled when Z-Controller to Hold is + # deselected in the Advanced section. The LED “Alt” next to the Z offset indicates if an + # alternate Z-controller setpoint is enabled. + + # Settling time(NXbias) (s) (e.g. 2.1E-3) Time to wait after changing the bias to the next + # level and before starting to acquire data. Adjust this parameter to avoid transient + # effect induced by the bias change. Integration time: time during which the data are + # acquired and averaged. + z_offset(NX_NUMBER): + unit: NX_LENGTH + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_offset + settling_time(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/settling_time + + # Z-Ctrl hold(NXpositioner_sts) (e.g. TRUE) # When selected, the Z-Controller is set to hold + # during the pulse. This means that the controller doesn't control the Z position during the pulse. + z_control_hold(NX_BOOLEAN): + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_ccontroller_hold + + # Final Z(NXpositioner_sts) (m) (e.g. N/A) + final_z(NX_NUMBER): + unit: NX_LENGTH + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/record_final_z + + # Start time(NXlog) (e.g.23.11.2022 18:55:16) # Timestamp of the moment + # when the acquisition starts by pressing the Start button. + # TODO: no available concept is found for the below link + # start_time(link): + # exists: optional + # Link to t target: none + # Bias Spectroscopy>1st Settling time(NXbias) (s) (e.g.2.1E-3) # See the "Settling time (s)" below. + first_settling_time(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/first_settling_time + + # Bias Spectroscopy>Integration time(NXbias) (s) (e.g.150E-6) # Time during which the data + # are acquired and averaged. + # integration_time(link): + # Link to ttarget: /ENTRY[entry]/INSTRUMENT[instrument]/ENVIRONMENT[environment]/sweep_control/bias_spectroscopy/integration_time + # Bias Spectroscopy>End Settling time(NXbias) (s) (e.g.4E-3) # Time to wait after the sweep has finished and the bias is ramped to the initial value. + end_settling_time(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/end_settling_time + + # Bias Spectroscopy>Z control time(NXbias) (s) (e.g.200E-3) # Time during which the + # Z-Controller is enabled once a sweep has finished. When averaging multiple sweeps + # (i.e. Sweeps>1), the Z-Controller is enabled for this duration between each sweep. + # After the last sweep, it will wait the specified time before continuing a running scan. + # This ensures each sweep reliably starts from the same position. This parameter is + # disabled when Z-Controller to Hold is deselected in the Advanced section. + z_control_time(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_control_time + + # Bias Spectroscopy>Max Slew rate(NXbias) (V/s) (e.g.1E+0) # Maximum rate at which + # the bias changes (before, during and after sweeping). + max_slew_rate(NX_NUMBER): + unit: NX_ANY + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/max_slew_rate + + # Bias Spectroscopy>backward sweep(NXbias) (e.g.TRUE) # Select whether to measure + # the backward (return) sweep or the forward only. + backward_sweep(NX_NUMBER): + unit: NX_ANY + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/backward_sweep + + # Z-Controller>Controller name(NXpositioner_sts) (e.g.log Current) # Controller name. + # This name which will be displayed at places where you can select a controller. + z_controller_name: + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_name + + # Z-Controller>Controller status(NXpositioner_sts) (e.g.OFF) # ON/OFF + z_controller_status(NX_BOOLEAN): + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_status + + # Z-Controller>Setpoint(NXpositioner_sts) (e.g.50E-12) # Set Point is the desired value + # of the control signal. It can be set by editing the number or using the slider bar. + # Click the "Set" button above the input field to use the actual value as Set Point. The slider shows the Set Point as well as the current value. + # Z-Controller>Setpoint unit(NXpositioner_sts) (e.g.A) # Angstrom + z_controller_setpoint(NX_NUMBER): + unit: NX_CURRENT + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/set_point + + # Z-Controller>P gain(NXpid) (e.g.6E-12) # The Type switches controller parameters + # between P/I (proportional gain/integral gain) and P/T (proportional gain/time constant). + # The formula for the controller in the frequency domain is: G(s) = P + I/s = P(1 + 1/(Ts)). + # The integral gain and time constant are related as follows: I = P/T. + y_control_p_gain(NX_NUMBER): + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/p_gain + + # Z-Controller>I gain(NXpid) (e.g.39.8241E-9) # See "Z-Controller>P gain" below. + z_control_i_gain(NX_NUMBER): + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/i_gain + + # Z-Controller>Time const(NXpid) (s) (e.g.150.662E-6) # See "Z-Controller>P gain" below. + z_control_time_const(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/time_const + + # Z-Controller>TipLift(NXpositioner_sts) (m) (e.g.0E+0) # Lifts the tip by the specified + # amount when then controller is switched off. This can be a positive or a negative number, + # i.e. the tip can also be moved towards the sample. Be careful with sign and value when + # using this feature. + z_control_tip_lift(NX_NUMBER): + unit: NX_LENGTH + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/tip_lift + + # Z-Controller>Switch off delay(NXpositioner_sts) (s) (e.g.0E+0) # Use this parameter for + # a reproducible position when switching off the Z-controller. When >0 and the Z-controller + # is switched off, it doesn't switch off immediately but continues to run for the specified time and averages the Z position. + z_control_switchoff_delay(NX_NUMBER): + unit: NX_TIME + exists: optional + doc: | + Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/switchoff_delay + sample(NXsample): + exists: optional + doc: | + To describe sample and other constaints that applied on sample before scanning. + sample_prep_descripton: + doc: | + At this moment no base class available that can track entire sample preparation. + + # TODO: discuss convertion data to DATA + (NXdata): + doc: | + This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. + There should also be two more fields called temperature and voltage containing the setpoint values. + There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension + equal to the number of voltage setpoints. + axes: bias_calc + signals: + li_demod_[1;2]_[X/Y]_[-;bwd;filt;bwd_filt] + current_[-;bwd;filt;bwd_filt] + temperature + x + y + z + + # DATA # multi dimensional array: multi I-V array per scan point; + # doc: The format of the data here is similar to a column matrix. + # Bias calc (V) #scanning parameter + # Current (A) # current during forward direction scanning of bias - original NXsensor + # LI Demod 2 X (A) lockin (NXsensor+lockin) + # LI Demod 2 Y (A) lockin + # LI Demod 1 X (A) lockin + # LI Demod 1 Y (A) lockin + # Current [bwd] (A) #bwd - backward (the positive direction shall be clarified by the reference bias scanning frame. Fwd means from left(neg) to right(pos). In the scannig image, the bottom(neg) to top(pos), the left(neg) to right(pos) + # LI Demod 2 X [bwd] (A) lockin + # LI Demod 2 Y [bwd] (A) lockin + # LI Demod 1 X [bwd] (A) lockin + # LI Demod 1 Y [bwd] (A) lockin + # Current (A) [filt] # forward direction (maybe from lockin#2?) + # LI Demod 2 X (A) [filt] lockin + # LI Demod 2 Y (A) [filt] lockin + # LI Demod 1 X (A) [filt] lockin + # LI Demod 1 Y (A) [filt] lockin + # Current (A) [bwd] [filt] + # LI Demod 2 X (A) [bwd] [filt] lockin + # LI Demod 2 Y (A) [bwd] [filt] lockin + # LI Demod 1 X (A) [bwd] [filt] lockin + # LI Demod 1 Y (A) [bwd] [filt] lockin + # Temperature + # x + # y + # z + # single point default plot # current(I) vs bias(V) + single_point(NXdata): + exists: optional + + # line scan default plot # multi I vs. V curves + line_scan(NXdata): + exists: optional + + # alternative plot # current(I) curve in the 2D space of (position(x), bias(V)) + alternative_plot(NXdata): + exists: optional + + # mesh scan default plot # 2D slices of the above alternative plot + mesh_scan(NXdata): + exists: optional + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 39a08f3d1a71d0ce3410e2ed1aed76a7250f94c8681a93d063c95f5966f79b9d +# +# +# +# +# +# +# Application definition for temperature-dependent IV curve measurements +# #2023.19.7 This Nexus file is currently only for STS data, it will be updated to handle the +# STM image mode in the future with a focus on bias spectroscopy in Scanning Tunneling Microscopy. +# +# In this application definition, times should be specified always together with a UTC offset. +# +# This is the application definition describing temperature (T) dependent current voltage (IV) curve +# measurements. For this, a temperature is set. After reaching the temperature, a voltage sweep +# is performed. For each voltage, a current is measured. +# Then, the next desired temperature is set and an IV measurement is performed. +# The data can be visualized in a tensor with: +# I (NXsensor_C, NXsoftware_Read_offset, NXcircuit) +# parameters: +# V has (NXsource+offset, NXsoftware_Scan_offset, NXsensor_V, NXcircuit) +# T has (NXsource, NXsoftware_Scan_offset, NXsensor_T) +# x has (NXsoftware_Scan_offset) +# y has (NXsoftware_Scan_offset) +# z has (NXsoftware_Scan_offset) +# +# +# +# +# +# +# +# +# +# Name of the experiment where the application is applicable. +# +# +# +# +# +# +# +# +# The equipments and techniques as well as the parameter settings and reference signals +# are used during the experiments used in Scanning Tunneling Microscopy (STM). +# +# +# +# +# +# +# +# +# +# +# The name of the output file, with the number of scans at the end. (e.g. +# 221122_Au_5K00014) +# +# +# +# +# The name of the series output file, which represents only the public part of the +# output file. (e.g. 221122_Au_5K) +# +# +# +# +# Path to storage of output files. +# (e.g. Path C:\Users\SPM-PEEM\Desktop\DATA_Nanonis\20220711_CreaTec_Service_Benchmarks_LHe\Nanonis-Session-PMD100-HVHU_CreaTec_Service_PalmaLabBerlin220711) +# +# +# +# +# Descriptive comments for this experiment, added by the experimenter, coming from the +# output file. (e.g. Comment01 SYNC & Filter LP 8order WITHDRAW 600 steps, locked Au(111), +# 50pA, 100 mV set point, 1mV DCA, 973Hz,138 1st H, -84 2nd H) +# +# +# +# +# +# Hardware type used in SPM experiment, includes hardware manufacturers and type. +# (e.g. Nanonis BP5e) +# +# +# +# +# +# Type of software used in SPM experiments, such as software version serial number, UI and +# RT probe release method. (e.g. SW Version Generic 5e -- RT Release 10771) +# +# +# +# Version of the software. +# +# +# +# +# +# +# The Amplifier description that improves or helps to determine tunnel current (current +# between tip and bias). +# +# +# +# +# +# +# Status of Lock-in device whether while performing the experiment +# +# +# +# +# +# This is the signal on which the modulation (sine) will be added. +# +# +# +# +# +# +# The signal is modulated by adding the frequency of the sine modulation. The +# modulation frequency spans can be from 10 mHz to 40 kHz, corresponding to the output filter +# cut-off range. When dealing with harmonics, it's essential to ensure that the +# harmonic frequencies remain below ~100 kHz, which aligns with the input filter cut-off. +# Be mindful that hardware filters might impact the amplitude as the signal approaches +# their cut-off frequencies." (e.g. 973E+0) +# +# +# +# +# +# The amplitude (in physical units of modulated signal) of the sine modulation. +# +# +# +# +# +# The input signal (STS signal) will be demodulated, in order to determine the amplitude +# and phase at the frequency set in the Frequency field or harmonics, such as current, +# bias, et.al. +# +# +# +# +# +# N denotes 1 or 2. The order of the harmonic oscillation to be detected in the demodulated +# signal should be considered relative to the modulation frequency. When dealing with +# higher harmonics, it's essential to ensure that their frequencies do not surpass +# the analogue signal bandwidth (e.g. harmonic_order_1). +# +# +# +# +# +# Reference phase for the sine on the demodulated signal with respect to the +# modulation signal. The determined phase is displayed with respect to the +# reference phase. +# +# +# +# +# +# +# +# +# Applied a voltage between tip and sample. +# +# +# +# +# +# +# +# +# Temperature of STM head. Note: At least one field from stm_head_temperature, +# cryo_bottom_temp and cryo_sheild_temp must be provided. +# +# +# +# +# Temperature of liquid helium cryostat. Note: At least one field from +# stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp must be provided. +# +# +# +# +# Temperature of liquid nitrogen shield. Temperature 3 (K) (e.g 78.00000E+0). Note: At +# least one field from stm_head_temperature, cryo_bottom_temp and cryo_sheild_temp +# must be provided. +# +# +# +# +# +# +# Configuration for piezoelectric scanner used to move tip along X and Y direction. The +# material of the Piezoelectric scanner composed of polycrystalline solids and sensitive to +# applied voltage. +# +# +# +# The name of calibration type. (e.g. LHe) +# +# +# +# +# N denotes X or Y or Z. There are three parameters in the X, Y, and Z directions, +# along with three available controls: Calibration (m/V), Range (m), and HV gain. Only +# two of these parameters are required to define the calibration. Consequently, when any +# value is changed, one of the other values will be automatically updated. (e.g. calib_X = 3.8E-9) +# +# +# +# +# N denotes X or Y or Z. In some systems, there is an HV gain readout feature. For +# these systems, the HV gain should be automatically adjusted whenever the gain is +# changed at the high voltage amplifier. (e.g. 14.5) +# +# +# +# +# +# N denotes X or Y. There are 2 parameters in X and Y directions, and tilt needs to be +# adjusted according to the actual surface. (in degrees, first order correction). +# +# +# +# +# +# N denotes X or Y. There are 2 parameters in X and Y directions. (can be set +# approximately to the length of the piezotube). +# +# +# +# +# N denotes X or Y. There are 2 parameters in X and Y directions. If you know them, +# you can enter the 2nd order piezo characteristics to compensate for it. The +# following equation shows the interpretation of the 2nd order correction parameter: +# For the X-piezo: "Ux = 1/cx · X + cxx · X2" with units: +# [V] = [V/m] · [m] + [V/m2] · [m2] where cx is the calibration of the piezo X and cxx +# is the 2nd order correction. (V/m^2). (e.g. 0E+0) +# +# +# +# +# N denotes X, Y or Z. There are 3 parameters in X, Y and Z directions. Define the +# drift speed for all three axes. When the compensation is on, the piezos will start to +# move at that speed. (e.g. 0E+0) +# +# +# +# +# Use the button to enable or disable the drift compensation. (e.g. FALSE) +# +# +# +# +# +# Describes an environment setup for a temperature-dependent IV measurement experiment. +# The temperature and voltage must be present as independently scanned controllers and +# the current sensor must also be present with its readings. +# +# +# +# +# This is set-point of tip current (in the constant current mode should be equal to set-point, +# in the constant height mode means the real tunnelling current between tip and sample). +# +# +# +# +# Value of calibration that comes as A/V. +# +# +# +# +# +# +# +# +# +# Clarify the frame laboratory frame. +# +# +# +# The scanning area in x position in the frame. (e.g. -890.53E-12) +# +# +# +# +# The scanning area in y position in the frame. (e.g. 29.6968E-9) +# +# +# +# +# The scanning area in z position in the frame. (e.g. 130.5E-9) +# +# +# +# +# +# Indicate the relative tip position z between tip and sample. The tip position can also +# be varied when the z_controller is not running. (e.g. 130.5E-9) +# +# +# +# +# +# +# +# +# +# Time during which the spectroscopy data are acquired and averaged. (e.g. 150E-6) +# +# +# +# +# Number of sweeps to measure and average. (e.g. 100) +# +# +# +# +# The start bias values of the sweep. (e.g. -300E-3) +# +# +# +# +# The end bias values of the sweep. (e.g. 300E-3) +# +# +# +# +# The sweep number of points is defined as the maximum spectrum resolution, which +# is equal to the bias sweep window divided by the number of pixels. (e.g. 4096) +# +# +# +# +# The Z position is recorded and averaged for a certain duration both before and +# after the sweep. After the initial Z averaging time, if "Z-Controller to Hold" +# is selected, the Z-Controller is set to hold mode, and the tip is positioned at +# the previously averaged Z position (adjusted by the Z offset). (e.g. 100E-3) +# +# +# +# +# +# +# The bandwidth of the Hardware and/or Software is instrument specific. +# For example, Nanonis Generic 5 has 'RT Frequency' (e.g. 20E+3). +# +# +# +# +# The Signals Period represents the rate at which signals are transferred to +# the host computer, which operates the control software. This rate may +# be 10 times lower than the sampling rate, as the real-time engine internally +# oversamples the signal. If desired, you may have the option to reduce the oversampling +# to 1, enabling higher frequency resolution in the Spectrum Analyzer. (e.g. 10) +# +# +# +# +# The update rate is utilized in various processes, including the History Graph, +# Auto-Approach, and multiple Programming Interface functions. It may be +# configured to a 20 ms interval. Any additional timings must strictly be integer +# multiples of this base value. While it is possible to set these additional +# timings to different values, the actual timing value will automatically be +# adjusted to become a multiple of the Acquisition Period. (e.g. 20E-3) +# +# +# +# +# The update rate of animated graphical indicators, such as graphs and sliders, +# can be adjusted. A normal value may be 40 ms, which corresponds to 25 updates +# per second. Increasing this period can help reduce the processor load on the +# graphical user interface, particularly on slower computers. It is important to +# note that this update rate solely impacts the user interface and does not affect +# measurements in any manner. (e.g. 20E-3) +# +# +# +# +# The update rate of digital indicators, such as the numbers displayed, can be set +# to 3 updates per second, equivalent to 300 ms. This interval is sufficient for +# the user interface and does not impact measurements in any manner. (e.g. 300E-3) +# +# +# +# +# The Measurements period determines the integration time required for precise +# measurements, primarily utilized in sweep modules. It is particularly useful for +# tasks such as recording force-distance curves or cantilever resonances. For +# swift measurements with small steps, a value of 40 ms is often adequate. For +# regular use, a range of 300-500 ms may be recommended, but when capturing the +# resonance of a high-Q cantilever, longer values in the range of several seconds +# might be necessary. Usually, this parameter does not require manual adjustment +# within this module, as the sweep modules automatically set this value according +# to the sweep timings. (e.g. 500E-3) +# +# +# +# +# +# +# +# +# +# Also clarify the frame for the ROI of the scan in lab frame, the middle of the lab +# frame is (0, 0), and positive in x means right and in y means up. +# +# +# +# +# +# +# The scan channels are selected by users. (e.g. (A);Bias (V);Z (m);LI Demod 2 X +# (A);LI Demod 2 Y (A);LI Demod 1 X (A);LI Demod 1 Y (A)) +# +# +# +# +# +# +# Configure the scan frame like x position; y position; width; height. (e.g. +# 3.11737E-9;29.1583E-9;15E-9;15E-9;0E+0) +# +# +# +# +# Scan resolution by setting the Lines equal to Pixels. (e.g. 512) +# +# +# +# +# Define the image resolution. (e.g. 512) +# +# +# +# +# Define the scan forward speed in the forward direction. (m/s) (e.g. 11.7187E-9) +# +# +# +# +# Define the scan backward speed in the forward direction. (m/s) (e.g. 11.7187E-9) +# +# +# +# +# +# +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/stm_head_temp +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/cryo_bottom_temp +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/temp_cryo_shield +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXlock_in/modulation_signal +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/NXintegration_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/number_of_sweeps +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_start +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/sweep_end +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/num_pixel +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_avg_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/rt_frequency +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/signals_oversampling +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/acquisition_period +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/animations_period +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/indicators_period +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXcircuit/measurements_period +# +# +# +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXsample_bias/bias +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current +# +# +# +# +# +# Link to target:/NXentry/NXnstrument/NXsample_bias/bias_calibration +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXsample_bias/bias_offset +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_calibration +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_offset +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXcurrent_sensor/current_gain +# +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_offset +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/settling_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_ccontroller_hold +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/record_final_z +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/first_settling_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/end_settling_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/z_control_time +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/max_slew_rate +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXsweep_control/NXbias_spectroscopy/backward_sweep +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_name +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/controller_status +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/set_point +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/p_gain +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/i_gain +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/time_const +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/tip_lift +# +# +# +# +# +# +# Link to target:/NXentry/NXinstrument/NXenvironment/NXposition/NXz_controller/switchoff_delay +# +# +# +# +# +# To describe sample and other constaints that applied on sample before scanning. +# +# +# +# At this moment no base class available that can track entire sample preparation. +# +# +# +# +# +# +# This NXdata should contain separate fields for the current values at different temperature setpoints, for example current_at_100C. +# There should also be two more fields called temperature and voltage containing the setpoint values. +# There should also be a field with an array of rank equal to the number of different temperature setpoints and each child's dimension +# equal to the number of voltage setpoints. +# axes: bias_calc +# signals: +# li_demod_[1;2]_[X/Y]_[-;bwd;filt;bwd_filt] +# current_[-;bwd;filt;bwd_filt] +# temperature +# x +# y +# z +# +# +# +# +# +# +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsubsampling_filter.yaml b/contributed_definitions/nyaml/NXsubsampling_filter.yaml new file mode 100644 index 0000000000..bd41ca04ff --- /dev/null +++ b/contributed_definitions/nyaml/NXsubsampling_filter.yaml @@ -0,0 +1,71 @@ +category: base +doc: | + Settings of a filter to sample entries based on their value. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXsubsampling_filter(NXobject): + linear_range_min_incr_max(NX_UINT): + unit: NX_UNITLESS + doc: | + Triplet of the minimum, increment, and maximum value which will + be included in the analysis. The increment controls which n-th entry to take. + + Take as an example a dataset with 100 entries (their indices start at zero) + and the filter set to 0, 1, 99. This will process each entry. + 0, 2, 99 will take each second entry. 90, 3, 99 will take only each third + entry beginning from entry 90 up to 99. + dimensions: + rank: 1 + dim: [[1, 3]] + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8b2ae0d8e8fbb65aa0b1e6f7cf5ea78417bf28ad83373f3401b159c41ef7c24c +# +# +# +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Settings of a filter to sample entries based on their value. +# +# +# +# Triplet of the minimum, increment, and maximum value which will +# be included in the analysis. The increment controls which n-th entry to take. +# +# Take as an example a dataset with 100 entries (their indices start at zero) +# and the filter set to 0, 1, 99. This will process each entry. +# 0, 2, 99 will take each second entry. 90, 3, 99 will take only each third +# entry beginning from entry 90 up to 99. +# +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXsubstance.yaml b/contributed_definitions/nyaml/NXsubstance.yaml new file mode 100644 index 0000000000..046ca73848 --- /dev/null +++ b/contributed_definitions/nyaml/NXsubstance.yaml @@ -0,0 +1,193 @@ +category: base +doc: | + A form of matter with a constant, definite chemical composition. + + Examples can be single chemical elements, chemical compunds, or alloys. + For further information, see https://en.wikipedia.org/wiki/Chemical_substance. +type: group +NXsubstance(NXobject): + name: + doc: | + User-defined chemical name of the substance + molecular_mass(NX_FLOAT): + unit: NX_MOLECULAR_WEIGHT + doc: | + Molecular mass of the substance + cas_number: + doc: | + Unique numeric CAS REGISTRY number of the sample chemical content + For further information, see https://www.cas.org/. + cas_name: + doc: | + CAS REGISTRY name of the sample chemical content + cas_uri: + doc: | + CAS REGISTRY URI + cas_image(NXnote): + doc: | + CAS REGISTRY image + cas_synonyms: + doc: | + Synonyms in the CAS system. + inchi_str: + doc: | + String InChi identifier. + The InChI identifier expresses chemical structures in terms of atomic connectivity, + tautomeric state, isotopes, stereochemistry and electronic charge in order to + produce a string of machine-readable characters unique to the respective molecule. + For further information, see https://iupac.org/who-we-are/divisions/division-details/inchi/. + inchi_key: + doc: | + Condensed, 27 character InChI key. + Hashed version of the full InChI (using the SHA-256 algorithm). + iupac_name: + doc: | + Name according to the IUPAC system (standard). + For further information, see https://iupac.org/. + smile: + doc: | + Identifier in the SMILES (Simplified Molecular Input Line Entry System) system + For further information, see https://www.daylight.com/smiles/. + canonical_smile: + doc: | + Canonical version of the smiles identifier + molecular_formula_hill: + doc: | + The chemical formula specified using CIF conventions. + Abbreviated version of CIF standard:107 + This is the *Hill* system used by Chemical Abstracts. + + * 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. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# c7ae6e64d284340e8b3ad667882f9b7f3a31bf7c509b6cc8794529ec765cb25a +# +# +# +# +# +# A form of matter with a constant, definite chemical composition. +# +# Examples can be single chemical elements, chemical compunds, or alloys. +# For further information, see https://en.wikipedia.org/wiki/Chemical_substance. +# +# +# +# User-defined chemical name of the substance +# +# +# +# +# Molecular mass of the substance +# +# +# +# +# Unique numeric CAS REGISTRY number of the sample chemical content +# For further information, see https://www.cas.org/. +# +# +# +# +# CAS REGISTRY name of the sample chemical content +# +# +# +# +# CAS REGISTRY URI +# +# +# +# +# CAS REGISTRY image +# +# +# +# +# Synonyms in the CAS system. +# +# +# +# +# String InChi identifier. +# The InChI identifier expresses chemical structures in terms of atomic connectivity, +# tautomeric state, isotopes, stereochemistry and electronic charge in order to +# produce a string of machine-readable characters unique to the respective molecule. +# For further information, see https://iupac.org/who-we-are/divisions/division-details/inchi/. +# +# +# +# +# Condensed, 27 character InChI key. +# Hashed version of the full InChI (using the SHA-256 algorithm). +# +# +# +# +# Name according to the IUPAC system (standard). +# For further information, see https://iupac.org/. +# +# +# +# +# Identifier in the SMILES (Simplified Molecular Input Line Entry System) system +# For further information, see https://www.daylight.com/smiles/. +# +# +# +# +# Canonical version of the smiles identifier +# +# +# +# +# The chemical formula specified using CIF conventions. +# Abbreviated version of CIF standard:107 +# This is the *Hill* system used by Chemical Abstracts. +# +# * 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. +# +# +# diff --git a/contributed_definitions/nyaml/NXtransmission.yaml b/contributed_definitions/nyaml/NXtransmission.yaml new file mode 100644 index 0000000000..b4ec2b439b --- /dev/null +++ b/contributed_definitions/nyaml/NXtransmission.yaml @@ -0,0 +1,607 @@ +category: application +doc: | + Application definition for transmission experiments +symbols: + doc: | + Variables used throughout the experiment + N_wavelengths: | + Number of wavelength points + N_scans: | + Number of scans + +# FAIRmat consortium 21.07.2022 +# Draft NeXus application definition for transmission experiments +type: group +NXtransmission(NXobject): + (NXentry): + doc: | + This application definition + definition: + doc: | + An application definition for transmission. + \@version: + doc: | + Version number to identify which definition of this application definition was + used for this entry/data. + \@url: + doc: | + URL where to find further material (documentation, examples) relevant to the + application definition. + enumeration: [NXtransmission] + start_time(NX_DATE_TIME): + doc: | + Start time of the experiment. + experiment_identifier(NX_CHAR): + doc: | + Unique identifier of the experiment, such as a (globally persistent) + unique identifier. + + * The identifier is usually defined by the facility or principle + investigator. + * The identifier enables to link experiments to e.g. proposals. + experiment_description(NX_CHAR): + exists: optional + doc: | + An optional free-text description of the experiment. However, details of the + experiment should be defined in the specific fields of this application + definition rather than in this experiment description. + + # TODO: Just used a NXmanufacturer, maybe + # it is nicer to introduce a general NXprogram class? + # However, a program may also be viewed as some sort + # of instrument. + acquisition_program(NXfabrication): + exists: optional + model(NX_CHAR): + doc: | + Commercial or otherwise defined given name to the program that was + used to generate the result file(s) with measured data and metadata. + identifier(NX_CHAR): + doc: | + Version number of the program that was used to generate the result + file(s) with measured data and metadata. + \@url: + type: NX_CHAR + exists: recommended + doc: | + Website of the software + operator(NXuser): + exists: ['min', '1'] + doc: | + Contact information of at least the user of the instrument or the investigator + who performed this experiment. Adding multiple users if relevant is recommended. + name: + doc: | + Name of the user. + affiliation: + doc: | + Name of the affiliation of the user at the point in time when the experiment was + performed. + address: + doc: | + Street address of the user's affiliation. + email: + doc: | + Email address of the user. + url: + exists: recommended + doc: | + Author ID defined by reasearch id services, e.g. orcid (https://orcid.org/). + telephone_number: + exists: recommended + doc: | + Telephone number of the user. + instrument(NXinstrument): + manufacturer(NXfabrication): + exists: recommended + doc: | + Manufacturer of the instrument. + common_beam_mask(NXslit): + doc: | + Common beam mask to shape the incident beam + y_gap(NX_NUMBER): + unit: NX_UNITLESS + doc: | + The height of the common beam in percentage of the beam + common_beam_depolarizer(NX_BOOLEAN): + doc: | + If true, the incident beam is depolarized. + polarizer(NX_NUMBER): + unit: NX_ANGLE + doc: | + Polarizer value inside the beam path + ref_attenuator(NXattenuator): + doc: | + Attenuator in the reference beam + attenuator_transmission(NX_FLOAT): + sample_attenuator(NXattenuator): + doc: | + Attenuator in the sample beam + attenuator_transmission(NX_FLOAT): + spectrometer(NXmonochromator): + wavelength(NX_NUMBER): + unit: NX_LENGTH + doc: | + Wavelength value(s) used for the measurement. + An array of 1 or more elements. Length defines N_wavelenghts + dimensions: + rank: 1 + dim: [[1, N_wavelengths]] + spectral_resolution(NX_NUMBER): + exists: optional + unit: NX_WAVENUMBER + doc: | + Overall spectral resolution of this spectrometer. + If several gratings are employed the spectral resoultion + should rather be specified for each grating inside the + NXgrating group of this spectrometer. + (NXgrating): + exists: optional + doc: | + Diffraction grating, as could be used in a monochromator. + If two or more gratings were used, define the angular + dispersion and the wavelength range (min/max wavelength) + for each grating and make sure that the wavelength ranges + do not overlap. The dispersion should be defined for the + entire wavelength range of the experiment. + angular_dispersion(NX_NUMBER): + exists: optional + doc: | + Dispersion of the grating in nm/mm used. + blaze_wavelength(NX_NUMBER): + exists: optional + unit: NX_LENGTH + doc: | + The blaze wavelength of the grating used. + spectral_resolution(NX_NUMBER): + exists: optional + unit: NX_WAVENUMBER + doc: | + Overall spectral resolution of the instrument + when this grating is used. + wavelength_range(NX_NUMBER): + unit: NX_LENGTH + doc: | + Wavelength range in which this grating was used + dimensions: + rank: 1 + dim: [[1, 2]] + (NXdetector): + wavelength_range(NX_NUMBER): + unit: NX_LENGTH + doc: | + Wavelength range in which this detector was used + dimensions: + rank: 1 + dim: [[1, 2]] + type(NX_CHAR): + doc: | + Detector type + enumeration: [PMT, PbS, InGaAs] + response_time(NX_NUMBER): + exists: optional + unit: NX_TIME + doc: | + Response time of the detector + gain(NX_NUMBER): + exists: optional + doc: | + Detector gain + slit(NXslit): + doc: | + Slit setting used for measurement with this detector + type(NX_CHAR): + enumeration: [fixed, servo] + time_points(NX_NUMBER): + exists: optional + unit: NX_TIME + doc: | + An array of relative scan start time points. + dimensions: + rank: 1 + dim: [[1, N_scans]] + measured_data(NX_NUMBER): + doc: | + Resulting data from the measurement. + The length of the 2nd dimension is + the number of time points. + If it has length one the time_points + may be empty. + dimensions: + rank: 2 + dim: [[1, N_scans], [2, N_wavelengths]] + (NXsource): + doc: | + The lamp used for illumination + type(NX_CHAR): + doc: | + The type of lamp, e.g. halogen, D2 etc. + enumeration: [halogen, D2] + spectrum(NX_NUMBER): + exists: optional + doc: | + The spectrum of the lamp used + dimensions: + rank: 1 + dim: [[1, N_wavelengths]] + wavelength_range(NX_NUMBER): + unit: NX_LENGTH + doc: | + Wavelength range in which the lamp was used + dimensions: + rank: 1 + dim: [[1, 2]] + (NXsample): + + # TODO: This should be extended by a generic + # NXsample class. + doc: | + Properties of the sample measured + name(NX_CHAR): + data(NXdata): + doc: | + A default view of the data emitted intensity vs. wavelength. + From measured_data plot intensity and wavelength. + \@axes: + doc: | + We recommend to use wavelength as a default attribute, but it can be + replaced by any suitable parameter along the X-axis. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8e44140527b6ce26fe9832c663c9074067ec6c8ecfdb137c8740677c772749f8 +# +# +# +# +# +# +# +# Variables used throughout the experiment +# +# +# +# Number of wavelength points +# +# +# +# +# Number of scans +# +# +# +# +# Application definition for transmission experiments +# +# +# +# This application definition +# +# +# +# An application definition for transmission. +# +# +# +# Version number to identify which definition of this application definition was +# used for this entry/data. +# +# +# +# +# URL where to find further material (documentation, examples) relevant to the +# application definition. +# +# +# +# +# +# +# +# +# Start time of the experiment. +# +# +# +# +# Unique identifier of the experiment, such as a (globally persistent) +# unique identifier. +# +# * The identifier is usually defined by the facility or principle +# investigator. +# * The identifier enables to link experiments to e.g. proposals. +# +# +# +# +# An optional free-text description of the experiment. However, details of the +# experiment should be defined in the specific fields of this application +# definition rather than in this experiment description. +# +# +# +# +# +# +# Commercial or otherwise defined given name to the program that was +# used to generate the result file(s) with measured data and metadata. +# +# +# +# +# Version number of the program that was used to generate the result +# file(s) with measured data and metadata. +# +# +# +# +# Website of the software +# +# +# +# +# +# Contact information of at least the user of the instrument or the investigator +# who performed this experiment. Adding multiple users if relevant is recommended. +# +# +# +# Name of the user. +# +# +# +# +# Name of the affiliation of the user at the point in time when the experiment was +# performed. +# +# +# +# +# Street address of the user's affiliation. +# +# +# +# +# Email address of the user. +# +# +# +# +# Author ID defined by reasearch id services, e.g. orcid (https://orcid.org/). +# +# +# +# +# Telephone number of the user. +# +# +# +# +# +# +# Manufacturer of the instrument. +# +# +# +# +# Common beam mask to shape the incident beam +# +# +# +# The height of the common beam in percentage of the beam +# +# +# +# +# +# If true, the incident beam is depolarized. +# +# +# +# +# Polarizer value inside the beam path +# +# +# +# +# Attenuator in the reference beam +# +# +# +# +# +# Attenuator in the sample beam +# +# +# +# +# +# +# Wavelength value(s) used for the measurement. +# An array of 1 or more elements. Length defines N_wavelenghts +# +# +# +# +# +# +# +# Overall spectral resolution of this spectrometer. +# If several gratings are employed the spectral resoultion +# should rather be specified for each grating inside the +# NXgrating group of this spectrometer. +# +# +# +# +# Diffraction grating, as could be used in a monochromator. +# If two or more gratings were used, define the angular +# dispersion and the wavelength range (min/max wavelength) +# for each grating and make sure that the wavelength ranges +# do not overlap. The dispersion should be defined for the +# entire wavelength range of the experiment. +# +# +# +# Dispersion of the grating in nm/mm used. +# +# +# +# +# The blaze wavelength of the grating used. +# +# +# +# +# Overall spectral resolution of the instrument +# when this grating is used. +# +# +# +# +# Wavelength range in which this grating was used +# +# +# +# +# +# +# +# +# +# +# Wavelength range in which this detector was used +# +# +# +# +# +# +# +# Detector type +# +# +# +# +# +# +# +# +# +# Response time of the detector +# +# +# +# +# Detector gain +# +# +# +# +# Slit setting used for measurement with this detector +# +# +# +# +# +# +# +# +# +# +# +# An array of relative scan start time points. +# +# +# +# +# +# +# +# Resulting data from the measurement. +# The length of the 2nd dimension is +# the number of time points. +# If it has length one the time_points +# may be empty. +# +# +# +# +# +# +# +# +# The lamp used for illumination +# +# +# +# The type of lamp, e.g. halogen, D2 etc. +# +# +# +# +# +# +# +# +# The spectrum of the lamp used +# +# +# +# +# +# +# +# Wavelength range in which the lamp was used +# +# +# +# +# +# +# +# +# +# +# Properties of the sample measured +# +# +# +# +# +# A default view of the data emitted intensity vs. wavelength. +# From measured_data plot intensity and wavelength. +# +# +# +# We recommend to use wavelength as a default attribute, but it can be +# replaced by any suitable parameter along the X-axis. +# +# +# +# +# diff --git a/contributed_definitions/nyaml/NXunit_cell.yaml b/contributed_definitions/nyaml/NXunit_cell.yaml new file mode 100644 index 0000000000..4109b2333b --- /dev/null +++ b/contributed_definitions/nyaml/NXunit_cell.yaml @@ -0,0 +1,379 @@ +category: base +doc: | + Description of a unit cell, i.e., the crystal structure of a single + thermodynamic phase. +symbols: + n_pos: | + Number of atom positions. +type: group +NXunit_cell(NXobject): + crystallographic_database_identifier: + doc: | + Identifier of an entry resolvable via crystallographic_database + which was used for creating this structure model. + crystallographic_database: + doc: | + Name of the crystallographic database to resolve + crystallographic_database_identifier e.g. COD, ICSD, or others. + lattice_system: + doc: | + A lattice system is a group of lattices with the same set of lattice point groups. + For further information, see https://en.wikipedia.org/wiki/Crystal_system. + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + space_group: + doc: | + Crystallographic space group. + A space group is the symmetry group of a repeating pattern in space. + For further information, see International Table for Crystallography (https://it.iucr.org/). + point_group: + doc: | + Crystallographic point group. + A crystallographic point group is a set of symmetry operations, corresponding to one of the point groups in three dimensions, + such that each operation (perhaps followed by a translation) would leave the structure of a crystal unchanged. + This field should use Schoenflies notation (see Schoenflies, A., Krystallsysteme und Krystallstructur, 1891). + For further information, see https://dictionary.iucr.org/Point_group. + laue_group: + doc: | + Laue group (also called Laue class). + The Laue classes are eleven geometric crystal classes containing centrosymmetric crystallographic types of point groups and their subgroups. + When absorption is negligible and Friedel's law applies, it is impossible to distinguish by diffraction between a centrosymmetric point group + and one of its non-centrosymmetric subgroups; only point groups belonging to different Laue classes can then be distinguished. + For further information, see https://dictionary.iucr.org/Laue_class. + + # defined using which convention? + a_b_c(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell parameters a, b, and c + dimensions: + rank: 1 + dim: [[1, 3]] + base_vector_a(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell vector a + dimensions: + rank: 1 + dim: [[1, 3]] + \@depends_on: + doc: | + For definining which coordinate system the unit cell vector a is defined in. + base_vector_b(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell vector b + dimensions: + rank: 1 + dim: [[1, 3]] + \@depends_on: + doc: | + For definining which coordinate system the unit cell vector b is defined in. + base_vector_c(NX_FLOAT): + unit: NX_LENGTH + doc: | + Crystallography unit cell vector c + dimensions: + rank: 1 + dim: [[1, 3]] + \@depends_on: + doc: | + For definining which coordinate system the unit cell vector c is defined in. + alpha_beta_gamma(NX_FLOAT): + unit: NX_ANGLE + doc: | + Crystallography unit cell angles alpha, beta, and gamma + dimensions: + rank: 1 + dim: [[1, 3]] + volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Volume of the unit cell + + # add enumeration of all possible + is_centrosymmetric(NX_BOOLEAN): + doc: | + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + is_chiral(NX_BOOLEAN): + doc: | + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + phase_identifier(NX_UINT): + unit: NX_UNITLESS + doc: | + Identifier for the phase. + The value 0 is reserved for the unknown phase which represents the null-model + that no phase model was sufficiently significantly confirmed. + phase_name: + doc: | + Trivial name of the phase/alias. + atom_identifier: + doc: | + Labels for each atom position + dimensions: + rank: 1 + dim: [[1, n_pos]] + atom(NX_UINT): + unit: NX_UNITLESS + doc: | + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) `_ + dimensions: + rank: 1 + dim: [[1, n_pos]] + atom_positions(NX_FLOAT): + unit: NX_LENGTH + doc: | + Atom positions x, y, z. + dimensions: + rank: 2 + dim: [[1, n_pos], [2, 3]] + \@depends_on: + doc: | + Reference to an instance of NXcoordinate_system whereby the positions can be + resolved. + atom_occupancy(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Relative occupancy of the atom position. + dimensions: + rank: 1 + dim: [[1, n_pos]] + depends_on: + doc: | + For definining which coordinate system the unit cell parameters are defined in. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 4921c2e1993393e8f5cb0b44e3470cba5cf59b6d1a88c15ef3cec4f60ccee8f3 +# +# +# +# +# +# +# +# Number of atom positions. +# +# +# +# +# Description of a unit cell, i.e., the crystal structure of a single +# thermodynamic phase. +# +# +# +# Identifier of an entry resolvable via crystallographic_database +# which was used for creating this structure model. +# +# +# +# +# Name of the crystallographic database to resolve +# crystallographic_database_identifier e.g. COD, ICSD, or others. +# +# +# +# +# A lattice system is a group of lattices with the same set of lattice point groups. +# For further information, see https://en.wikipedia.org/wiki/Crystal_system. +# +# +# +# +# +# +# +# +# +# +# +# +# +# Crystallographic space group. +# A space group is the symmetry group of a repeating pattern in space. +# For further information, see International Table for Crystallography (https://it.iucr.org/). +# +# +# +# +# Crystallographic point group. +# A crystallographic point group is a set of symmetry operations, corresponding to one of the point groups in three dimensions, +# such that each operation (perhaps followed by a translation) would leave the structure of a crystal unchanged. +# This field should use Schoenflies notation (see Schoenflies, A., Krystallsysteme und Krystallstructur, 1891). +# For further information, see https://dictionary.iucr.org/Point_group. +# +# +# +# +# Laue group (also called Laue class). +# The Laue classes are eleven geometric crystal classes containing centrosymmetric crystallographic types of point groups and their subgroups. +# When absorption is negligible and Friedel's law applies, it is impossible to distinguish by diffraction between a centrosymmetric point group +# and one of its non-centrosymmetric subgroups; only point groups belonging to different Laue classes can then be distinguished. +# For further information, see https://dictionary.iucr.org/Laue_class. +# +# +# +# +# +# Crystallography unit cell parameters a, b, and c +# +# +# +# +# +# +# +# Crystallography unit cell vector a +# +# +# +# +# +# +# For definining which coordinate system the unit cell vector a is defined in. +# +# +# +# +# +# Crystallography unit cell vector b +# +# +# +# +# +# +# For definining which coordinate system the unit cell vector b is defined in. +# +# +# +# +# +# Crystallography unit cell vector c +# +# +# +# +# +# +# For definining which coordinate system the unit cell vector c is defined in. +# +# +# +# +# +# Crystallography unit cell angles alpha, beta, and gamma +# +# +# +# +# +# +# +# Volume of the unit cell +# +# +# +# +# +# True if space group is considered a centrosymmetric one. +# False if space group is considered a non-centrosymmetric one. +# Centrosymmetric has all types and combinations of symmetry elements +# (translation, rotational axis, mirror planes, center of inversion) +# Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). +# Chiral compared to non-centrosymmetric is constrained (no mirror planes). +# +# +# +# +# True if space group is considered a chiral one. +# False if space group is consider a non-chiral one. +# +# +# +# +# Identifier for the phase. +# The value 0 is reserved for the unknown phase which represents the null-model +# that no phase model was sufficiently significantly confirmed. +# +# +# +# +# Trivial name of the phase/alias. +# +# +# +# +# Labels for each atom position +# +# +# +# +# +# +# +# The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` +# the number of protons and :math:`N` the number of neutrons +# of each isotope respectively. Z and N have to be 8-bit unsigned integers. +# For the rationale behind this `M. Kühbach et al. (2021) <https://doi.org/10.1017/S1431927621012241>`_ +# +# +# +# +# +# +# +# Atom positions x, y, z. +# +# +# +# +# +# +# +# Reference to an instance of NXcoordinate_system whereby the positions can be +# resolved. +# +# +# +# +# +# Relative occupancy of the atom position. +# +# +# +# +# +# +# +# For definining which coordinate system the unit cell parameters are defined in. +# +# +# diff --git a/contributed_definitions/nyaml/NXwaveplate.yaml b/contributed_definitions/nyaml/NXwaveplate.yaml new file mode 100644 index 0000000000..b23d9de71f --- /dev/null +++ b/contributed_definitions/nyaml/NXwaveplate.yaml @@ -0,0 +1,286 @@ +category: base +doc: | + A waveplate or retarder. +symbols: + N_spectrum: | + Size of the wavelength array for which the refractive index of the material + and/or coating is given. + N_wavelengths: | + Number of discrete wavelengths for which the waveplate is designed. If it + operates for a range of wavelengths then N_wavelengths = 2 and the minimum + and maximum values of the range should be provided. + +# A draft of a new base class to describe a waveplate +type: group +NXwaveplate(NXobject): + type: + doc: | + Type of waveplate (e.g. achromatic waveplate or zero-order waveplate). + + # A waveplate can be e.g. a dual-wavelength multi-order plate + # => multiple selection needs to be possible + enumeration: [zero-order waveplate, achromatic waveplate, multiple-order waveplate, dual-wavelength waveplate, other] + + # Are there any other common wave plate types? + other_type: + doc: | + If you selected 'other' in type describe what it is. + retardance: + doc: | + Specify the retardance of the waveplate (e.g. full-wave, half-wave + (lambda/2), quarter-wave (lambda/4) plate). + enumeration: [full-wave plate, half-wave plate, quarter-wave plate] + wavelengths(NX_NUMBER): + exists: recommended + doc: | + Discrete wavelengths for which the waveplate is designed. If the + waveplate operates over an entire range of wavelengths, enter the minimum + and maximum values of the wavelength range (in this case + N_wavelengths = 2). + dimensions: + rank: 1 + dim: [[1, N_wavelengths]] + diameter(NX_FLOAT): + unit: NX_LENGTH + doc: | + Diameter of the waveplate. + clear_aperture(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Clear aperture of the device (e.g. 90% of diameter for a disc or 90% of + length/height for square geometry). + + # Would it be better to provide the clear aperture as length? + substrate(NXsample): + doc: | + Describe the material of the substrate of the wave plate in + substrate/substrate_material and provide its index of refraction in + substrate/index_of_refraction_substrate, if known. + substrate_material: + doc: | + Specify the material of the wave plate. If the device has a + coating it should be described in coating/coating_material. + substrate_thickness(NX_NUMBER): + unit: NX_LENGTH + doc: | + Thickness of the wave plate substrate. + index_of_refration_substrate(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the wave plate substrate. Specify at + given wavelength (or energy, wavenumber etc.) values. + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + coating(NXsample): + doc: | + Is the wave plate coated? If yes, specify the type and material of the + coating and the wavelength range for which it is designed. If known, you + may also provide its index of refraction. + coating_type: + doc: | + Specify the coating type (e.g. dielectric, anti-reflection (AR), + multilayer coating etc.). + coating_material: + doc: | + Specify the coating material. + coating_thickness(NX_NUMBER): + unit: NX_LENGTH + doc: | + Thickness of the coating. + wavelength_range_coating(NX_NUMBER): + exists: recommended + doc: | + Wavelength range for which the coating is designed. Enter the minimum + and maximum values of the wavelength range. + dimensions: + rank: 1 + dim: [[1, 2]] + index_of_refraction_coating(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Complex index of refraction of the coating. Specify at given spectral + values (wavelength, energy, wavenumber etc.). + dimensions: + rank: 2 + dim: [[1, 2], [2, N_spectrum]] + reflectance(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Average reflectance of the waveplate in percentage. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1084311acf55f71d1555553d11d9c7d6ec2c8339916f54dd2ab1cc6aeabcf603 +# +# +# +# +# +# +# +# +# Size of the wavelength array for which the refractive index of the material +# and/or coating is given. +# +# +# +# +# Number of discrete wavelengths for which the waveplate is designed. If it +# operates for a range of wavelengths then N_wavelengths = 2 and the minimum +# and maximum values of the range should be provided. +# +# +# +# +# A waveplate or retarder. +# +# +# +# Type of waveplate (e.g. achromatic waveplate or zero-order waveplate). +# +# +# +# +# +# +# +# +# +# +# +# +# +# If you selected 'other' in type describe what it is. +# +# +# +# +# Specify the retardance of the waveplate (e.g. full-wave, half-wave +# (lambda/2), quarter-wave (lambda/4) plate). +# +# +# +# +# +# +# +# +# +# Discrete wavelengths for which the waveplate is designed. If the +# waveplate operates over an entire range of wavelengths, enter the minimum +# and maximum values of the wavelength range (in this case +# N_wavelengths = 2). +# +# +# +# +# +# +# +# Diameter of the waveplate. +# +# +# +# +# Clear aperture of the device (e.g. 90% of diameter for a disc or 90% of +# length/height for square geometry). +# +# +# +# +# +# Describe the material of the substrate of the wave plate in +# substrate/substrate_material and provide its index of refraction in +# substrate/index_of_refraction_substrate, if known. +# +# +# +# Specify the material of the wave plate. If the device has a +# coating it should be described in coating/coating_material. +# +# +# +# +# Thickness of the wave plate substrate. +# +# +# +# +# Complex index of refraction of the wave plate substrate. Specify at +# given wavelength (or energy, wavenumber etc.) values. +# +# +# +# +# +# +# +# +# +# Is the wave plate coated? If yes, specify the type and material of the +# coating and the wavelength range for which it is designed. If known, you +# may also provide its index of refraction. +# +# +# +# Specify the coating type (e.g. dielectric, anti-reflection (AR), +# multilayer coating etc.). +# +# +# +# +# Specify the coating material. +# +# +# +# +# Thickness of the coating. +# +# +# +# +# Wavelength range for which the coating is designed. Enter the minimum +# and maximum values of the wavelength range. +# +# +# +# +# +# +# +# Complex index of refraction of the coating. Specify at given spectral +# values (wavelength, energy, wavenumber etc.). +# +# +# +# +# +# +# +# +# +# Average reflectance of the waveplate in percentage. +# +# +# diff --git a/contributed_definitions/nyaml/NXxpcs.yaml b/contributed_definitions/nyaml/NXxpcs.yaml new file mode 100644 index 0000000000..20dd211c91 --- /dev/null +++ b/contributed_definitions/nyaml/NXxpcs.yaml @@ -0,0 +1,1085 @@ +category: application +doc: | + X-ray Photon Correlation Spectroscopy (XPCS) data (results). + + The purpose of ``NXxpcs`` is to document and communicate an accepted vernacular for various XPCS results data + in order to support development of community software tools. The definition presented here only + represents a starting point and contains fields that a common software tool should support for + community acceptance. + + Additional fields may be added to XPCS results file (either formally or informally). It is expected + that this XPCS data will be part of multi-modal data set that could involve e.g., :ref:`NXcanSAS` or + 1D and/or 2D data. +symbols: + doc: | + The symbol(s) listed here will be used below to coordinate datasets with the same shape. + nP: | + Number of points +type: group +NXxpcs(NXobject): + (NXentry)entry: + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxpcs] + entry_identifier: + doc: | + **Locally** unique identifier for the experiment (a.k.a. run or scan). + + * For bluesky users, this is the run's `"scan_id"`. + * For SPEC users, this is the scan number (``SCAN_N``). + entry_identifier_uuid: + exists: ['min', '0', 'max', '1'] + doc: | + (optional) UUID identifier for this entry. + + See the `UUID standard `__ (or + `wikipedia `__) + for more information. + + * For `bluesky `__ users, this is the + run's `"uid"` and is expected for that application. + * Typically, `SPEC `__ users will + not use this field without further engineering. + scan_number(NX_INT): + deprecated: Use the ``entry_identifier`` field. + + # Use of "deprecated" is to advise the XPCS authors of this change. + # The `scan_number` field will be removed by 2022-12-31. + doc: | + Scan number (must be an integer). + + NOTE: Link to collection_identifier. + start_time(NX_DATE_TIME): + doc: | + Starting time of experiment, such as "2021-02-11 11:22:33.445566Z". + end_time(NX_DATE_TIME): + exists: ['min', '0', 'max', '1'] + doc: | + Ending time of experiment, such as "2021-02-11 11:23:45Z". + (NXdata)data: + doc: | + The results data captured here are most commonly required for high throughput, equilibrium dynamics experiments. Data (results) + describing on-equilibrium dynamics consume more memory resources so these data are separated. + frame_sum(NX_NUMBER): + unit: NX_COUNT + exists: ['min', '0', 'max', '1'] + doc: | + Two-dimensional summation along the frames stack. + + sum of intensity v. time (in the units of "frames") + frame_average(NX_NUMBER): + unit: NX_COUNT + exists: ['min', '0', 'max', '1'] + doc: | + Two-dimensional average along the frames stack. + + average intensity v. time (in the units of "frames") + g2(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + normalized intensity auto-correlation function, see Lumma, Rev. Sci. Instr. (2000), Eq 1 + + .. math:: g_2(\boldsymbol Q,t) = \frac{ \langle I(\boldsymbol Q,t\prime) I(\boldsymbol Q,t\prime + t) \rangle }{ \langle I(\boldsymbol Q,t\prime)\rangle^2 }; t > 0 + + Typically, :math:`g_2` is a quantity calculated for a group of pixels representing a specific + region of reciprocal space. These groupings, or bins, are generically described as :math:`q`. Some + open-source XPCS libraries refer to these bins as "rois", which are not to be confused with + EPICS AreaDetector ROI. See usage guidelines for q_lists and roi_maps within a mask. [#]_ + + In short, :math:`g_2` should be ordered according to the roi_map value. In principle, any format is acceptable if + the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one + of the following two formats: + + * iterable list of linked files (or keys) for each :math:`g_2` with 1 file (key) per :math:`q`, where `q` is called by the nth roi_map value + * 2D array [#]_ with shape (:math:`g_2`, :math:`q`), where `q` is represented by the nth roi_map value, not the value `q` value + + Note it is expected that "g2" and all quantities following it will be of the same length. + + Other formats are acceptable with sufficient axes description. + + See references below for related implementation information: + + .. [#] mask: ``NXxpcs:/entry/instrument/masks-group`` + .. [#] NeXus 2-D data and axes: https://manual.nexusformat.org/classes/base_classes/NXdata.html#nxdata + \@storage_mode: + type: NX_CHAR + doc: | + storage_mode describes the format of the data to be loaded + + We encourage the documentation of other formats not represented here. + + * one array representing entire data set ("one_array") + * data exchange format with each key representing one ``q`` by its corresponding roi_map value ("data_exchange_keys") + enumeration: [one_array, data_exchange_keys, other] + g2_derr(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + error values for the :math:`g_2` values. + + The derivation of the error is left up to the implemented code. Symmetric error will be + expected (:math:`\pm` error). The data should be in the same format as ``g2``. + \@storage_mode: + type: NX_CHAR + enumeration: [one_array, data_exchange_keys, other] + G2_unnormalized(NX_NUMBER): + unit: NX_ANY + exists: ['min', '0', 'max', '1'] + doc: | + unnormalized intensity auto-correlation function. + + Specifically, ``g2`` without the denominator. The data should be in the same format as ``g2``. + \@storage_mode: + type: NX_CHAR + enumeration: [one_array, data_exchange_keys, other] + delay_difference(NX_INT): + unit: NX_COUNT + exists: ['min', '0', 'max', '1'] + doc: | + delay_difference (also known as delay or lag step) + + This is quantized difference so that the "step" between two consecutive + frames is one frame (or step ``= dt = 1 frame``) + + It is the "quantized" delay time corresponding to the ``g2`` values. + + The unit of delay_differences is ``NX_INT`` for units of frames (i.e., integers) preferred, + refer to :ref:`NXdetector` for conversion to time units. + \@storage_mode: + type: NX_CHAR + enumeration: [one_array, data_exchange_keys, other] + (NXdata)twotime: + exists: ['min', '0'] + doc: | + The data (results) in this section are based on the two-time intensity correlation function derived from a time series of scattering images. + two_time_corr_func(NX_NUMBER): + unit: NX_ANY + exists: ['min', '0', 'max', '1'] + doc: | + two-time correlation of speckle intensity for a given q-bin or roi (represented by the nth roi_map value) + + See Fluerasu, Phys Rev E (2007), Eq 1 and Sutton, Optics Express (2003) for an early + description applied to X-ray scattering: + + .. math:: C(\boldsymbol Q, t_1, t_2) = \frac{ \langle I(\boldsymbol Q, t_1)I(\boldsymbol Q, t_2)\rangle }{ \langle I(\boldsymbol Q,t_1)\rangle \langle I(\boldsymbol Q,t_2)\rangle } + + in which time is quantized by frames. In principle, any data format is acceptable if + the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one + of the following two formats: + + * iterable list of linked files (or keys) for each q-bin called by the nth roi_map value. data for each bin is a 2D array + * 3D array with shape (frames, frames, q) or (q, frames, frames), where :math:`q` is represented by the nth roi_map value, not the value `q` value + + + The computation of this result can be customized. These customizations can affect subsequently derived results (below). The + following attributes will be used to manage the customization. + + * Other normalization methods may be applied, but the method will not be specified in this + definition. Some of these normalization methods result in a baseline value of ``0``, not ``1``. + + * The various software libraries use different programming languages. Therefore, we need to + specify the ``time = 0`` origin location of the 2D array for each :math:`q`. + + * A method to reduce data storage needs is to only record half of the 2D array by populating + array elements above or below the array diagonal. + \@storage_mode: + type: NX_CHAR + doc: | + storage_mode describes the format of the data to be loaded + + We encourage the documention of other formats represented here. + enumeration: [one_array_q_first, one_array_q_last, data_exchange_keys, other] + \@baseline_reference: + type: NX_INT + doc: | + baseline is the expected value of a full decorrelation + + The baseline is a constant value added to the functional form of the auto-correlation + function. This value is required. + enumeration: [0, 1] + \@time_origin_location: + type: NX_CHAR + doc: | + time_origin_location is the location of the origin + enumeration: [upper_left, lower_left] + \@populated_elements: + type: NX_CHAR + doc: | + populated_elements describe the elements of the 2D array that are populated with data + enumeration: [all, upper_half, lower_half] + g2_from_two_time_corr_func(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + frame weighted average along the diagonal direction in ``two_time_corr_func`` + + The data format and description should be consistent with that found in "/NXxpcs/entry/data/g2" + + * iterable list of linked files for each :math:`g_2` with 1 file per :math:`q` + * 2D array with shape (:math:`g_2`, :math:`q`) + + Note that delay_difference is not included here because it is derived from the shape of + extracted :math:`g_2` because all frames are considered, which is not necessarily the case for :math:`g_2`. + + The computation of this result can be customized. The customization can affect the fitting required to extract quantitative results. The + following attributes will be used to manage the customization. + \@storage_mode: + type: NX_CHAR + enumeration: [one_array_q_first, one_array_q_last, data_exchange_keys, other] + \@baseline_reference: + type: NX_INT + enumeration: [0, 1] + \@first_point_for_fit: + type: NX_INT + doc: | + first_point_for_fit describes if the first point should or should not be used in fitting the functional form of the dynamics to extract quantitative time-scale information. + + The first_point_for_fit is True ("1") or False ("0"). This value is required. + enumeration: [0, 1] + g2_err_from_two_time_corr_func(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + error values for the :math:`g_2` values. + + The derivation of the error is left up to the implemented code. Symmetric error will be + expected (:math:`\pm` error). + \@storage_mode: + type: NX_CHAR + enumeration: [one_array_q_first, one_array_q_last, data_exchange_keys, other] + g2_from_two_time_corr_func_partials(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + subset of frame weighted average along the diagonal direction in ``two_time_corr_func`` + + Time slicing along the diagonal can be very sophisticated. This entry currently assumes + equal frame-binning. The data formats are highly dependent on the implantation of various analysis libraries. + In principle, any data format is acceptable if the data and its axes are self describing as per NeXus + recommendations. However, the data is preferred in one of the following two formats: + + * iterable list of linked files (or keys) for each partial :math:`g_2` of each q-bin represented by the roi_map value + * 3D array with shape (:math:`g_2`, :math:`q`, nth_partial) + + Note that delay_difference is not included here because it is derived from the shape of + extracted :math:`g_2`. + \@storage_mode: + type: NX_CHAR + enumeration: [one_array, data_exchange_keys, other] + \@baseline_reference: + type: NX_INT + enumeration: [0, 1] + g2_err_from_two_time_corr_func_partials(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0', 'max', '1'] + doc: | + error values for the :math:`g_2` values. + + The derivation of the error is left up to the implemented code. Symmetric error will be + expected (:math:`\pm` error). + (NXinstrument)instrument: + doc: | + XPCS instrument Metadata. + + Objects can be entered here directly or linked from other + objects in the NeXus file (such as within ``/entry/instrument``). + (NXbeam)incident_beam: + incident_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Incident beam line energy (either keV or eV). + incident_energy_spread(NX_FLOAT): + unit: NX_ENERGY + exists: ['min', '0', 'max', '1'] + doc: | + Spread of incident beam line energy (either keV or eV). This quantity is otherwise known + as the energy resolution, which is related to the longitudinal coherence length. + incident_polarization_type: + exists: ['min', '0', 'max', '1'] + doc: | + Terse description of the incident beam polarization. + + The value can be plain text, such as ``vertical``, ``C+``, + ``circular left``. + extent(NX_FLOAT): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Size (2-D) of the beam at this position. + + # FIXME: (h, v) or (v, h)? State this in the docs FOR EPICS AD, likeky v, h. But seems CSX is (h,v) if looking + # from the source's perspective at the face of the detector - see fig 11 and fig 12 of cxidb documentation. this + # is also relevant for the next section, which is just describing the 2D array V, H is python/bluesky + (NXdetector): + doc: | + XPCS data is typically produced by area detector (likely EPICS AreaDetector) as a stack of 2D images. Sometimes + this data is represented in different ways (sparse arrays or photon event list), but this detail + is left to the analysis software. Therefore, we only include requirements based on full array data. + + We note that the image origin (pixel coordinates (0,0)) are found at the top left of a single 2D image array. This + is the standard expected by Coherent X-ray Imaging Data Bank. [#]_ + See CXI version 1.6 and Maia, Nature Methods (2012). This seems to be consistent with matplotlib and + the practiced implementation of EPICS AreaDetector. However, some exceptions may exists in the CXI + documentation (See Fig 11 vs Fig 12). + + Additionally, not all :ref:`NXdetector` dependencies are inherited from AreaDetector or other control systems. ``frame_time`` is used to + convert ``delay_difference`` to seconds. ``frame_time`` field could be missing from AreaDetector or may + either be `acquire_period` or `acquire_time`, depending on the detector model and the local implementation. + + .. [#] Coherent X-ray Imaging Data Bank: https://cxidb.org/cxi.html + description: + exists: ['min', '0', 'max', '1'] + doc: | + Detector name. + distance(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Distance between sample and detector. + count_time(NX_NUMBER): + unit: NX_TIME + doc: | + Exposure time of frames, s. + frame_time(NX_NUMBER): + unit: NX_TIME + doc: | + Exposure period (time between frame starts) of frames, s + beam_center_x(NX_NUMBER): + unit: NX_LENGTH + doc: | + Position of beam center, x axis, in detector's coordinates. + beam_center_y(NX_NUMBER): + unit: NX_LENGTH + doc: | + Position of beam center, y axis, in detector's coordinates. + x_pixel_size(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + + # made this optional in case of single photon xy-time lists + doc: | + Length of pixel in x direction. + y_pixel_size(NX_NUMBER): + unit: NX_LENGTH + exists: ['min', '0', 'max', '1'] + doc: | + Length of pixel in y direction. + (NXnote)masks: + exists: ['min', '0', 'max', '1'] + doc: | + Data masks or mappings to regions of interest (roi) for specific :math:`Q` values + + Fields in this ``masks`` group describe regions of interest + in the data by either a mask to select pixels or to associate + a *map* of rois with a (one-dimensional) *list* of values. + + "roi_maps" provide for representation of pixel binning that are arbitrary and irregular, + which is geometry scattering agnostic and most flexible. The maps work as a labeled array for N rois. + + "Dynamic" represents quantities directly related to XPCS and NXxcps/entry/data and + NXxpcs/entry/two_time. + + "Static" refers to finer binning used for computation not strictly used for the final + XPCS results. Implementation of _static_ binning is left for individual libraries to + document. We encourage usage of :ref:`NXcanSAS` to represent standard SAXS results or + development of new NeXus definitions for GI-SAXS or other reciprocal space + intensity mapping. + dynamic_roi_map(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + roi index array or labeled array + + The values of this mask index (or map to) the :math:`Q` value from the + the ``dynamic_q_list`` field. Not that the value of ``0`` represents in-action. XPCS computations + are performed on all pixels with a value > 0. + + The ``units`` attribute should be set to ``"au"`` + indicating arbitrary units. + dynamic_q_list(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + 1-D list of :math:`Q` values, one for each roi index value. + + List order is determined by the index value of the associated roi map starting at ``1``. + + The only requirement for the list is that it may be iterable. Some expected formats are: + + * iterable list of floats (i.e., :math:`Q(r)`) + * iterable list of tuples (i.e., :math:`Q(r)`, :math:`\varphi`), but preferable use the seperate :math:`\varphi` field below + * iterable list of tuples (e.g., (H, K, L); (qx, qy, qz); (horizontal_pixel, vertical_pixel)) + * iterable list of integers (for Nth roi_map value) or strings + + This format is chosen because results plotting packages are not common and simple I/O is required by end user. + The lists can be accessed as lists, arrays or via keys + dynamic_phi_list(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + Array of :math:`\varphi` value for each pixel. + + List order is determined by the index value of the associated roi map starting at ``1``. + static_roi_map(NX_NUMBER): + unit: NX_DIMENSIONLESS + exists: ['min', '0'] + doc: | + roi index array. + + The values of this mask index the :math:`|Q|` value from the + the ``static_q_list`` field. + + The ``units`` attribute should be set to ``"au"`` + indicating arbitrary units. + static_q_list(NX_NUMBER): + unit: NX_PER_LENGTH + exists: ['min', '0'] + doc: | + 1-D list of :math:`|Q|` values, 1 for each roi. + (NXsample)sample: + exists: ['min', '0'] + + # Describes the minimum requirements regarding equilibrium sample conditions. NXsample + # permits other quantities (e.g., applied fields, crystallographic information, name, etc) that + # may optionally be include for equilibrium conditions (which is not exclusively equilibrium + # dynamics from XPCS analysis). + # For non-equilibrium sample conditions (i.e., changing sample or process conditions + # during the XPCS measurement) will require either a new entry or an additional atttribute. + temperature_set(NX_NUMBER): + unit: NX_TEMPERATURE + exists: ['min', '0'] + doc: | + Sample temperature setpoint, (C or K). + temperature(NX_NUMBER): + unit: NX_TEMPERATURE + exists: ['min', '0'] + doc: | + Sample temperature actual, (C or K). + (NXpositioner)position_x: + exists: ['min', '0'] + (NXpositioner)position_y: + exists: ['min', '0'] + (NXpositioner)position_z: + exists: ['min', '0'] + (NXnote)NOTE: + exists: ['min', '0', 'max', 'unbounded'] + doc: | + Any other notes. + + NAME: The NeXus convention, to use all upper case + to indicate the name (here ``NOTE``), is left to the file + writer. In our case, follow the suggested name + pattern and sequence: note_1, note_2, note_3, ... + Start with ``note_1`` if the first one, otherwise + pick the next number in this sequence. + (NXprocess): + doc: | + Describe the computation process that produced these results. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 24b656b7be7f0c85955748deed904585a8136c312327d128d6a4a377760052c8 +# +# +# +# +# +# +# The symbol(s) listed here will be used below to coordinate datasets with the same shape. +# +# +# Number of points +# +# +# +# X-ray Photon Correlation Spectroscopy (XPCS) data (results). +# +# The purpose of ``NXxpcs`` is to document and communicate an accepted vernacular for various XPCS results data +# in order to support development of community software tools. The definition presented here only +# represents a starting point and contains fields that a common software tool should support for +# community acceptance. +# +# Additional fields may be added to XPCS results file (either formally or informally). It is expected +# that this XPCS data will be part of multi-modal data set that could involve e.g., :ref:`NXcanSAS` or +# 1D and/or 2D data. +# +# +# +# Official NeXus NXDL schema to which this file conforms +# +# +# +# +# +# +# +# **Locally** unique identifier for the experiment (a.k.a. run or scan). +# +# * For bluesky users, this is the run's `"scan_id"`. +# * For SPEC users, this is the scan number (``SCAN_N``). +# +# +# +# +# (optional) UUID identifier for this entry. +# +# See the `UUID standard <https://www.rfc-editor.org/rfc/rfc4122.html>`__ (or +# `wikipedia <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__) +# for more information. +# +# * For `bluesky <https://blueskyproject.io/>`__ users, this is the +# run's `"uid"` and is expected for that application. +# * Typically, `SPEC <https://certif.com/content/spec/>`__ users will +# not use this field without further engineering. +# +# +# +# +# +# Scan number (must be an integer). +# +# NOTE: Link to collection_identifier. +# +# +# +# +# Starting time of experiment, such as "2021-02-11 11:22:33.445566Z". +# +# +# +# +# Ending time of experiment, such as "2021-02-11 11:23:45Z". +# +# +# +# +# +# The results data captured here are most commonly required for high throughput, equilibrium dynamics experiments. Data (results) +# describing on-equilibrium dynamics consume more memory resources so these data are separated. +# +# +# +# Two-dimensional summation along the frames stack. +# +# sum of intensity v. time (in the units of "frames") +# +# +# +# +# Two-dimensional average along the frames stack. +# +# average intensity v. time (in the units of "frames") +# +# +# +# +# normalized intensity auto-correlation function, see Lumma, Rev. Sci. Instr. (2000), Eq 1 +# +# .. math:: g_2(\boldsymbol Q,t) = \frac{ \langle I(\boldsymbol Q,t\prime) I(\boldsymbol Q,t\prime + t) \rangle }{ \langle I(\boldsymbol Q,t\prime)\rangle^2 }; t > 0 +# +# Typically, :math:`g_2` is a quantity calculated for a group of pixels representing a specific +# region of reciprocal space. These groupings, or bins, are generically described as :math:`q`. Some +# open-source XPCS libraries refer to these bins as "rois", which are not to be confused with +# EPICS AreaDetector ROI. See usage guidelines for q_lists and roi_maps within a mask. [#]_ +# +# In short, :math:`g_2` should be ordered according to the roi_map value. In principle, any format is acceptable if +# the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one +# of the following two formats: +# +# * iterable list of linked files (or keys) for each :math:`g_2` with 1 file (key) per :math:`q`, where `q` is called by the nth roi_map value +# * 2D array [#]_ with shape (:math:`g_2`, :math:`q`), where `q` is represented by the nth roi_map value, not the value `q` value +# +# Note it is expected that "g2" and all quantities following it will be of the same length. +# +# Other formats are acceptable with sufficient axes description. +# +# See references below for related implementation information: +# +# .. [#] mask: ``NXxpcs:/entry/instrument/masks-group`` +# .. [#] NeXus 2-D data and axes: https://manual.nexusformat.org/classes/base_classes/NXdata.html#nxdata +# +# +# +# storage_mode describes the format of the data to be loaded +# +# We encourage the documentation of other formats not represented here. +# +# * one array representing entire data set ("one_array") +# * data exchange format with each key representing one ``q`` by its corresponding roi_map value ("data_exchange_keys") +# +# +# +# +# +# +# +# +# +# +# error values for the :math:`g_2` values. +# +# The derivation of the error is left up to the implemented code. Symmetric error will be +# expected (:math:`\pm` error). The data should be in the same format as ``g2``. +# +# +# +# +# +# +# +# +# +# +# +# unnormalized intensity auto-correlation function. +# +# Specifically, ``g2`` without the denominator. The data should be in the same format as ``g2``. +# +# +# +# +# +# +# +# +# +# +# +# +# delay_difference (also known as delay or lag step) +# +# This is quantized difference so that the "step" between two consecutive +# frames is one frame (or step ``= dt = 1 frame``) +# +# It is the "quantized" delay time corresponding to the ``g2`` values. +# +# The unit of delay_differences is ``NX_INT`` for units of frames (i.e., integers) preferred, +# refer to :ref:`NXdetector` for conversion to time units. +# +# +# +# +# +# +# +# +# +# +# +# +# +# The data (results) in this section are based on the two-time intensity correlation function derived from a time series of scattering images. +# +# +# +# two-time correlation of speckle intensity for a given q-bin or roi (represented by the nth roi_map value) +# +# See Fluerasu, Phys Rev E (2007), Eq 1 and Sutton, Optics Express (2003) for an early +# description applied to X-ray scattering: +# +# .. math:: C(\boldsymbol Q, t_1, t_2) = \frac{ \langle I(\boldsymbol Q, t_1)I(\boldsymbol Q, t_2)\rangle }{ \langle I(\boldsymbol Q,t_1)\rangle \langle I(\boldsymbol Q,t_2)\rangle } +# +# in which time is quantized by frames. In principle, any data format is acceptable if +# the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one +# of the following two formats: +# +# * iterable list of linked files (or keys) for each q-bin called by the nth roi_map value. data for each bin is a 2D array +# * 3D array with shape (frames, frames, q) or (q, frames, frames), where :math:`q` is represented by the nth roi_map value, not the value `q` value +# +# +# The computation of this result can be customized. These customizations can affect subsequently derived results (below). The +# following attributes will be used to manage the customization. +# +# * Other normalization methods may be applied, but the method will not be specified in this +# definition. Some of these normalization methods result in a baseline value of ``0``, not ``1``. +# +# * The various software libraries use different programming languages. Therefore, we need to +# specify the ``time = 0`` origin location of the 2D array for each :math:`q`. +# +# * A method to reduce data storage needs is to only record half of the 2D array by populating +# array elements above or below the array diagonal. +# +# +# +# +# +# storage_mode describes the format of the data to be loaded +# +# We encourage the documention of other formats represented here. +# +# +# +# +# +# +# +# +# +# +# baseline is the expected value of a full decorrelation +# +# The baseline is a constant value added to the functional form of the auto-correlation +# function. This value is required. +# +# +# +# +# +# +# +# +# time_origin_location is the location of the origin +# +# +# +# +# +# +# +# +# populated_elements describe the elements of the 2D array that are populated with data +# +# +# +# +# +# +# +# +# +# +# frame weighted average along the diagonal direction in ``two_time_corr_func`` +# +# The data format and description should be consistent with that found in "/NXxpcs/entry/data/g2" +# +# * iterable list of linked files for each :math:`g_2` with 1 file per :math:`q` +# * 2D array with shape (:math:`g_2`, :math:`q`) +# +# Note that delay_difference is not included here because it is derived from the shape of +# extracted :math:`g_2` because all frames are considered, which is not necessarily the case for :math:`g_2`. +# +# The computation of this result can be customized. The customization can affect the fitting required to extract quantitative results. The +# following attributes will be used to manage the customization. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# first_point_for_fit describes if the first point should or should not be used in fitting the functional form of the dynamics to extract quantitative time-scale information. +# +# The first_point_for_fit is True ("1") or False ("0"). This value is required. +# +# +# +# +# +# +# +# +# +# error values for the :math:`g_2` values. +# +# The derivation of the error is left up to the implemented code. Symmetric error will be +# expected (:math:`\pm` error). +# +# +# +# +# +# +# +# +# +# +# +# +# subset of frame weighted average along the diagonal direction in ``two_time_corr_func`` +# +# Time slicing along the diagonal can be very sophisticated. This entry currently assumes +# equal frame-binning. The data formats are highly dependent on the implantation of various analysis libraries. +# In principle, any data format is acceptable if the data and its axes are self describing as per NeXus +# recommendations. However, the data is preferred in one of the following two formats: +# +# * iterable list of linked files (or keys) for each partial :math:`g_2` of each q-bin represented by the roi_map value +# * 3D array with shape (:math:`g_2`, :math:`q`, nth_partial) +# +# Note that delay_difference is not included here because it is derived from the shape of +# extracted :math:`g_2`. +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# +# error values for the :math:`g_2` values. +# +# The derivation of the error is left up to the implemented code. Symmetric error will be +# expected (:math:`\pm` error). +# +# +# +# +# +# +# XPCS instrument Metadata. +# +# Objects can be entered here directly or linked from other +# objects in the NeXus file (such as within ``/entry/instrument``). +# +# +# +# Incident beam line energy (either keV or eV). +# +# +# +# Spread of incident beam line energy (either keV or eV). This quantity is otherwise known +# as the energy resolution, which is related to the longitudinal coherence length. +# +# +# +# +# Terse description of the incident beam polarization. +# +# The value can be plain text, such as ``vertical``, ``C+``, +# ``circular left``. +# +# +# +# Size (2-D) of the beam at this position. +# +# +# +# +# +# +# XPCS data is typically produced by area detector (likely EPICS AreaDetector) as a stack of 2D images. Sometimes +# this data is represented in different ways (sparse arrays or photon event list), but this detail +# is left to the analysis software. Therefore, we only include requirements based on full array data. +# +# We note that the image origin (pixel coordinates (0,0)) are found at the top left of a single 2D image array. This +# is the standard expected by Coherent X-ray Imaging Data Bank. [#]_ +# See CXI version 1.6 and Maia, Nature Methods (2012). This seems to be consistent with matplotlib and +# the practiced implementation of EPICS AreaDetector. However, some exceptions may exists in the CXI +# documentation (See Fig 11 vs Fig 12). +# +# Additionally, not all :ref:`NXdetector` dependencies are inherited from AreaDetector or other control systems. ``frame_time`` is used to +# convert ``delay_difference`` to seconds. ``frame_time`` field could be missing from AreaDetector or may +# either be `acquire_period` or `acquire_time`, depending on the detector model and the local implementation. +# +# .. [#] Coherent X-ray Imaging Data Bank: https://cxidb.org/cxi.html +# +# +# Detector name. +# +# +# Distance between sample and detector. +# +# +# Exposure time of frames, s. +# +# +# +# Exposure period (time between frame starts) of frames, s +# +# +# +# +# Position of beam center, x axis, in detector's coordinates. +# +# +# +# +# Position of beam center, y axis, in detector's coordinates. +# +# +# +# +# +# Length of pixel in x direction. +# +# +# +# +# Length of pixel in y direction. +# +# +# +# +# +# +# Data masks or mappings to regions of interest (roi) for specific :math:`Q` values +# +# Fields in this ``masks`` group describe regions of interest +# in the data by either a mask to select pixels or to associate +# a *map* of rois with a (one-dimensional) *list* of values. +# +# "roi_maps" provide for representation of pixel binning that are arbitrary and irregular, +# which is geometry scattering agnostic and most flexible. The maps work as a labeled array for N rois. +# +# "Dynamic" represents quantities directly related to XPCS and NXxcps/entry/data and +# NXxpcs/entry/two_time. +# +# "Static" refers to finer binning used for computation not strictly used for the final +# XPCS results. Implementation of _static_ binning is left for individual libraries to +# document. We encourage usage of :ref:`NXcanSAS` to represent standard SAXS results or +# development of new NeXus definitions for GI-SAXS or other reciprocal space +# intensity mapping. +# +# +# +# roi index array or labeled array +# +# The values of this mask index (or map to) the :math:`Q` value from the +# the ``dynamic_q_list`` field. Not that the value of ``0`` represents in-action. XPCS computations +# are performed on all pixels with a value > 0. +# +# The ``units`` attribute should be set to ``"au"`` +# indicating arbitrary units. +# +# +# +# +# 1-D list of :math:`Q` values, one for each roi index value. +# +# List order is determined by the index value of the associated roi map starting at ``1``. +# +# The only requirement for the list is that it may be iterable. Some expected formats are: +# +# * iterable list of floats (i.e., :math:`Q(r)`) +# * iterable list of tuples (i.e., :math:`Q(r)`, :math:`\varphi`), but preferable use the seperate :math:`\varphi` field below +# * iterable list of tuples (e.g., (H, K, L); (qx, qy, qz); (horizontal_pixel, vertical_pixel)) +# * iterable list of integers (for Nth roi_map value) or strings +# +# This format is chosen because results plotting packages are not common and simple I/O is required by end user. +# The lists can be accessed as lists, arrays or via keys +# +# +# +# +# Array of :math:`\varphi` value for each pixel. +# +# List order is determined by the index value of the associated roi map starting at ``1``. +# +# +# +# +# roi index array. +# +# The values of this mask index the :math:`|Q|` value from the +# the ``static_q_list`` field. +# +# The ``units`` attribute should be set to ``"au"`` +# indicating arbitrary units. +# +# +# +# +# 1-D list of :math:`|Q|` values, 1 for each roi. +# +# +# +# +# +# +# +# +# +# Sample temperature setpoint, (C or K). +# +# +# +# +# Sample temperature actual, (C or K). +# +# +# +# +# +# +# +# +# +# Any other notes. +# +# NAME: The NeXus convention, to use all upper case +# to indicate the name (here ``NOTE``), is left to the file +# writer. In our case, follow the suggested name +# pattern and sequence: note_1, note_2, note_3, ... +# Start with ``note_1`` if the first one, otherwise +# pick the next number in this sequence. +# +# +# +# +# +# +# Describe the computation process that produced these results. +# +# +# diff --git a/contributed_definitions/nyaml/NXxrd.yaml b/contributed_definitions/nyaml/NXxrd.yaml new file mode 100644 index 0000000000..2b9cbf9c54 --- /dev/null +++ b/contributed_definitions/nyaml/NXxrd.yaml @@ -0,0 +1,59 @@ +category: base +doc: | + NXxrd on top of NXmonopd +# ! : additions +# ? : could or should be modified? +type: group +NXxrd(NXmonopd): + (NXentry): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms + enumeration: [NXxrd] + (NXinstrument): + exists: optional + (NXbeam): + incident_energy(NX_FLOAT): + unit: NX_ENERGY + (NXdetector): + raw_data(NXdata): + exists: optional + doc: | + raw detector signal (usually counts) as colected + it can be a multi-dimensional dataset depending on + the detector type (faster axes) and + the scanning method (slower axes) + polar_angle(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + unit: NX_ANGLE + doc: | + The 2-theta range of the difractogram + \@units: + enumeration: [deg] + (NXdata): + polar_angle(NX_FLOAT): + doc: | + link (suggested target:/NXentry/NXinstrument/NXdetector/polar_angle) + Link to ponglar ale in /NXentry/NXinstrument/NXdetector + dimensions: + rank: 1 + dim: [[1, nDet]] + data(NX_NUMBER): + doc: | + link (suggested target:/NXentry/NXinstrument/NXdetector/data) + Link to data in /Nxentry/Nxinstrument/Nxdetector + dimensions: + rank: 1 + dim: [[1, nDet]] + (NXprocess): + exists: optional + doc: | + Description of a processing or analysis step, such as the + baseline extraction or azimuth integration. + Add additional fields as needed to describe value(s) of + any variable, parameter, or term related to + the NXprocess step. Be sure to include units attributes + for all numerical fields. + diff --git a/contributed_definitions/nyaml/NXxrd_pan.yaml b/contributed_definitions/nyaml/NXxrd_pan.yaml new file mode 100644 index 0000000000..8314a7f160 --- /dev/null +++ b/contributed_definitions/nyaml/NXxrd_pan.yaml @@ -0,0 +1,198 @@ +category: application +doc: | + NXxrd_pan is a specialisation of NXxrd with exptra properties +# n_values - symbols +# ! : additions +# ? : could or should be modified? +type: "group" +NXxrd_pan(NXxrd): + (NXentry): + definition: + doc: | + Official NeXus NXDL schema to which this file conforms. + enumeration: [NXxrd_pan] + method: + enumeration: [X-Ray Diffraction (XRD)] + doc: | + Method used to collect the data + default='X-Ray Diffraction (XRD)' + (NXinstrument): + # Need a group that explain + (NXsource): + xray_tube_material: + doc: | + Type of the X-ray tube. + enumeration: [Cu, Cr, Mo, Fe, Ag, In, Ga] + xray_tube_current(NX_FLOAT): + unit: NX_CURRENT + doc: | + Current of the X-ray tube. + xray_tube_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Voltage of the X-ray tube. + # Unicode for alpha : \u03b1 + k_alpha_one(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Wavelength of the K\u03b1 1 line. + \@units: + enumeration: [angstrom] + k_alpha_two(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + Wavelength of the K\u03b1 2 line. + \@units: + enumeration: [angstrom] + ratio_k_alphatwo_k_alphaone(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + K\u03b1 2/K\u03b1 1 intensity ratio. + kbeta(NX_FLOAT): + exists: optional + unit: NX_WAVELENGTH + doc: | + Wavelength of the K\u00df line. + \@units: + enumeration: [angstrom] + source_peak_wavelength(NX_FLOAT): + exists: optional + unit: NX_WAVELENGTH + doc: | + Wavelength of the X-ray source. Used to convert from 2-theta to Q. + (NXdetector): + scan_axis: + doc: | + Axis scanned. + scan_mode: + doc: | + Mode of scan. + integration_time(NX_FLOAT): + exists: optional + unit: NX_TIME + doc: | + Integration time per channel. + # Note: We should need to think about incident and deflected beam (NXbeam). As the data also contains + # beams information about the beam and the object encountered by beam through the path + # incident_beam(NXbeam): + # defracted_beam(NXbeam): + (NXcollection): + exists: optional + doc: | + Collect user inputs e.g. name or path of the input file. + 2theta(NXcollection): + start(NX_FLOAT): + unit: NX_ANGLE + doc: | + Starting value of the diffraction angle. + end(NX_FLOAT): + unit: NX_ANGLE + doc: | + Ending value of the diffraction angle. + step(NX_FLOAT): + unit: NX_ANGLE + doc: | + Minimum step size in-between two diffraction angles. + omega(NXcollection): + start(NX_FLOAT): + unit: NX_ANGLE + doc: | + Starting value of the incident angle. + end(NX_FLOAT): + unit: NX_ANGLE + doc: | + Ending value of the incident angle. + step(NX_FLOAT): + unit: NX_ANGLE + doc: | + Minimum step size in the between two incident angles. + data_file: + exists: optional + doc: | + Name of the data file. + measurement_type: + doc: | + Type of measurement. + beam_attenuation_factors: + doc: | + Beam attenuation factors over the path. + goniometer_x(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Goniometer position X. + goniometer_y(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Goniometer position Y. + goniometer_z(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Goniometer position Z + count_time(NX_FLOAT): + unit: NX_TIME + doc: | + Total time of count. + 2theta_plot(NXdata): + doc: | + Desired plot would be two_theta vs intensity. + intensity(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + doc: | + Number of scattered electrons per unit time. + two_theta(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + doc: | + Axis scale represeting the 2-theta range of the difractogram. + omega(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + exists: optional + doc: | + The omega range of the difractogram. + phi(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + exists: optional + doc: | + The phi range of the difractogram + chi(NX_FLOAT): + dimensions: + rank: 1 + dim: [[1, nDet]] + exists: optional + doc: | + The chi range of the difractogram + q_plot(NXdata): + exists: optional + doc: | + Desired plot would be q_vector vs intensity. + q(NX_FLOAT): + doc: | + Axis scale representing wavevector for scatter energy. + intensity(NX_FLOAT): + doc: | + Number of scattered electrons per unit time. + (NXsample): + exists: optional + doc: | + Description on sample. + sample_mode: + doc: | + Mode of sample. + sample_id: + doc: | + Id of sample. + sample_name: + doc: | + Usually in xrd sample are being analysed, but sample might be identified by assumed name or given name. + prepared_by: + doc: | diff --git a/dev_tools/apps/manual_app.py b/dev_tools/apps/manual_app.py index 768332b58d..dfb2c1b824 100644 --- a/dev_tools/apps/manual_app.py +++ b/dev_tools/apps/manual_app.py @@ -8,7 +8,6 @@ from ..nxdl import validate_definition from ..utils.copy import copy_files from ..utils.copy import copydir -from ..utils.copy import download_files from ..utils.diff import diff_ascii from .nxclass_app import diff_nxclass_docs from .nxclass_app import save_nxclass_docs @@ -113,26 +112,9 @@ def manual_exec(args): print("generate anchor list files in", output_path) anchor_registry.write() copy_files(EXTRA_FILES) - download_files(EXTRA_URLS) # Path relative to source directory, # Path relative to build directory, # Overwrite (boolean) EXTRA_FILES = [["NXDL_VERSION", "NXDL_VERSION", True], ["LGPL.txt", "LGPL.txt", True]] - -# URL, -# Path relative to build directory, -# Overwrite (boolean) -EXTRA_URLS = [ - [ - "https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf", - "manual/source/_static/NeXusIntern.pdf", - False, - ], - [ - "https://github.com/nexusformat/code/raw/master/applications/NXtranslate/docs/NXtranslate.pdf", - "manual/source/_static/NXtranslate.pdf", - False, - ], -] diff --git a/dev_tools/docs/nxdl.py b/dev_tools/docs/nxdl.py old mode 100644 new mode 100755 index 8da3ebbc05..109ec5d872 --- a/dev_tools/docs/nxdl.py +++ b/dev_tools/docs/nxdl.py @@ -12,9 +12,15 @@ from ..globals.errors import NXDLParseError from ..globals.nxdl import NXDL_NAMESPACE from ..globals.urls import REPO_URL +from ..utils import nxdl_utils as pynxtools_nxlib +from ..utils.github import get_file_contributors_via_api from ..utils.types import PathLike from .anchor_list import AnchorRegistry +# controlling the length of progressively more indented sub-node +MIN_COLLAPSE_HINT_LINE_LENGTH = 20 +MAX_COLLAPSE_HINT_LINE_LENGTH = 80 + class NXClassDocGenerator: """Generate documentation in reStructuredText markup @@ -80,6 +86,7 @@ def _parse_nxdl_file(self, nxdl_file: Path): self._print( f".. auto-generated by {__name__} from the NXDL source {source} -- DO NOT EDIT" ) + self._print("") self._print(".. index::") self._print(f" ! {nxclass_name} ({self._listing_category})") @@ -100,6 +107,24 @@ def _parse_nxdl_file(self, nxdl_file: Path): else: extends = f":ref:`{extends}`" + # add the contributors as variables to the rst file that will + nxdl_root = get_nxdl_root() + rel_path = str(nxdl_file.relative_to(nxdl_root)) + rel_html = str(rel_path).replace(os.sep, "/") + contribs_dct = get_file_contributors_via_api("definitions", rel_html) + if contribs_dct is not None: + self._print("") + self._print("..") + self._print(" Contributors List") + for date_str, contrib_dct in contribs_dct.items(): + date_str = date_str.split("T")[0] + name = contrib_dct["name"] + gh_login_nm = contrib_dct["commit_dct"]["committer"]["login"] + gh_avatar_url = contrib_dct["commit_dct"]["committer"]["avatar_url"] + self._print("") + s = "|".join([name, gh_login_nm, gh_avatar_url, date_str]) + self._print(f" .. |contrib_name| replace:: {s}") + self._print("") self._print("**Status**:\n") self._print(f" {self._listing_category.strip()}, extends {extends}") @@ -109,7 +134,7 @@ def _parse_nxdl_file(self, nxdl_file: Path): # print official description of this class self._print("") self._print("**Description**:\n") - self._print_doc(self._INDENTATION_UNIT, ns, root, required=True) + self._print_doc_enum("", ns, root, required=True) # print symbol list node_list = root.xpath("nx:symbols", namespaces=ns) @@ -119,7 +144,7 @@ def _parse_nxdl_file(self, nxdl_file: Path): elif len(node_list) > 1: raise Exception(f"Invalid symbol table in {nxclass_name}") else: - self._print_doc(self._INDENTATION_UNIT, ns, node_list[0]) + self._print_doc_enum("", ns, node_list[0]) for node in node_list[0].xpath("nx:symbol", namespaces=ns): doc = self._get_doc_line(ns, node) self._print(f" **{node.get('name')}**", end="") @@ -278,12 +303,34 @@ def _get_doc_blocks(ns, node): out_blocks.append("\n".join(out_lines)) return out_blocks + def _handle_multiline_docstring(self, blocks): + links = [] + docstring = "" + expanded_blocks = [] + for block in blocks: + expanded_blocks += block.split("\n") + + for block in expanded_blocks: + if not block: + continue + + link_match = re.search(r"\.\. _([^:]+):(.*)", block) + if link_match is not None: + links.append((link_match.group(1), link_match.group(2).strip())) + else: + docstring += " " + re.sub(r"\n", " ", block.strip()) + + for name, target in links: + docstring = docstring.replace(f"`{name}`_", f"`{name} <{target}>`_") + + return docstring + def _get_doc_line(self, ns, node): blocks = self._get_doc_blocks(ns, node) if len(blocks) == 0: return "" if len(blocks) > 1: - raise Exception(f"Unexpected multi-paragraph doc [{'|'.join(blocks)}]") + return self._handle_multiline_docstring(blocks) return re.sub(r"\n", " ", blocks[0]) def _get_minOccurs(self, node): @@ -498,6 +545,38 @@ def _print_doc(self, indent, ns, node, required=False): self._print(f"{indent}{line}") self._print() + def long_doc(self, ns, node, left_margin): + length = 0 + line = "documentation" + fnd = False + blocks = self._get_doc_blocks(ns, node) + max_characters = max( + MIN_COLLAPSE_HINT_LINE_LENGTH, (MAX_COLLAPSE_HINT_LINE_LENGTH - left_margin) + ) + for block in blocks: + lines = block.splitlines() + length += len(lines) + for single_line in lines: + if len(single_line) > 2 and single_line[0] != "." and not fnd: + fnd = True + line = single_line[:max_characters] + return (length, line, blocks) + + def _print_doc_enum(self, indent, ns, node, required=False): + collapse_indent = indent + node_list = node.xpath("nx:enumeration", namespaces=ns) + (doclen, line, blocks) = self.long_doc(ns, node, len(indent)) + if len(node_list) + doclen > 1: + collapse_indent = f"{indent} " + self._print(f"{indent}{self._INDENTATION_UNIT}.. collapse:: {line} ...\n") + self._print_doc( + collapse_indent + self._INDENTATION_UNIT, ns, node, required=required + ) + if len(node_list) == 1: + self._print_enumeration( + collapse_indent + self._INDENTATION_UNIT, ns, node_list[0] + ) + def _print_attribute(self, ns, kind, node, optional, indent, parent_path): name = node.get("name") index_name = name @@ -506,12 +585,9 @@ def _print_attribute(self, ns, kind, node, optional, indent, parent_path): ) self._print(f"{indent}.. index:: {index_name} ({kind} attribute)\n") self._print( - f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)}\n" + f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n" ) - self._print_doc(indent + self._INDENTATION_UNIT, ns, node) - node_list = node.xpath("nx:enumeration", namespaces=ns) - if len(node_list) == 1: - self._print_enumeration(indent + self._INDENTATION_UNIT, ns, node_list[0]) + self._print_doc_enum(indent, ns, node) def _print_if_deprecated(self, ns, node, indent): deprecated = node.get("deprecated", None) @@ -549,17 +625,12 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): f"{self._format_type(node)}" f"{dims}" f"{self._format_units(node)}" + f" {self.get_first_parent_ref(f'{parent_path}/{name}', 'field')}" "\n" ) self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT) - self._print_doc(indent + self._INDENTATION_UNIT, ns, node) - - node_list = node.xpath("nx:enumeration", namespaces=ns) - if len(node_list) == 1: - self._print_enumeration( - indent + self._INDENTATION_UNIT, ns, node_list[0] - ) + self._print_doc_enum(indent, ns, node) for subnode in node.xpath("nx:attribute", namespaces=ns): optional = self._get_required_or_optional_text(subnode) @@ -585,10 +656,12 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): # target = hTarget.replace(".. _", "").replace(":\n", "") # TODO: https://github.com/nexusformat/definitions/issues/1057 self._print(f"{indent}{hTarget}") - self._print(f"{indent}**{name}**: {optional_text}{typ}\n") + self._print( + f"{indent}**{name}**: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n" + ) self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT) - self._print_doc(indent + self._INDENTATION_UNIT, ns, node) + self._print_doc_enum(indent, ns, node) for subnode in node.xpath("nx:attribute", namespaces=ns): optional = self._get_required_or_optional_text(subnode) @@ -619,8 +692,49 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path): f"(suggested target: ``{node.get('target')}``)" "\n" ) - self._print_doc(indent + self._INDENTATION_UNIT, ns, node) + self._print_doc_enum(indent, ns, node) def _print(self, *args, end="\n"): # TODO: change instances of \t to proper indentation self._rst_lines.append(" ".join(args) + end) + + def get_first_parent_ref(self, path, tag): + nx_name = path[1 : path.find("/", 1)] + path = path[path.find("/", 1) :] + + try: + parents = pynxtools_nxlib.get_inherited_nodes(path, nx_name)[2] + except FileNotFoundError: + return "" + if len(parents) > 1: + parent = parents[1] + parent_path = parent_display_name = parent.attrib["nxdlpath"] + parent_path_segments = parent_path[1:].split("/") + parent_def_name = parent.attrib["nxdlbase"][ + parent.attrib["nxdlbase"] + .rfind("/") : parent.attrib["nxdlbase"] + .rfind(".nxdl") + ] + + # Case where the first parent is a base_class + if parent_path_segments[0] == "": + return "" + + # special treatment for NXnote@type + if ( + tag == "attribute" + and parent_def_name == "/NXnote" + and parent_path == "/type" + ): + return "" + + if tag == "attribute": + pos_of_right_slash = parent_path.rfind("/") + parent_path = ( + parent_path[:pos_of_right_slash] + + "@" + + parent_path[pos_of_right_slash + 1 :] + ) + parent_display_name = f"{parent_def_name[1:]}{parent_path}" + return f":ref:`⤆ `" + return "" diff --git a/dev_tools/docs/nxdl_index.py b/dev_tools/docs/nxdl_index.py index 98f90b95bc..61725ced4e 100644 --- a/dev_tools/docs/nxdl_index.py +++ b/dev_tools/docs/nxdl_index.py @@ -45,6 +45,8 @@ def nxdl_indices() -> Dict[str, dict]: nxclass_name = nxdl_file.with_suffix("").stem classes.append(nxclass_name) summary = get_nxclass_description(nxdl_file, namespaces) + if "NXcg" in nxclass_name or "NXapm" in nxclass_name or "NXms" in nxclass_name: + continue rst_lines.append("\n") rst_lines.append(f":ref:`{nxclass_name}`\n") rst_lines.append(f"{indentation}{summary}\n") @@ -57,6 +59,24 @@ def nxdl_indices() -> Dict[str, dict]: rst_lines.append(".. toctree::\n") rst_lines.append(f"{indentation}:hidden:\n") rst_lines.append("\n") + if "index_file" in section.keys(): + file = section["index_file"] + print("----------", file) + file = os.path.abspath(file) + else: + file = "" + print("---------++++++++-", section) + if file.endswith("contributed_definitions/index.rst"): + rst_lines.append(f"{indentation}em-structure\n") + rst_lines.append(f"{indentation}ellipsometry-structure\n") + rst_lines.append(f"{indentation}mpes-structure\n") + rst_lines.append(f"{indentation}apm-structure\n") + rst_lines.append(f"{indentation}transport-structure\n") + rst_lines.append(f"{indentation}sts-structure\n") + rst_lines.append(f"{indentation}cgms-structure\n") + rst_lines.append(f"{indentation}icme-structure\n") + rst_lines.append(f"{indentation}sample-prep-structure\n") + for cname in sorted(classes): rst_lines.append(f"{indentation}{cname}\n") @@ -141,5 +161,22 @@ def get_nxclass_description(nxdl_file: Path, namespaces) -> str: case not for general use. The :ref:`NIAC` is charged to review any new contributed definitions and provide feedback to the authors before ratification and acceptance as either a base class or application definition. + +Some contributions are grouped together: + :ref:`Optical Spectroscopy ` + + :ref:`Multi-dimensional Photoemission Spectroscopy ` + + :ref:`Atomprobe Microscopy ` + + :ref:`Electron Microscopy ` + + :ref:`Transport Measurements ` + + :ref:`Geometry and Microstructures ` + + +and others are simply listed here: + """, } diff --git a/dev_tools/docs/xsd_units.py b/dev_tools/docs/xsd_units.py index 63d7714289..8306a6fa9f 100644 --- a/dev_tools/docs/xsd_units.py +++ b/dev_tools/docs/xsd_units.py @@ -5,7 +5,6 @@ the NXDL chapter. """ - from pathlib import Path from typing import List diff --git a/dev_tools/ext/__init__.py b/dev_tools/ext/__init__.py new file mode 100755 index 0000000000..e69de29bb2 diff --git a/dev_tools/ext/contrib_ext.py b/dev_tools/ext/contrib_ext.py new file mode 100755 index 0000000000..dc37de88c2 --- /dev/null +++ b/dev_tools/ext/contrib_ext.py @@ -0,0 +1,30 @@ +import re + +# a custom sphinx extension that is connected to the source-read hook for rst files, +# the purpose is to read all of the contributor information from the rst file and +# place it in a string variable that will be used in the sourcelink.html jinja template +# that has been over ridden and sits in the _templates directory to produce the +# contributor information on the for right sidebar of the html pages + +variables_re = re.compile(r"\|(\w+)\| replace::\s(.+)") + + +def extract_contributor_vars(app, docname, source): + # Read the RST file content + content = source[0] + + # Extract variables using regular expressions + variables = variables_re.findall(content) + + # Create a dictionary to store the extracted variables + # this will create a list of single strings each of which contain the info about the contributor + extracted_variables = [var[1] for var in variables] + if "variables" not in app.config.html_context.keys(): + app.config.html_context["variables"] = {} + + # Add the extracted variables to the Jinja environment + app.config.html_context["variables"][docname] = extracted_variables + + +def setup(app): + app.connect("source-read", extract_contributor_vars) diff --git a/dev_tools/globals/urls.py b/dev_tools/globals/urls.py index 729b7d1028..2929070cc2 100644 --- a/dev_tools/globals/urls.py +++ b/dev_tools/globals/urls.py @@ -1,2 +1,2 @@ -REPO_URL = "https://github.com/nexusformat/definitions/blob/main" +REPO_URL = "https://github.com/FAIRmat-NFDI/nexus_definitions/tree/fairmat" MANUAL_URL = "https://manual.nexusformat.org" diff --git a/dev_tools/nxdl/syntax.py b/dev_tools/nxdl/syntax.py index e5b37b657e..f3959654c3 100644 --- a/dev_tools/nxdl/syntax.py +++ b/dev_tools/nxdl/syntax.py @@ -1,3 +1,4 @@ +from contextlib import contextmanager from typing import Optional import lxml.etree @@ -16,13 +17,19 @@ def validate_definition( xml_schema: Optional[lxml.etree.XMLSchema] = None, ): xml_file_name = str(xml_file_name) - try: + with _handle_xml_error(xml_file_name, lxml.etree.XMLSyntaxError): xml_tree = lxml.etree.parse(xml_file_name) - except lxml.etree.XMLSyntaxError: - raise errors.XMLSyntaxError(xml_file_name) if xml_schema is None: xml_schema = nxdl_schema() - try: + with _handle_xml_error(xml_file_name, lxml.etree.DocumentInvalid): xml_schema.assertValid(xml_tree) - except lxml.etree.DocumentInvalid: - raise errors.NXDLSyntaxError(xml_file_name) + + +@contextmanager +def _handle_xml_error(xml_file_name: str, *exception_types): + try: + yield + except exception_types as e: + raise errors.XMLSyntaxError( + "\n " + "\n ".join([xml_file_name] + str(e).rsplit(":", 1)) + ) from e diff --git a/dev_tools/tests/NXtest.nxdl.xml b/dev_tools/tests/NXtest.nxdl.xml new file mode 100644 index 0000000000..767733e948 --- /dev/null +++ b/dev_tools/tests/NXtest.nxdl.xml @@ -0,0 +1,65 @@ + + + + This is a dummy NXDL to test out the dataconverter. + + + + This is a dummy NXDL to test out the dataconverter. + + + + + + + + + A dummy entry for a float value. + + + A dummy entry for a bool value. + + + A dummy entry for an int value. + + + A dummy entry for a positive int value. + + + A dummy entry for a char value. + + + A dummy entry for a date value. + + + + + + + + + + + + This is a required yet empty group. + + + This is a second required yet empty group. + + + + A dummy entry to test optional parent check for required child. + + + A dummy entry to test optional parent check for required child. + + + + diff --git a/dev_tools/tests/test_nxdl_utils.py b/dev_tools/tests/test_nxdl_utils.py new file mode 100644 index 0000000000..82972e6ae4 --- /dev/null +++ b/dev_tools/tests/test_nxdl_utils.py @@ -0,0 +1,138 @@ +"""This is a code that performs several tests on nexus tool + +""" + +# +# Copyright The NOMAD Authors. +# +# This file is part of NOMAD. See https://nomad-lab.eu for further info. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +import os + +import lxml.etree as ET + +from ..utils import nxdl_utils as nexus + + +def test_get_nexus_classes_units_attributes(): + """Check the correct parsing of a separate list for: + Nexus classes (base_classes) + Nexus units (memberTypes) + Nexus attribute type (primitiveTypes) + the tested functions can be found in nexus.py file""" + + # Test 1 + nexus_classes_list = nexus.get_nx_classes() + + assert "NXbeam" in nexus_classes_list + + # Test 2 + nexus_units_list = nexus.get_nx_units() + assert "NX_TEMPERATURE" in nexus_units_list + + # Test 3 + nexus_attribute_list = nexus.get_nx_attribute_type() + assert "NX_FLOAT" in nexus_attribute_list + + +def test_get_node_at_nxdl_path(): + """Test to verify if we receive the right XML element for a given NXDL path""" + local_dir = os.path.abspath(os.path.dirname(__file__)) + nxdl_file_path = os.path.join(local_dir, "./NXtest.nxdl.xml") + elem = ET.parse(nxdl_file_path).getroot() + node = nexus.get_node_at_nxdl_path("/ENTRY/NXODD_name", elem=elem) + assert node.attrib["type"] == "NXdata" + assert node.attrib["name"] == "NXODD_name" + + node = nexus.get_node_at_nxdl_path("/ENTRY/NXODD_name/float_value", elem=elem) + assert node.attrib["type"] == "NX_FLOAT" + assert node.attrib["name"] == "float_value" + + node = nexus.get_node_at_nxdl_path( + "/ENTRY/NXODD_name/AXISNAME/long_name", elem=elem + ) + assert node.attrib["name"] == "long_name" + + nxdl_file_path = os.path.join( + local_dir, "../../contributed_definitions/NXem.nxdl.xml" + ) + elem = ET.parse(nxdl_file_path).getroot() + node = nexus.get_node_at_nxdl_path( + "/ENTRY/measurement/EVENT_DATA_EM_SET/EVENT_DATA_EM/end_time", elem=elem + ) + assert node.attrib["name"] == "end_time" + + node = nexus.get_node_at_nxdl_path("/ENTRY/measurement", elem=elem) + assert node.attrib["type"] == "NXem_msr" + + node = nexus.get_node_at_nxdl_path( + "/ENTRY/measurement/EVENT_DATA_EM_SET/EVENT_DATA_EM/IMAGE_C_SET/hyperstack", + elem=elem, + ) + assert node.attrib["type"] == "NXdata" + + node = nexus.get_node_at_nxdl_path( + "/ENTRY/measurement/EVENT_DATA_EM_SET/EVENT_DATA_EM/IMAGE_C_SET/hyperstack/AXISNAME_indices", + elem=elem, + ) + assert node.attrib["name"] == "AXISNAME_indices" + + node = nexus.get_node_at_nxdl_path( + "/ENTRY/measurement/EVENT_DATA_EM_SET/EVENT_DATA_EM/IMAGE_C_SET/stack/axis_j", + elem=elem, + ) + assert node.attrib["type"] == "NX_NUMBER" + + node = nexus.get_node_at_nxdl_path("/ENTRY/COORDINATE_SYSTEM_SET", elem=elem) + assert node.attrib["type"] == "NXcoordinate_system_set" + + nxdl_file_path = os.path.join( + local_dir, "../../contributed_definitions/NXiv_temp.nxdl.xml" + ) + elem = ET.parse(nxdl_file_path).getroot() + node = nexus.get_node_at_nxdl_path( + "/ENTRY/INSTRUMENT/ENVIRONMENT/voltage_controller", elem=elem + ) + assert node.attrib["name"] == "voltage_controller" + + node = nexus.get_node_at_nxdl_path( + "/ENTRY/INSTRUMENT/ENVIRONMENT/voltage_controller/calibration_time", elem=elem + ) + assert node.attrib["name"] == "calibration_time" + + +def test_get_inherited_nodes(): + """Test to verify if we receive the right XML element list for a given NXDL path.""" + local_dir = os.path.abspath(os.path.dirname(__file__)) + nxdl_file_path = os.path.join( + local_dir, "../../contributed_definitions/NXiv_temp.nxdl.xml" + ) + elem = ET.parse(nxdl_file_path).getroot() + (_, _, elist) = nexus.get_inherited_nodes( + nxdl_path="/ENTRY/INSTRUMENT/ENVIRONMENT", elem=elem + ) + assert len(elist) == 3 + + (_, _, elist) = nexus.get_inherited_nodes( + nxdl_path="/ENTRY/INSTRUMENT/ENVIRONMENT/voltage_controller", elem=elem + ) + assert len(elist) == 4 + + (_, _, elist) = nexus.get_inherited_nodes( + nxdl_path="/ENTRY/INSTRUMENT/ENVIRONMENT/voltage_controller", + nx_name="NXiv_temp", + ) + assert len(elist) == 4 diff --git a/dev_tools/utils/copy.py b/dev_tools/utils/copy.py index 472c4b4ad0..099dd8d759 100644 --- a/dev_tools/utils/copy.py +++ b/dev_tools/utils/copy.py @@ -3,8 +3,6 @@ from typing import List from typing import Tuple -import requests - from ..globals import directories @@ -20,14 +18,6 @@ def copydir(from_path: Path, to_path: Path) -> None: shutil.copytree(from_path, to_path, dirs_exist_ok=True) -def download(url: str, to_path: Path) -> None: - print("download", url) - print(" ->", to_path) - r = requests.get(url) - with open(to_path, "wb") as fh: - fh.write(r.content) - - def copy_files(files: List[Tuple[str, str, bool]]) -> None: source_root = directories.get_source_root() build_root = directories.get_build_root() @@ -38,13 +28,3 @@ def copy_files(files: List[Tuple[str, str, bool]]) -> None: copyfile(from_path, to_path) else: print("already exists", to_path) - - -def download_files(urls: List[Tuple[str, str, bool]]) -> None: - build_root = directories.get_build_root() - for url, subname, overwrite in urls: - to_path = build_root / subname - if overwrite or not to_path.exists(): - download(url, to_path) - else: - print("already exists", to_path) diff --git a/dev_tools/utils/github.py b/dev_tools/utils/github.py new file mode 100755 index 0000000000..f286594eb1 --- /dev/null +++ b/dev_tools/utils/github.py @@ -0,0 +1,94 @@ +import os + +import requests + + +def format_author_name(nm): + """ + make sure all words in name start with a capital + """ + nms = nm.split(" ") + auth_nm = " ".join([n.capitalize() for n in nms]) + return auth_nm + + +def get_github_profile_name(email): + """ + given an email addr return the github login name + """ + email = email.replace(" ", "") + nm = email.split("@")[0] + return nm + + +def get_file_contributors_via_api(repo_name, file_path): + """ + This function takes the repo name (ex:"definitions") and relative path to the nxdl + file (ex: "applications/NXmx.nxdl.xml") and using the github api it retrieves a dictionary + of committers for that file in descending date order. + + In order to increase the capacity (rate) of use of the github API an access token is used if it exists + as an environment variable called GH_TOKEN, in the ci yaml file this is expected to be assigned from the secret + object like this + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + + With the access token the rate is 5000 times per hour and without it is 60 + + returns a sorted dict of unique contributors to a file, or None if no GH_TOKEN has been defined in os.environ + """ + have_token = False + access_token = os.getenv("GH_TOKEN") + if ( + access_token is not None and access_token != "NONE" + ): # latter clause is false in most CI cases + if len(access_token) > 0: + have_token = True + else: + # because the environment does not contain GH_TOKEN, assume the user wants to build the + # docs without contributor info + return None + + contrib_skip_list = ["GitHub"] + url = f"https://api.github.com/repos/nexusformat/{repo_name}/commits" + params = {"path": file_path} + headers = {} + if have_token: + # Set the headers with the access token + headers = { + "Authorization": f"token {access_token}", + "Accept": "application/vnd.github.v3+json", + } + + response = requests.get(url, params=params, headers=headers) + commits = response.json() + if response.status_code != 200: + # if its 403: the max rate per hour has been reached + raise Exception( + f"access_token={access_token}, {commits['message']},{commits['documentation_url']}" + ) + + contributor_names = set() + contribs_dct = {} + _email_lst = [] + for commit_dct in commits: + if commit_dct["committer"] is not None: + contributor = commit_dct["commit"]["committer"]["name"] + if contributor in contrib_skip_list: + continue + contributor_names.add(contributor) + if commit_dct["commit"]["committer"]["email"] not in _email_lst: + _email = commit_dct["commit"]["committer"]["email"] + _email_lst.append(_email) + contribs_dct[commit_dct["commit"]["committer"]["date"]] = { + "name": format_author_name( + commit_dct["commit"]["committer"]["name"] + ), + "commit_dct": commit_dct, + } + + # sort them so they are in descending order from newest to oldest + sorted_keys = sorted(contribs_dct.keys(), reverse=True) + sorted_dict = {key: contribs_dct[key] for key in sorted_keys} + + return sorted_dict diff --git a/dev_tools/utils/nxdl_utils.py b/dev_tools/utils/nxdl_utils.py new file mode 100644 index 0000000000..be8262fdfc --- /dev/null +++ b/dev_tools/utils/nxdl_utils.py @@ -0,0 +1,839 @@ +# pylint: disable=too-many-lines +"""Parse NeXus definition files +""" + +import os +import textwrap +from functools import lru_cache +from glob import glob +from pathlib import Path + +import lxml.etree as ET +from lxml.etree import ParseError as xmlER + + +def remove_namespace_from_tag(tag): + """Helper function to remove the namespace from an XML tag.""" + + return tag.split("}")[-1] + + +class NxdlAttributeNotFoundError(Exception): + """An exception to throw when an Nxdl attribute is not found.""" + + +def get_nexus_definitions_path(): + """Check NEXUS_DEF_PATH variable. + If it is empty, this function is filling it""" + try: # either given by sys env + return Path(os.environ["NEXUS_DEF_PATH"]) + except KeyError: # or it should be available locally under the dir 'definitions' + local_dir = Path(__file__).resolve().parent + for _ in range(2): + local_dir = local_dir.parent + return local_dir + + +nexus_def_path = get_nexus_definitions_path() + + +def get_app_defs_names(): + """Returns all the AppDef names without their extension: .nxdl.xml""" + app_def_path_glob = nexus_def_path / "applications" / "*.nxdl*" + + contrib_def_path_glob = Path(nexus_def_path) / "contributed_definitions" / "*.nxdl*" + + files = sorted(glob(app_def_path_glob)) + for nexus_file in sorted(contrib_def_path_glob): + root = get_xml_root(nexus_file) + if root.attrib["category"] == "application": + files.append(nexus_file) + + return [Path(file).name[:-9] for file in files] + ["NXroot"] + + +@lru_cache(maxsize=None) +def get_xml_root(file_path): + """Reducing I/O time by caching technique""" + + return ET.parse(file_path).getroot() + + +def get_hdf_root(hdf_node): + """Get the root HDF5 node""" + node = hdf_node + while node.name != "/": + node = node.parent + return node + + +def get_hdf_parent(hdf_info): + """Get the parent of an hdf_node in an hdf_info""" + if "hdf_path" not in hdf_info: + return hdf_info["hdf_node"].parent + node = ( + get_hdf_root(hdf_info["hdf_node"]) + if "hdf_root" not in hdf_info + else hdf_info["hdf_root"] + ) + for child_name in hdf_info["hdf_path"].split("/"): + node = node[child_name] + return node + + +def get_parent_path(hdf_name): + """Get parent path""" + return hdf_name.rsplit("/", 1)[0] + + +def get_hdf_info_parent(hdf_info): + """Get the hdf_info for the parent of an hdf_node in an hdf_info""" + if "hdf_path" not in hdf_info: + return {"hdf_node": hdf_info["hdf_node"].parent} + node = get_hdf_parent(hdf_info) + return {"hdf_node": node, "hdf_path": get_parent_path(hdf_info["hdf_path"])} + + +def get_nx_class(nxdl_elem): + """Get the nexus class for a NXDL node""" + if "category" in nxdl_elem.attrib.keys(): + return "" + return nxdl_elem.attrib.get("type", "NX_CHAR") + + +def get_nx_namefit(hdf_name, name, name_any=False): + """Checks if an HDF5 node name corresponds to a child of the NXDL element + uppercase letters in front can be replaced by arbitrary name, but + uppercase to lowercase match is preferred, + so such match is counted as a measure of the fit""" + if name == hdf_name: + return len(name) * 2 + # count leading capitals + counting = 0 + while counting < len(name) and name[counting].isupper(): + counting += 1 + if ( + name_any + or counting == len(name) + or (counting > 0 and hdf_name.endswith(name[counting:])) + ): # if potential fit + # count the matching chars + fit = 0 + for i in range(min(counting, len(hdf_name))): + if hdf_name[i].upper() == name[i]: + fit += 1 + else: + break + if fit == min(counting, len(hdf_name)): # accept only full fits as better fits + return fit + return 0 + return -1 # no fit + + +def get_nx_classes(): + """Read base classes from the NeXus definition folder. + Check each file in base_classes, applications, contributed_definitions. + If its category attribute is 'base', then it is added to the list.""" + nexus_definition_path = nexus_def_path + base_classes = sorted(nexus_definition_path.glob("base_classes/*.nxdl.xml")) + applications = sorted(nexus_definition_path.glob("applications/*.nxdl.xml")) + contributed = sorted( + nexus_definition_path.glob("contributed_definitions/*.nxdl.xml") + ) + nx_class = [] + for nexus_file in base_classes + applications + contributed: + try: + root = get_xml_root(nexus_file) + except xmlER as e: + raise ValueError(f"Getting an issue while parsing file {nexus_file}") from e + if root.attrib["category"] == "base": + nx_class.append(nexus_file.name[:-9]) + return sorted(nx_class) + + +def get_nx_units(): + """Read unit kinds from the NeXus definition/nxdlTypes.xsd file""" + filepath = nexus_def_path / "nxdlTypes.xsd" + root = get_xml_root(filepath) + units_and_type_list = [] + for child in root: + units_and_type_list.extend(child.attrib.values()) + flag = False + nx_units = [] + for line in units_and_type_list: + if line == "anyUnitsAttr": + flag = True + elif "NX" in line and flag: + nx_units.append(line) + elif line == "primitiveType": + flag = False + + return nx_units + + +def get_nx_attribute_type(): + """Read attribute types from the NeXus definition/nxdlTypes.xsd file""" + filepath = nexus_def_path / "nxdlTypes.xsd" + + root = get_xml_root(filepath) + units_and_type_list = [] + for child in root: + units_and_type_list.extend(child.attrib.values()) + flag = False + nx_types = [] + for line in units_and_type_list: + if line == "primitiveType": + flag = True + elif "NX" in line and flag is True: + nx_types.append(line) + elif line == "anyUnitsAttr": + flag = False + else: + pass + return nx_types + + +def get_node_name(node): + """Node - xml node. Returns html documentation name. + Either as specified by the 'name' or taken from the type (nx_class). + Note that if only class name is available, the NX prefix is removed and + the string is converted to UPPER case.""" + if "name" in node.attrib: + name = node.attrib["name"] + else: + name = node.attrib["type"] + if name.startswith("NX"): + name = name[2:].upper() + return name + + +def belongs_to(nxdl_elem, child, name, class_type=None, hdf_name=None): + """Checks if an HDF5 node name corresponds to a child of the NXDL element + uppercase letters in front can be replaced by arbitraty name, but + uppercase to lowercase match is preferred""" + if class_type and get_nx_class(child) != class_type: + return False + act_htmlname = get_node_name(child) + chk_name = hdf_name or name + if act_htmlname == chk_name: + return True + if not hdf_name: # search for name fits is only allowed for hdf_nodes + return False + try: # check if nameType allows different name + name_any = bool(child.attrib["nameType"] == "any") + except KeyError: + name_any = False + params = [act_htmlname, chk_name, name_any, nxdl_elem, child, name] + return belongs_to_capital(params) + + +def belongs_to_capital(params): + """Checking continues for Upper case""" + (act_htmlname, chk_name, name_any, nxdl_elem, child, name) = params + # or starts with capital and no reserved words used + if ( + (name_any or (act_htmlname[0].isalpha() and act_htmlname[0].isupper())) + and name != "doc" + and name != "enumeration" + ): + fit = get_nx_namefit(chk_name, act_htmlname, name_any) # check if name fits + if fit < 0: + return False + for child2 in nxdl_elem: + if not isinstance(child2.tag, str): + continue + if ( + get_local_name_from_xml(child) != get_local_name_from_xml(child2) + or get_node_name(child2) == act_htmlname + ): + continue + # check if the name of another sibling fits better + name_any2 = child2.attrib.get("nameType") == "any" + fit2 = get_nx_namefit(chk_name, get_node_name(child2), name_any2) + if fit2 > fit: + return False + # accept this fit + return True + return False + + +def get_local_name_from_xml(element): + """Helper function to extract the element tag without the namespace.""" + return remove_namespace_from_tag(element.tag) + + +def get_own_nxdl_child_reserved_elements(child, name, nxdl_elem): + """checking reserved elements, like doc, enumeration""" + local_name = get_local_name_from_xml(child) + if local_name == "doc" and name == "doc": + return set_nxdlpath(child, nxdl_elem, tag_name=name) + + if local_name == "enumeration" and name == "enumeration": + return set_nxdlpath(child, nxdl_elem, tag_name=name) + return False + + +def get_own_nxdl_child_base_types(child, class_type, nxdl_elem, name, hdf_name): + """checking base types of group, field, attribute""" + if get_local_name_from_xml(child) == "group": + if ( + class_type is None or (class_type and get_nx_class(child) == class_type) + ) and belongs_to(nxdl_elem, child, name, class_type, hdf_name): + return set_nxdlpath(child, nxdl_elem) + if get_local_name_from_xml(child) == "field" and belongs_to( + nxdl_elem, child, name, None, hdf_name + ): + return set_nxdlpath(child, nxdl_elem) + if get_local_name_from_xml(child) == "attribute" and belongs_to( + nxdl_elem, child, name, None, hdf_name + ): + return set_nxdlpath(child, nxdl_elem) + return False + + +def get_own_nxdl_child( + nxdl_elem, name, class_type=None, hdf_name=None, nexus_type=None +): + """Checks if an NXDL child node fits to the specific name (either nxdl or hdf) + name - nxdl name + class_type - nxdl type or hdf classname (for groups, it is obligatory) + hdf_name - hdf name""" + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + if child.attrib.get("name") == name: + return set_nxdlpath(child, nxdl_elem) + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + if child.attrib.get("name") == name: + child.set("nxdlbase", nxdl_elem.get("nxdlbase")) + return child + + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + result = get_own_nxdl_child_reserved_elements(child, name, nxdl_elem) + if result is not False: + return result + if nexus_type and get_local_name_from_xml(child) != nexus_type: + continue + result = get_own_nxdl_child_base_types( + child, class_type, nxdl_elem, name, hdf_name + ) + if result is not False: + return result + return None + + +def find_definition_file(bc_name): + """find the nxdl file corresponding to the name. + Note that it first checks in contributed and goes beyond only if no contributed found + """ + bc_filename = None + for nxdl_folder in ["contributed_definitions", "base_classes", "applications"]: + nxdl_file = nexus_def_path / nxdl_folder / f"{bc_name}.nxdl.xml" + if nxdl_file.exists(): + bc_filename = nexus_def_path / nxdl_folder / f"{bc_name}.nxdl.xml" + break + return bc_filename + + +def get_nxdl_child( + nxdl_elem, name, class_type=None, hdf_name=None, nexus_type=None, go_base=True +): # pylint: disable=too-many-arguments + """Get the NXDL child node corresponding to a specific name + (e.g. of an HDF5 node,or of a documentation) note that if child is not found in application + definition, it also checks for the base classes""" + # search for possible fits for hdf_nodes : skipped + # only exact hits are returned when searching an nxdl child + own_child = get_own_nxdl_child(nxdl_elem, name, class_type, hdf_name, nexus_type) + if own_child is not None: + return own_child + if not go_base: + return None + bc_name = get_nx_class(nxdl_elem) # check in the base class, app def or contributed + if bc_name[2] == "_": # filter primitive types + return None + if ( + bc_name == "group" + ): # Check if it is the root element. Then send to NXroot.nxdl.xml + bc_name = "NXroot" + bc_filename = find_definition_file(bc_name) + if not bc_filename: + raise ValueError("nxdl file not found in definitions folder!") + bc_obj = ET.parse(bc_filename).getroot() + bc_obj.set("nxdlbase", bc_filename) + if "category" in bc_obj.attrib: + bc_obj.set("nxdlbase_class", bc_obj.attrib["category"]) + bc_obj.set("nxdlpath", "") + return get_own_nxdl_child(bc_obj, name, class_type, hdf_name, nexus_type) + + +def get_required_string(nxdl_elem): + """Check for being REQUIRED, RECOMMENDED, OPTIONAL, NOT IN SCHEMA""" + if nxdl_elem is None: + return "<>" + is_optional = ( + "optional" in nxdl_elem.attrib.keys() and nxdl_elem.attrib["optional"] == "true" + ) + is_minoccurs = ( + "minOccurs" in nxdl_elem.attrib.keys() and nxdl_elem.attrib["minOccurs"] == "0" + ) + is_recommended = ( + "recommended" in nxdl_elem.attrib.keys() + and nxdl_elem.attrib["recommended"] == "true" + ) + + if is_recommended: + return "<>" + if is_optional or is_minoccurs: + return "<>" + # default optionality: in BASE CLASSES is true; in APPLICATIONS is false + if nxdl_elem.get("nxdlbase_class") == "base": + return "<>" + return "<>" + + +# below there are some functions used in get_nxdl_doc function: +def write_doc_string(logger, doc, attr): + """Simple function that prints a line in the logger if doc exists""" + if doc: + logger.debug("@%s [NX_CHAR]", attr) + return logger, doc, attr + + +def try_find_units(logger, elem, nxdl_path, doc, attr): + """Try to find if units is defined inside the field in the NXDL element, + otherwise try to find if units is defined as a child of the NXDL element.""" + try: # try to find if units is defined inside the field in the NXDL element + unit = elem.attrib[attr] + if doc: + logger.debug(get_node_concept_path(elem) + "@" + attr + " [" + unit + "]") + elem = None + nxdl_path.append(attr) + except ( + KeyError + ): # otherwise try to find if units is defined as a child of the NXDL element + orig_elem = elem + elem = get_nxdl_child(elem, attr, nexus_type="attribute") + if elem is not None: + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - [" + + get_nx_class(elem) + + "]" + ) + nxdl_path.append(elem) + else: # if no units category were defined in NXDL: + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - REQUIRED, but undefined unit category" + ) + nxdl_path.append(attr) + return logger, elem, nxdl_path, doc, attr + + +def check_attr_name_nxdl(param): + """Check for ATTRIBUTENAME_units in NXDL (normal). + If not defined, check for ATTRIBUTENAME to see if the ATTRIBUTE + is in the SCHEMA, but no units category were defined.""" + (logger, elem, nxdl_path, doc, attr, req_str) = param + orig_elem = elem + elem2 = get_nxdl_child(elem, attr, nexus_type="attribute") + if elem2 is not None: # check for ATTRIBUTENAME_units in NXDL (normal) + elem = elem2 + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - [" + + get_nx_class(elem) + + "]" + ) + nxdl_path.append(elem) + else: + # if not defined, check for ATTRIBUTENAME to see if the ATTRIBUTE + # is in the SCHEMA, but no units category were defined + elem2 = get_nxdl_child(elem, attr[:-6], nexus_type="attribute") + if elem2 is not None: + req_str = "<>" + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - RECOMMENDED, but undefined unit category" + ) + nxdl_path.append(attr) + else: # otherwise: NOT IN SCHEMA + elem = elem2 + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - IS NOT IN SCHEMA" + ) + return logger, elem, nxdl_path, doc, attr, req_str + + +def try_find_default( + logger, orig_elem, elem, nxdl_path, doc, attr +): # pylint: disable=too-many-arguments + """Try to find if default is defined as a child of the NXDL element""" + if elem is not None: + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - [" + + get_nx_class(elem) + + "]" + ) + nxdl_path.append(elem) + else: # if no default category were defined in NXDL: + if doc: + logger.debug(get_node_concept_path(orig_elem) + "@" + attr + " - [NX_CHAR]") + nxdl_path.append(attr) + return logger, elem, nxdl_path, doc, attr + + +def other_attrs( + logger, orig_elem, elem, nxdl_path, doc, attr +): # pylint: disable=too-many-arguments + """Handle remaining attributes""" + if elem is not None: + if doc: + logger.debug( + get_node_concept_path(orig_elem) + + "@" + + attr + + " - [" + + get_nx_class(elem) + + "]" + ) + nxdl_path.append(elem) + else: + if doc: + logger.debug( + get_node_concept_path(orig_elem) + "@" + attr + " - IS NOT IN SCHEMA" + ) + return logger, elem, nxdl_path, doc, attr + + +def get_node_concept_path(elem): + """get the short version of nxdlbase:nxdlpath""" + return f'{elem.get("nxdlbase").split("/")[-1]}:{elem.get("nxdlpath")}' + + +def get_doc(node, ntype, nxhtml, nxpath): + """Get documentation""" + # URL for html documentation + anchor = "" + for n_item in nxpath: + anchor += n_item.lower() + "-" + anchor = ( + "https://manual.nexusformat.org/classes/", + nxhtml + "#" + anchor.replace("_", "-") + ntype, + ) + if not ntype: + anchor = anchor[:-1] + doc = "" # RST documentation from the field 'doc' + doc_field = node.find("doc") + if doc_field is not None: + doc = doc_field.text + (index, enums) = get_enums(node) # enums + if index: + enum_str = ( + "\n " + + ("Possible values:" if enums.count(",") else "Obligatory value:") + + "\n " + + enums + + "\n" + ) + else: + enum_str = "" + return anchor, doc + enum_str + + +def print_doc(node, ntype, level, nxhtml, nxpath): + """Print documentation""" + anchor, doc = get_doc(node, ntype, nxhtml, nxpath) + print(" " * (level + 1) + anchor) + preferred_width = 80 + level * 2 + wrapper = textwrap.TextWrapper( + initial_indent=" " * (level + 1), + width=preferred_width, + subsequent_indent=" " * (level + 1), + expand_tabs=False, + tabsize=0, + ) + if doc is not None: + for par in doc.split("\n"): + print(wrapper.fill(par)) + + +def get_namespace(element): + """Extracts the namespace for elements in the NXDL""" + return element.tag[element.tag.index("{") : element.tag.rindex("}") + 1] + + +def get_enums(node): + """Makes list of enumerations, if node contains any. + Returns comma separated STRING of enumeration values, if there are enum tag, + otherwise empty string.""" + # collect item values from enumeration tag, if any + namespace = get_namespace(node) + enums = [] + for enumeration in node.findall(f"{namespace}enumeration"): + for item in enumeration.findall(f"{namespace}item"): + enums.append(item.attrib["value"]) + enums = ",".join(enums) + if enums != "": + return (True, "[" + enums + "]") + return (False, "") # if there is no enumeration tag, returns empty string + + +def add_base_classes(elist, nx_name=None, elem: ET.Element = None): + """ + Add the base classes corresponding to the last element in elist to the list. Note that if + elist is empty, a nxdl file with the name of nx_name or a placeholder elem is used if provided + """ + if elist and nx_name is None: + nx_name = get_nx_class(elist[-1]) + # to support recursive defintions, like NXsample in NXsample, the following test is removed + # if elist and nx_name and f"{nx_name}.nxdl.xml" in (e.get('nxdlbase') for e in elist): + # return + if elem is None: + if not nx_name: + return + nxdl_file_path = find_definition_file(nx_name) + if nxdl_file_path is None: + nxdl_file_path = f"{nx_name}.nxdl.xml" + + try: + elem = ET.parse(os.path.abspath(nxdl_file_path)).getroot() + # elem = ET.parse(nxdl_file_path).getroot() + except OSError: + with open(nxdl_file_path, "r") as f: + elem = ET.parse(f).getroot() + + if not isinstance(nxdl_file_path, str): + nxdl_file_path = str(nxdl_file_path) + elem.set("nxdlbase", nxdl_file_path) + else: + elem.set("nxdlbase", "") + if "category" in elem.attrib: + elem.set("nxdlbase_class", elem.attrib["category"]) + elem.set("nxdlpath", "") + elist.append(elem) + # add inherited base class + if "extends" in elem.attrib and elem.attrib["extends"] != "NXobject": + add_base_classes(elist, elem.attrib["extends"]) + else: + add_base_classes(elist) + + +def set_nxdlpath(child, nxdl_elem, tag_name=None): + """Setting up child nxdlbase, nxdlpath and nxdlbase_class from nxdl_element.""" + if nxdl_elem.get("nxdlbase") is not None: + child.set("nxdlbase", nxdl_elem.get("nxdlbase")) + child.set("nxdlbase_class", nxdl_elem.get("nxdlbase_class")) + # Handle element that does not has 'name' attr e.g. doc, enumeration + if tag_name: + child.set("nxdlpath", nxdl_elem.get("nxdlpath") + "/" + tag_name) + else: + child.set( + "nxdlpath", nxdl_elem.get("nxdlpath") + "/" + get_node_name(child) + ) + + return child + + +def get_direct_child(nxdl_elem, html_name): + """returns the child of nxdl_elem which has a name + corresponding to the html documentation name html_name""" + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + if get_local_name_from_xml(child) in ( + "group", + "field", + "attribute", + ) and html_name == get_node_name(child): + decorated_child = set_nxdlpath(child, nxdl_elem) + return decorated_child + return None + + +def get_field_child(nxdl_elem, html_name): + """returns the child of nxdl_elem which has a name + corresponding to the html documentation name html_name""" + data_child = None + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + if get_local_name_from_xml(child) != "field": + continue + if get_node_name(child) == html_name: + data_child = set_nxdlpath(child, nxdl_elem) + break + return data_child + + +def get_best_nxdata_child(nxdl_elem, hdf_node, hdf_name): + """returns the child of an NXdata nxdl_elem which has a name + corresponding to the hdf_name""" + nxdata = hdf_node.parent + signals = [] + if "signal" in nxdata.attrs.keys(): + signals.append(nxdata.attrs.get("signal")) + if "auxiliary_signals" in nxdata.attrs.keys(): + for aux_signal in nxdata.attrs.get("auxiliary_signals"): + signals.append(aux_signal) + data_child = get_field_child(nxdl_elem, "DATA") + data_error_child = get_field_child(nxdl_elem, "FIELDNAME_errors") + for signal in signals: + if signal == hdf_name: + return (data_child, 100) + if hdf_name.endswith("_errors") and signal == hdf_name[:-7]: + return (data_error_child, 100) + axes = [] + if "axes" in nxdata.attrs.keys(): + for axis in nxdata.attrs.get("axes"): + axes.append(axis) + axis_child = get_field_child(nxdl_elem, "AXISNAME") + for axis in axes: + if axis == hdf_name: + return (axis_child, 100) + return (None, 0) + + +def get_best_child(nxdl_elem, hdf_node, hdf_name, hdf_class_name, nexus_type): + """returns the child of nxdl_elem which has a name + corresponding to the html documentation name html_name""" + bestfit = -1 + bestchild = None + if ( + "name" in nxdl_elem.attrib.keys() + and nxdl_elem.attrib["name"] == "NXdata" + and hdf_node is not None + and hdf_node.parent is not None + and hdf_node.parent.attrs.get("NX_class") == "NXdata" + ): + (fnd_child, fit) = get_best_nxdata_child(nxdl_elem, hdf_node, hdf_name) + if fnd_child is not None: + return (fnd_child, fit) + for child in nxdl_elem: + if not isinstance(child.tag, str): + continue + fit = -2 + if get_local_name_from_xml(child) == nexus_type and ( + nexus_type != "group" or get_nx_class(child) == hdf_class_name + ): + name_any = ( + "nameType" in nxdl_elem.attrib.keys() + and nxdl_elem.attrib["nameType"] == "any" + ) + fit = get_nx_namefit(hdf_name, get_node_name(child), name_any) + if fit > bestfit: + bestfit = fit + bestchild = set_nxdlpath(child, nxdl_elem) + return (bestchild, bestfit) + + +def walk_elist(elist, html_name): + """Handle elist from low priority inheritance classes to higher""" + for ind in range(len(elist) - 1, -1, -1): + child = get_direct_child(elist[ind], html_name) + if child is None: + # check for names fitting to a superclas definition + main_child = None + for potential_direct_parent in elist: + main_child = get_direct_child(potential_direct_parent, html_name) + if main_child is not None: + (fitting_child, _) = get_best_child( + elist[ind], + None, + html_name, + get_nx_class(main_child), + get_local_name_from_xml(main_child), + ) + if fitting_child is not None: + child = fitting_child + break + elist[ind] = child + if child is None: + del elist[ind] + continue + # override: remove low priority inheritance classes if class_type is overriden + if len(elist) > ind + 1 and get_nx_class(elist[ind]) != get_nx_class( + elist[ind + 1] + ): + del elist[ind + 1 :] + # add new base class(es) if new element brings such (and not a primitive type) + if len(elist) == ind + 1 and not get_nx_class(elist[ind]).startswith("NX_"): + add_base_classes(elist) + return elist, html_name + + +@lru_cache(maxsize=None) +def get_inherited_nodes( + nxdl_path: str = None, # pylint: disable=too-many-arguments,too-many-locals + nx_name: str = None, + elem: ET.Element = None, +): + """Returns a list of ET.Element for the given path.""" + # let us start with the given definition file + elist = [] # type: ignore[var-annotated] + add_base_classes(elist, nx_name, elem) + nxdl_elem_path = [elist[0]] + + class_path = [] # type: ignore[var-annotated] + html_paths = nxdl_path.split("/")[1:] + for html_name in html_paths: + elist, _ = walk_elist(elist, html_name) + if elist: + class_path.append(get_nx_class(elist[0])) + nxdl_elem_path.append(elist[0]) + return (class_path, nxdl_elem_path, elist) + + +def get_node_at_nxdl_path( + nxdl_path: str = None, + nx_name: str = None, + elem: ET.Element = None, + exc: bool = True, +): + """Returns an ET.Element for the given path. + This function either takes the name for the NeXus Application Definition + we are looking for or the root elem from a previously loaded NXDL file + and finds the corresponding XML element with the needed attributes.""" + try: + (class_path, nxdlpath, elist) = get_inherited_nodes(nxdl_path, nx_name, elem) + except ValueError as value_error: + if exc: + raise NxdlAttributeNotFoundError( + f"Attributes were not found for {nxdl_path}. " + "Please check this entry in the template dictionary." + ) from value_error + return None + if class_path and nxdlpath and elist: + elem = elist[0] + else: + elem = None + if exc: + raise NxdlAttributeNotFoundError( + f"Attributes were not found for {nxdl_path}. " + "Please check this entry in the template dictionary." + ) + return elem diff --git a/impatient-guide/conf.py b/impatient-guide/conf.py index 165ad7d7aa..5b25e6f16e 100644 --- a/impatient-guide/conf.py +++ b/impatient-guide/conf.py @@ -40,17 +40,18 @@ master_doc = 'index' # General information about the project. +year = '2022' # str(datetime.datetime.now().year) project = u'NeXus for the Impatient' -copyright = u'2014-2016, http://nexusformat.org' +copyright = f'2014-{year}, http://nexusformat.org' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '2016' +version = year # The full version, including alpha/beta/rc tags. -release = '2016' +release = year # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -116,7 +117,7 @@ # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -html_favicon = 'favicon.ico' +html_favicon = "../../common/favicon.ico" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/impatient-guide/favicon.ico b/impatient-guide/favicon.ico deleted file mode 100644 index 064181b36a..0000000000 Binary files a/impatient-guide/favicon.ico and /dev/null differ diff --git a/manual/source/_static/blockquote.css.bak b/manual/source/_static/blockquote.css.bak new file mode 100644 index 0000000000..4ce6e9b98f --- /dev/null +++ b/manual/source/_static/blockquote.css.bak @@ -0,0 +1,23 @@ +/* + * blockquote.css + * ~~~~~~~~~~~~~~~ + * + * custom Sphinx stylesheet -- define margins in blockquotes with NXDL documentation + * + * :see: http://stackoverflow.com/questions/23462494/how-to-add-custom-css-file + * + */ + +/* do NOT import, causes sidebar to disappear, see issue 341 +@import url("basic.css"); +*/ + +/* -- page layout ----------------------------------------------------------- */ + +/* github issue 341: nicer to solve this just for NXDL documentation files + * but this works for now + */ + +blockquote { + margin-right: 100px; +} diff --git a/manual/source/_static/to_alabaster.css b/manual/source/_static/to_alabaster.css new file mode 100644 index 0000000000..cf2c82d789 --- /dev/null +++ b/manual/source/_static/to_alabaster.css @@ -0,0 +1,73 @@ +/* Theme override commands to control the html aspect in alabaster sphinx theme */ + +/* Override sidebar background color default (#FFFFFF) */ +.sphinxsidebar { + background: #55af31 !important; + } +/* #005F73 is the original NIAC sidebar colour */ + +div.document { + margin-top: 0 !important; +} + +div.body { + margin-top: 30px !important; +} + + /* Control logo positioning */ +.sphinxsidebarwrapper p.logo { + padding: 15% !important; + text-align: center !important; +} + +/* Control sidebar headers (non clickable)*/ +.sphinxsidebarwrapper h3 { + font-size: 18pt !important; +} + +/* Control logo name string */ +.sphinxsidebarwrapper h1.logo { + margin-top: 0px !important; + font-size: 21pt !important; + margin-bottom: 10px !important; +} + +/* Control TOC tree top level links */ +.sphinxsidebar ul li.toctree-l1 > a { + font-size: 11pt !important; + line-height: 1.8 !important; +} + +/* Control TOC tree second level links */ +.sphinxsidebar ul li.toctree-l2 > a { + font-size: 10pt !important; + line-height: 1.8 !important; +} + +/* Control quick search bar */ +.sphinxsidebar input { + margin-top: 5px !important; + margin-bottom: 12px !important; +} + +/* Control quick search bar wrapper, nasty alignment with the google search bar */ +.sphinxsidebar div.searchformwrapper { + width: 209px !important; + align-self: center !important; + margin-left: 3px !important; +} + +/* Control text blurb explaining the project under the logo name */ +.sphinxsidebarwrapper p.blurb { + margin-top: 10px !important; + margin-bottom: 20px !important; +} + +/* Slightly increase the padding in the body */ +.bodywrapper div.body { + padding: 0 45px 0 45px !important; +} + +.body h1 { + margin-bottom: 50px !important; +} \ No newline at end of file diff --git a/manual/source/_static/to_rtd.css b/manual/source/_static/to_rtd.css new file mode 100644 index 0000000000..0b69475425 --- /dev/null +++ b/manual/source/_static/to_rtd.css @@ -0,0 +1,10 @@ +/* Theme override commands to control the html aspect in read the docs sphinx theme*/ + +/* Sidebar header (and topbar for mobile) */ +.wy-side-nav-search, .wy-nav-top { + background: #FF331C; + } +/* Sidebar */ +.wy-nav-side { + background: #005F73; + } \ No newline at end of file diff --git a/manual/source/_templates/sourcelink.html b/manual/source/_templates/sourcelink.html new file mode 100755 index 0000000000..791bdb3348 --- /dev/null +++ b/manual/source/_templates/sourcelink.html @@ -0,0 +1,45 @@ +{# + basic/sourcelink.html + ~~~~~~~~~~~~~~~~~~~~~ + + Sphinx sidebar template: "show source" link. + + :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{%- if show_source and has_source and sourcename %} +
+

{{ _('This Page') }}

+

Have a Question? Get help

+
    + + {% set nx_class_nm = sourcename|replace(".rst.txt","") %} + {% if variables[nx_class_nm]|length > 0 %} +

    Contributors

    + {% else %} + {% endif %} +
    + {% for vars_string in variables[nx_class_nm] %} + {% set var_list = vars_string.split('|') %} + {% set tooltip_string = var_list[0] ~ " " ~ var_list[3] %} + + GitHub Avatar + {% endfor %} +
+
+{%- endif %} diff --git a/manual/source/apm-structure.rst b/manual/source/apm-structure.rst new file mode 100644 index 0000000000..84ff91a115 --- /dev/null +++ b/manual/source/apm-structure.rst @@ -0,0 +1,9 @@ +.. _Apm-Structure-Fairmat: + +========================= +B5: Atom-probe tomography +========================= + +Atom probe tomography and related field-ion microscopy, aka atom probe microscopy (techniques) cover metrology methods with an origin in the materials science and condensed-matter physics communities. With its maturation and commercialization in the last two decades atom probe is increasingly being used for characterization of bio materials and fundamental science of field evaporation physics. + +A status report of the ongoing work on data schemas for atom probe using NeXus is available here: :ref:`Apm-Structure`. diff --git a/manual/source/cgms-structure.rst b/manual/source/cgms-structure.rst new file mode 100644 index 0000000000..4a4950933d --- /dev/null +++ b/manual/source/cgms-structure.rst @@ -0,0 +1,9 @@ +.. _Cg-Structure-Fairmat: + +====================== +Computational geometry +====================== + +Computational geometry is a frequently used tool for describing the shape and geometry of structural features in materials and components of instruments used for materials characterization. NeXus has a long history of base classes which serve these purposes. Upon closer inspection during the first year of the FAIRmat project, we found though that the collection of base classes could profit from an extension to make working with computational geometry data in NeXus simpler and more fine-grained. + +A status report of this ongoing work is available here: :ref:`CgmsFeatures-Structure`. diff --git a/manual/source/classes/contributed_definitions/apm-structure.rst b/manual/source/classes/contributed_definitions/apm-structure.rst new file mode 100644 index 0000000000..1e8b361527 --- /dev/null +++ b/manual/source/classes/contributed_definitions/apm-structure.rst @@ -0,0 +1,312 @@ +.. _Apm-Structure: + +===================== +Atom-probe tomography +===================== + +.. index:: + IntroductionApm + ApmAppDef + ApmBC + StatusQuoApm + ApmParaprobeAppDef + ApmParaprobeNewBC + + +.. _IntroductionApm: + +Introduction +############ + +Set of data schemas to describe the acquisition, i.e. measurement side, the extraction of hits from detector raw data, +steps to compute mass-to-charge state ratios from uncorrected time of flight data, the reconstruction, and the ranging, +i.e. identification of peaks in the mass-to-charge-state ratio histogram to detect (molecular) ions. +The data schemas can be useful to generate data artifacts also for field-ion microscopy experiments. + +.. _ApmAppDef: + +Application Definition +###################### + + :ref:`NXapm`: + A general application definition with many detailed places for leaving metadata and computational steps described which are commonly used when reporting the measurement of atom probe data including also detector hit data, as well as how to proceed with reconstructing atom positions from these data, and how to store details about definitions made, which describe how mass-to-charge-state ratio values are mapped to iontypes in a process called ranging. + +.. _ApmBC: + +Base Classes +############ + +The following base classes are proposed to support modularizing the storage of pieces of information: + + :ref:`NXchamber`: + A base class to describe a component of the instrument which houses other components. + A chamber may offer a controlled atmosphere to execute an experiment and/or offer functionalities + for storing and loading specimens. + + :ref:`NXcoordinate_system_set` + A base class to describe different coordinate systems used and/or to be harmonized + or transformed into one another when interpreting the dataset. + + :ref:`NXion`: + A base class to describe molecular ions with an adjustable number of atoms/isotopes building each ion. + For the usage in atom probe research the maximum number of atoms supported building a molecular ion + is currently set to a maximum of 32. Suggestions made in reference `DOI: 10.1017/S1431927621012241 `_ are used to map isotope to hash values with + which all possible isotopes (stable, radioactive, or synthetically generated ones) can be described. + + :ref:`NXfabrication`: + A base class to bundle manufacturer/technology-partner-specific details about + a component or device of an instrument. + + :ref:`NXpeak`: + A base class to describe peaks mathematically to detail how peaks in + mass-to-charge-state ratio histograms (aka mass spectra) are defined and + labelled as iontypes. + + :ref:`NXpump`: + A base class to describe details about pump(s) used as components of an instrument. + + :ref:`NXpulser_apm`: + A base class to describe the high-voltage and/or laser pulsing capabilities. + + :ref:`NXreflectron`: + A base class to describe a kinetic-energy-sensitive filtering device + for time-of-flight (ToF) mass spectrometry. + + :ref:`NXstage_lab`: + A base class to describe the specimen fixture including the cryo-head. + Nowadays, stages of microscopes represent small-scale laboratory platforms. + Therefore, there is a need to define the characteristics of such stages in more detail, + especially in light of in-situ experiments. Many similarities exists between a stage + in an electron microscope and one in an atom probe instrument. Both offer fixture + functionalities and additional components for applying e.g. stimuli on the specimen. + +Microscopy experiments, not only taking into account those performed on commercial instruments, offer users to apply a set of +data processing steps. Some of them are frequently applied on-the-fly. For now we represent these steps with specifically named +instances of the :ref:`NXprocess` base class. + +Data processing steps are essential to transform measurements into knowledge. Therefore, these steps +should be documented to enable reproducible research, ideally numerically, and learn how pieces of information are connected. +In what follows, an example is presented how an open-source community software can be modified to use descriptions +of these computational steps. + +The respective research software here is the `paraprobe-toolbox `_ +The software is developed by `M. Kühbach et al. `_. +For atom probe research the proposal can also serve as a blue print how computational steps of other software +tool including commercial ones could be developed further to benefit from NeXus. + + +.. _IntroductionApmParaprobe: + +apmtools +######## + +The paraprobe-toolbox is an example of an open-source parallelized software for analyzing +point cloud data, for assessing meshes in 3D continuum space, and for studying the effects of +parameterization on descriptors of micro- and nanoscale structural features (crystal defects) +within materials when characterized and studied with atom probe. + +The need for a thorough documentation of the tools in not only the paraprobe-toolbox +was motivated by several needs: + +First, users of software would like to better understand and also be able to study for themselves +which individual parameters and settings for each tool exist and how configuring these +affects analyses quantitatively. This stresses the aspect how to improve documentation. + +Second, scientific software like paraprobe-toolbox implement numerical/algorithmical +(computational) workflows whereby data coming from multiple input sources +(like previous analysis results) are processed and carried through more involved analyses +within several steps inside the tool. The tool then creates output as files. This +provenance and workflow should be documented. + +Individual tools of paraprobe-toolbox are developed in C/C++ and/or Python. +Provenance tracking is useful as it is one component and requirement for making +workflows exactly numerically reproducible and thus to enable reproducibility (the "R" +of the FAIR principles of data stewardship). + +For tools of the paraprobe-toolbox each workflow step is a pair or triple of sub-steps: +1. The creation of a configuration file. +2. The actual analysis using the Python/or C/C++ tools. +3. The optional analyses/visualization of the results based on data in NeXus/HDF5 files generated by each tool. + +.. _StatusQuoApm: + +What has been achieved so far? +############################## + +This proposal summarizes work of members of the FAIRmat project, which is part of the `German +National Research Data Infrastructure `_. The here detailed +proposal documents how all tools of the paraprobe-toolbox were modified to generate +only well-defined configuration files as accepted input and yield specifically formatted output +files according to the following NeXus application definitions. + +Data and metadata between the tools are exchanged with NeXus/HDF5 files. This means that data +inside HDF5 binary containers are named, formatted, and hierarchically structured according +to application definitions. + +For example the application definition NXapm_paraprobe_config_surfacer specifies +how a configuration file for the paraprobe-surfacer tool should be formatted +and which parameters it contains including optionality and cardinality constraints. + +Thereby, each config file uses a controlled vocabulary of terms. Furthermore, +the config files store a SHA256 checksum for each input file. This implements a full +provenance tracking on the input files along the workflow. + +As an example, a user may first range their reconstruction and then compute spatial +correlation functions. The config file for the ranging tool stores the files +which hold the reconstructed ion position and ranging definitions. +The ranging tool generates a results file with the labels of each molecular ion. +This results file is formatted according to the tool-specific `results` +application definition. The generated results file and the reconstruction is +imported by the spatial statistics tool which again keeps track of all files +and reports its results in a spatial statistics tool results file. + +This design makes it possible to rigorously trace which numerical results were achieved +with specific inputs and settings using specifically-versioned tools. Noteworthy +this includes Y-junction on a graph which is where multiple input sources are +combined to generate new results. + +We are convinced that defining, documenting, using, and sharing application definitions +is useful and future-proof strategy for software development and data analyses as it enables +automated provenance tracking which happens silently in the background + +.. _ApmParaprobeAppDef: + +Application Definitions +####################### + +NXapm_paraprobe application definitions are in fact pairs of application definitions. +One for the configuration (input) side and one for the results (output) side. For each +tool one such pair is proposed: + + :ref:`NXapm_paraprobe_config_transcoder`: + Configuration of paraprobe-transcoder + Load POS, ePOS, APSuite APT, RRNG, RNG, and NXapm HDF5 files. + + :ref:`NXapm_paraprobe_results_transcoder`: + Results of paraprobe-transcoder + Store reconstructed positions, ions, and charge states. + + + :ref:`NXapm_paraprobe_config_ranger`: + Configuration of paraprobe-ranger + Apply ranging definitions and explore possible molecular ions. + + :ref:`NXapm_paraprobe_results_ranger`: + Results of paraprobe-ranger + Store applied ranging definitions and combinatorial analyses of all possible iontypes. + + + :ref:`NXapm_paraprobe_config_selector`: + Configuration of paraprobe-selector + Defining complex spatial regions-of-interest to filter reconstructed datasets. + + :ref:`NXapm_paraprobe_results_selector`: + Results of paraprobe-selector + Store which points are inside or on the boundary of complex spatial regions-of-interest. + + + :ref:`NXapm_paraprobe_config_surfacer`: + Configuration of paraprobe-surfacer + Create a model for the edge of a point cloud via convex hulls, alpha shapes. + + :ref:`NXapm_paraprobe_results_surfacer`: + Results of paraprobe-surfacer + Store triangulated surface meshes of models for the edge of a dataset. + + + :ref:`NXapm_paraprobe_config_distancer`: + Configuration of paraprobe-distancer + Compute analytical distances between ions to a set of triangles. + + :ref:`NXapm_paraprobe_results_distancer`: + Results of paraprobe-distancer + Store analytical distances between ions to a set of triangles. + + + :ref:`NXapm_paraprobe_config_tessellator`: + Configuration of paraprobe-tessellator + Compute Voronoi cells for if desired all ions in a dataset. + + :ref:`NXapm_paraprobe_results_tessellator`: + Results of paraprobe-tessellator + Store volume of all Voronoi cells about each ion in the dataset. + + + :ref:`NXapm_paraprobe_config_nanochem`: + Configuration of paraprobe-nanochem + Compute delocalization, iso-surfaces, analyze 3D objects, and composition profiles. + + :ref:`NXapm_paraprobe_results_nanochem`: + Results of paraprobe-nanochem + Store all results of delocalization, isosurface, and interface detection algorithms, + store all extracted triangulated surface meshes of found microstructural features, + store composition profiles and corresponding geometric primitives (ROIs). + + + :ref:`NXapm_paraprobe_config_intersector`: + Configuration of paraprobe-intersector + Assess intersections and proximity of 3D triangulated surface meshes in + continuum space to study the effect the parameterization of surface + extraction algorithms on the resulting shape, spatial arrangement, + and colocation of 3D objects via graph-based techniques. + + :ref:`NXapm_paraprobe_results_intersector`: + Results of paraprobe-intersector + Store graph of microstructural features and relations/link identified between them. + + + :ref:`NXapm_paraprobe_config_spatstat`: + Configuration of paraprobe-spatstat + Spatial statistics on the entire or selected regions of the reconstructed dataset. + + :ref:`NXapm_paraprobe_results_spatstat`: + Results of paraprobe-spatstat + Store spatial correlation functions. + + + :ref:`NXapm_paraprobe_config_clusterer`: + Configuration of paraprobe-clusterer + Import cluster analysis results of IVAS/APSuite and perform clustering + analyses in a Python ecosystem. + + :ref:`NXapm_paraprobe_results_clusterer`: + Results of paraprobe-clusterer + Store results of cluster analyses. + +.. _ApmParaprobeNewBC: + +Base Classes +############ + +We envision that the above-mentioned definitions can be useful not only to take +inspiration for other software tools in the field of atom probe but also to support +a discussion towards a stronger standardization of the vocabulary used. This is an +ongoing discussion in the field emission community `IFES `_. +We are happy for taking comments and suggestions. The use of base classes for atom probe +is motivated by the observation that the majority of data analyses in atom probe +use a common set of operations and conditions on the input data: + + :ref:`NXapm_input_reconstruction`: + A base class documenting from where reconstructed ion positions are imported. + + :ref:`NXapm_input_ranging`: + A base class documenting from where ranging definitions are imported. + The design of the ranging definitions is, thanks to :ref:`NXion`, so + general that all possible nuclids can be considered. + +A detailed inspection of spatial and other type of filters frequently used in analysis of atom probe +data revealed that it is better to define atom-probe-agnostic reusable concepts for filters: + + :ref:`NXspatial_filter`: + A base class proposing how a point cloud can be spatially filtered in a specific yet general manner. + This base class takes advantage of :ref:`NXcg_ellipsoid_set`, :ref:`NXcg_cylinder_set`, + and :ref:`NXcg_hexahedron_set` to cater for commonly used geometric primitives in atom probe. + The primitives are used for defining the shape and extent of a region of interest (ROI). + + :ref:`NXsubsampling_filter`: + A base class for a filter that can also be used for specifying how entries + like ions can be filtered via sub-sampling. + + :ref:`NXmatch_filter`: + A base class for a filter that can also be used for specifying how entries + like ions can be filtered based on their type or other descriptors like hit multiplicity. diff --git a/manual/source/classes/contributed_definitions/cgms-structure.rst b/manual/source/classes/contributed_definitions/cgms-structure.rst new file mode 100644 index 0000000000..ad0872731f --- /dev/null +++ b/manual/source/classes/contributed_definitions/cgms-structure.rst @@ -0,0 +1,238 @@ +.. _CgmsFeatures-Structure: + +============================ +Geometry and microstructures +============================ + +.. index:: + IntroductionCgms + PhysicsCgms + CgmsAppDef + CgmsBC + + +.. _IntroductionCgms: + +Introduction +############ + +The computational-geometry/microstructure-modeling-based part of the proposal +has the following aims: + +First, to contribute to efforts on standardizing a controlled vocabulary, definitions for terms, +and relations between terms, for computational-geometry-based descriptions of the structure of +materials and atomic configurations used when characterizing materials in experiments +and computer simulations. + +As far as NeXus is concerned, this proposed set of geometric primitives offer +a complementary alternative to the current set of base classes in NeXus for +constructive solid geometry (CSG) such as :ref:`NXcsg`, :ref:`NXoff_geometry`, or :ref:`NXquadric`. + +Second, to explore how terms which are frequently used by materials scientists in the field of +condensed-matter physics can be harmonized with definitions and terms offer by the NOMAD MetaInfo +description. NOMAD MetaInfo is the data schema of the NOMAD research data management system. + +Third, to yield a substantiated set of arguments and suggestions how descriptors for the structure +and the atomic architecture of materials can be harmonized. Especially this proposal reaches out to +other materials-science-related projects and consortia including the activities in the German NFDI +FAIRmat, NFDI-MatWerk, NFDI4Ing, NFDI4Chem, NFDI4Cat, MaRDI, and DAPHNE. + +.. _PhysicsCgms: + +Physics background +################## +Microstructural features or crystal defects are spatial arrangements of atoms. +Given their specific atomic arrangement and composition, such features have +specific constraints on the degrees of freedom. This causes these defects to have specific +properties (thermodynamic observables/descriptors). Provided well-defined coarse-graining procedures +are used and regions-of-interest and/or regions-of-applicability are defined, microstructural +features are often characterized and modelled to have associated thermodynamic descriptors. + +Another motivation for the proposal was the observation that frequently the design +of file formats for simulation software in the computational materials science especially +at the interface between condensed-matter physics and materials engineering are frequently +reimplementing the wheel when it comes to making decision how to store e.g. atom and feature positions +or how to document the shape of regions-of-interest, grids, crystals, grains, precipitates, and dislocations. +This generates a diversity of file formats and data schemas which hampers semantic interpretation +and interoperability. + +Maybe this is a historical burden given the large set of technical terms in place which then +motivated pragmatic solutions that have resulted in many research groups having developed +similar formats using similar descriptions. + +Defining crystal defects is a question of how to coarse-grain a given spatiotemporal set of atoms, +each having a nuclide type and position/trajectory. Different mathematical/geometrical methods exists +to determine how a point, a line, a surface, or a volumetric defect can be described and be spatiotemporally constrained through a geometrical model +with defined primitives and associated observables. + +The key motivation to such coarse-graining is to reduce the complexity of the description. +On the one hand to support visualization and scientific analyses - not only of crystal defect arrangements. +On the other hand it is the hope that using descriptors at a coarser level, i.e. nanometer, micrometer, and larger, +are still sufficiently accurate and precise to yield descriptors which avoid that one has +to account for the dynamics of each atom to predict or understand the properties +of defects and their dynamics. + +Experience has shown that computational-geometry-based descriptions +when combined with hierarchical clustering/labeling methods, applied on sets of +atoms and features turn out to yield useful descriptors. Examples include point, +line, surface defects, such as vacancies, solute cluster, dislocations, +disconnections, interfaces to name but a few. + +.. _CgmsBC: + +Base Classes +############ + +The following base classes are defined to incentivize the use of NeXus for using +computational-geometry-based descriptions. In what follows, base classes +for frequently used shapes and geometric primitives are proposed: + + :ref:`NXcg_sphere_set`: + A base class for a set of possibly dissimilar spheres. + + :ref:`NXcg_ellipsoid_set`: + A base class for a set of possibly dissimilar rotated ellipsoids. + + :ref:`NXcg_cylinder_set`: + A base class for a set of possibly dissimilar rotated cylinders. + + :ref:`NXcg_point_set`: + A base class for a collection of points with labels or mark data. + + :ref:`NXcg_polyline_set`: + A base class for a collection of lines and linearized segments. + + :ref:`NXcg_triangle_set`: + A base class for a collection (or soup) of triangles. + + :ref:`NXcg_parallelogram_set`: + A base class for a collection of possibly dissimilar parallelograms. + + :ref:`NXcg_triangulated_surface_mesh`: + A base class for a collection and/or mesh of triangles. + + :ref:`NXcg_polygon_set`: + A base class for a collection (or soup) of polygons. + + :ref:`NXcg_polyhedron_set`: + A base class for a collection (or soup) of polyhedra. + + :ref:`NXcg_roi_set`: + A container to host a number of different types of primitives. + + :ref:`NXcg_tetrahedron_set`: + A base class for a collection (or soup) of tetrahedra. + + :ref:`NXcg_hexahedron_set`: + A base class for a collection (or soup) of hexahedra to represent + e.g. simpler (bounding) boxes for e.g. binary trees. + +These base classes make use of base classes which describe data structures: + + :ref:`NXcg_face_list_data_structure`: + A base class to store the usual way how polygon/polyhedra data are reported: + Via a list of vertices and faces with identifiers and properties. + + :ref:`NXcg_half_edge_data_structure`: + A base class for more advanced but more efficiently traversable data structure: + A half-edge data structure is a useful complementary descriptor for + polygon/polyhedra which enables topological analyses and traversal of half-edges + about a topology of primitives. + + :ref:`NXcg_unit_normal_set`: + A base class for storing primitive unit normal vectors. + + :ref:`NXcg_geodesic_mesh`: + Geodesic meshes are useful for all applications when meshing the surface of a sphere + with many applications in the analyses of diffraction data. + + :ref:`NXcg_alpha_complex`: + Alpha shapes and alpha wrappings, specifically the special case of the + convex hull, are frequently used geometrical models for describing + a boundary or edge to a set of geometric primitives. + +Furthermore, a few base classes are defined for documenting the working with +discretized representations of material (area or volume) which can be useful +not only for stencil-based methods: + + :ref:`NXcg_grid`: + A base class for a grid of cells discretizing e.g. a computational domain + or computation with models using representative volume elements (RVEs). + + :ref:`NXisocontour`: + A base class for isocontour descriptions. + + :ref:`NXcg_marching_cubes`: + A base class to store metadata of a specific implementation of + the Marching Cubes algorithm, whose sensitivity to specific topological + configurations is known to result in different triangle soups. + This is relevant e.g. for computations of isocontours. + + :ref:`NXdelocalization`: + A base class to document procedures whereby a scalar field + is smoothened in a controlled manner (typically using kernel methods). + + :ref:`NXsimilarity_grouping`: + A base class defining an alias for NXclustering. + + :ref:`NXclustering`: + A base class to describe clustering of objects (such as atoms or features). + + :ref:`NXrotation_set`: + A base class to describe the relative orientation or rotation members + of a set of features/objects. + + :ref:`NXslip_system_set`: + A base class to describe a set of slip system/slip system family for + a given crystal structure. + + :ref:`NXms_feature_set`: + A base class to describe any nested set of features of a material at the + continuum-, micron-, or nano-scale, including representation of a topology + of molecules and atoms. + + :ref:`NXms_snapshot`: + A base class to describe the state of microstructural features + at a given point in time. + + :ref:`NXms_snapshot_set`: + A base class to store a set of :ref:`NXms_snapshot` objects. + + :ref:`NXchemical_composition`: + A base class to document (chemical) composition of a sample or a set of things. + +Finally, the following base classes allow data processing software to document its +input parameters and to summarize its performance statistics: + + :ref:`NXprogram`: + A base class for a specifically named and versioned program or library/component. + + :ref:`NXcs_filter_boolean_mask`: + A base class for a boolean mask. + + :ref:`NXcs_prng`: + A base class for settings of a pseudo-random number generator (PRNG) algorithm. + + :ref:`NXcs_profiling`: + A base class for holding a set of :ref:`NXcs_profiling_event` instances. + + :ref:`NXcs_profiling_event`: + A base class for documenting profiling/benchmark for an algorithm or computational step. + + :ref:`NXcs_computer`: + A base class for documenting a computer. + + :ref:`NXcs_cpu`: + A base class for documenting a central processing unit. + + :ref:`NXcs_gpu`: + A base class for documenting a graphical processing unit / accelerator. + + :ref:`NXcs_mm_sys`: + A base class for documenting the (main) memory (sub-)system. + + :ref:`NXcs_io_sys`: + A base class for documenting the input/output system. + + :ref:`NXcs_io_obj`: + A base class for storing data inside an :ref:`NXcs_io_sys` instance. diff --git a/manual/source/classes/contributed_definitions/container/ComplexContainerBeampath.png b/manual/source/classes/contributed_definitions/container/ComplexContainerBeampath.png new file mode 100644 index 0000000000..597cee834c Binary files /dev/null and b/manual/source/classes/contributed_definitions/container/ComplexContainerBeampath.png differ diff --git a/manual/source/classes/contributed_definitions/container/ComplexExampleContainer.png b/manual/source/classes/contributed_definitions/container/ComplexExampleContainer.png new file mode 100644 index 0000000000..4ffdd862da Binary files /dev/null and b/manual/source/classes/contributed_definitions/container/ComplexExampleContainer.png differ diff --git a/manual/source/classes/contributed_definitions/ellipsometry-structure.rst b/manual/source/classes/contributed_definitions/ellipsometry-structure.rst new file mode 100644 index 0000000000..35f0420a23 --- /dev/null +++ b/manual/source/classes/contributed_definitions/ellipsometry-structure.rst @@ -0,0 +1,179 @@ +.. _Ellipsometry-Structure: + +==================== +Optical Spectroscopy +==================== + +.. index:: + Ellipsometry + DispersiveMaterial + + +.. _Ellipsometry: + +Ellipsometry +############ + +Ellipsometry is an optical characterization method to describe optical properties of interfaces and thickness of films. +The measurements are based on determining how the polarization state of light changes upon transmission and reflection. +Interpretation is based on Fresnel equations and numerical models of the optical properties of the materials. + +In the application definition we provide a minimum set of description elements allowing for a reproducible recording of ellipsometry measurements. + + +Application Definitions +----------------------- + + :ref:`NXopt`: + A generic application definition for optial spectorscopy measurements, including complex systems up to variable angle spectroscopic ellipsometry. + + :ref:`NXellipsometry`: + An application definition for ellipsometry measurements, including complex systems up to variable angle spectroscopic ellipsometry. + + +Base Classes +------------ + +There is a set of base classes for describing an optical experiment. + + :ref:`NXbeam_path` + A beam path consisting of one or more optical elements. + + NXbeam_path is used in NXopt to describe the beam path, i.e. the arrangement + of optical elements between the excitation source and the sample, or between + the sample and the detector unit. + + :ref:`NXbeam_splitter` + A beam splitter, i.e. a device splitting the light into two or more beams. + + Use two or more NXbeam_paths to describe the beam paths after the beam + splitter. In the dependency chain of the new beam paths, the first elements + each point to this beam splitter, as this is the previous element. + + :ref:`NXfiber` + An optical fiber, e.g. glass fiber. + + :ref:`NXlens_opt` + Description of an optical lens. + + :ref:`NXpolarizer_opt` + A spin polarizer. + + :ref:`NXwaveplate` + A waveplate or retarder. + + :ref:`NXenvironment` + Specify external parameters that have influenced the sample, + such as the surrounding medium, and varied parameters e.g. + temperature, pressure, pH value, optical excitation etc. + + + +.. _DispersiveMaterial: + +Dispersive Material +################### + +A dispersive material is a description for the optical dispersion of materials. +This description may be used to store optical model data from an ellipsometric analysis +(or any other technique) or to build a database of optical constants for optical properties of materials. + +Application Definition +---------------------- + + :ref:`NXdispersive_material`: + An application definition to describe the dispersive properties of a material. + The material may be isotropic, uniaxial or biaxial. Hence, it may contain up + to three dispersive functions or tables. + + + +Base Classes +------------ + +There is a set of base classes for describing a dispersion. + + :ref:`NXdispersion` + This is an umbrella base class for a group of dispersion functions to describe the material. + For a simple dispersion it may contain only on NXdispersion_function or NXdispersion_table entry. + If it contains multiple entries the actual dispersion is the sum of all dispersion functions and tables. + This allows for, e.g. splitting real and imaginary parts and describing them seperately or + adding a dielectric background (e.g. Sellmeier model) to an oscillator model (e.g. Lorentz). + + :ref:`NXdispersion_function` + This dispersion is described by a function and its single and repeated parameter values. + It follows a formula of the form ``eps = eps_inf + sum[A * lambda ** 2 / (lambda ** 2 - B ** 2)]`` + (Sellmeier formula). See the formula grammar below for an ebnf grammar for this form. + + :ref:`NXdispersion_single_parameter` + This denotes a parameter which is used outside the summed part of a dispersion function, + e.g. ``eps_inf`` in the formula example above. + + :ref:`NXdispersion_repeated_parameter` + This denotes arrays of repeated parameters which are used to build a sum of parameter values, e.g. + ``A`` and ``B`` are repeated parameters in the formula above. + + :ref:`NXdispersion_table` + This describes a tabular dispersion where the dielectric function is an array versus wavelength or energy. + +Formula Grammar +--------------- + +Below you find a grammar to which the formula should adhere and which can be used to parse and +evaluate the dispersion function. The terms ``single_param_name`` and ``param_name`` should be +filled with the respective single and repeated params from the stored data. + +.. code-block:: + + ?assignment: "eps" "=" kkr_expression -> eps + | "n" "=" kkr_expression -> n + + ?kkr_expression: expression + | "" "+" "1j" "*" term -> kkr_term + + ?expression: term + | expression "+" term -> add + | expression "-" term -> sub + + ?term: factor + | term "*" factor -> mul + | term "/" factor -> div + + ?factor: power + | power "**" power -> power + + + ?power: "(" expression ")" + | FUNC "(" expression ")" -> func + | "sum" "[" repeated_expression "]" -> sum_expr + | NAME -> single_param_name + | SIGNED_NUMBER -> number + | BUILTIN -> builtin + + ?repeated_expression: repeated_term + | repeated_expression "+" repeated_term -> add + | repeated_expression "-" repeated_term -> sub + + + ?repeated_term: repeated_factor + | repeated_term "*" repeated_factor -> mul + | repeated_term "/" repeated_factor -> div + + ?repeated_factor: repeated_power + | repeated_power "**" repeated_power -> power + + ?repeated_power: "(" repeated_expression ")" + | FUNC "(" repeated_expression ")" -> func + | SIGNED_NUMBER -> number + | NAME -> param_name + | BUILTIN -> builtin + + FUNC.1: "sin" | "cos" | "tan" | "sqrt" | "dawsn" | "ln" | "log" | "heaviside" + BUILTIN.1: "1j" | "pi" | "eps_0" | "hbar" | "h" | "c" + + %import common.CNAME -> NAME + %import common.SIGNED_NUMBER + %import common.WS_INLINE + + %ignore WS_INLINE + diff --git a/manual/source/classes/contributed_definitions/em-structure.rst b/manual/source/classes/contributed_definitions/em-structure.rst new file mode 100644 index 0000000000..61aee37e08 --- /dev/null +++ b/manual/source/classes/contributed_definitions/em-structure.rst @@ -0,0 +1,140 @@ +.. _Em-Structure: + +=================== +Electron microscopy +=================== + +.. index:: + IntroductionEm + EmAppDef + EmBC + EmAnalysisClasses + +.. _IntroductionEm: + +Introduction +############ + +A set of data schemas is proposed to describe components of an electron microscope and its eventually available focused-ion beam functionalities. +The data schemas were designed from the perspective of how electron microscopes are used by colleagues in the materials-science-branch of electron microscopy. +We realize that the biology-/bio-materials/omics-branch of electron microscopy is eventually in an already more mature state of discussion with respect +to data management practices. In what follows, the focus is on the usage of electron microscopy in condensed-matter physics, chemical physics of solids, +and materials engineering applications. As many of the components of electron microscopes used in the bio-materials communities are the same or at least many +components are very similar, it is likely that the here presented schema definitions can also inspire discussion and exchange with the bio-materials community. +Partner consortia in the German National Research Data Infrastructure are here e.g. NFDI-BioImage, NFDI-Microbiota, NFDI4Health, and e.g. NFDI-Neuro. + +Electron microscopes are functionally very customizable tools: Examples include multi-signal/-modal analyses which are frequently realized as on-the-fly computational analyses, regularly switching between GUI-based instrument control, computational steps, and more and more using high-throughput stream-based processing. Also artificial intelligence methods are increasingly used and are becoming more closely interconnected with classical modes of controlling the instrument and perform data processing. A challenge in electron microscopy is that these steps are often executed within commercial integrated control and analysis software. This makes it difficult to keep track of workflows in a technology-partner-agnostic, i.e. interdisciplinary manner. + +.. _EmAppDef: + +Application Definitions +####################### + +We acknowledge that it can be difficult to agree on a single application definition which is generally enough applicable yet not unnecessarily complex and useful for applications across a variety of instruments, technology partners, and instrument use cases. In what follows, the proposal conceptualizes first the basic components of an electron microscope and the usual workflow of how an electron microscope is used for collecting data with detectors via probing radiation-specimen-matter interaction mechanisms. + +In summary, scientists place a specimen/sample into the microscope, calibrate the instrument, take measurements, and may perform experiments, prepare their specimens with a focused ion beam, calibrate again, and take other measurements, before their session on the instrument ends. In between virtually all of these steps data are collected and stream in from different detectors probing different physical mechanisms of the interaction between electrons or other types of radiation with the specimen. + +A microscope session ends with the scientist removing the specimen from the instrument or parking it so that the next user can start a session. Occasionally, service technicians perform calibrations and maintenance which also can be described as a session on the microscope. We have provided base classes to describe these steps and events and an application definition for electron microscopy: + + :ref:`NXem`: + An application definition which explores the possibilities of electron microscopes. + +.. _EmBC: + +Base Classes +############ + +The following base classes are proposed to support modularizing the storage of pieces of information related to electron microscopy research: + + :ref:`NXaberration_model`, :ref:`NXaberration_model_ceos`, :ref:`NXaberration_model_nion`, :ref:`NXaberration`: + Base classes to describe procedures and values for the calibration of aberrations based on + conventions of different companies active in the field of aberration correction. + + :ref:`NXaperture_em`: + A base class to describe an aperture. + + :ref:`NXchamber`: + A base class to describe the chamber as a part of the microscope or storage unit + for transferring specimens in between or within an instrument. + + :ref:`NXcoordinate_system_set`: + A base class to describe different coordinate systems used and/or to be harmonized + or transformed into one another. + + :ref:`NXcorrector_cs`: + A base class to describe details about corrective lens or compound lens devices + which reduce the aberration of an electron beam. + + :ref:`NXebeam_column`: + A base class serving the possibility to group the components relevant for generating + and shaping the electron beam. + + :ref:`NXevent_data_em`: + A base class representing a container to hold time-stamped and microscope-state- + annotated data during a session at an electron microscope. + + :ref:`NXevent_data_em_set`: + A base class to group all :ref:`NXevent_data_em` instances. + + :ref:`NXibeam_column`: + A base class serving the possibility to group the components relevant for generating + and shaping an ion beam of an instrument to offer focused-ion beam (milling) capabilities. + + :ref:`NXimage_set`: + Base classes for storing acquisition details for individual images or stacks of images. Specialized versions can be defined. Each such uses controlled vocabulary terms for group name prefixes like **adf** annular dark field, **bf** bright field, **bse** backscattered electron, **chamber** camera to monitor the stage and chamber, **df** darkfield, **diffrac** diffraction, **ecci** electron channeling contrast imaging, **kikuchi** electron backscatter diffraction, **ronchigram** - convergent beam diffraction pattern, or **se** secondary electron. + + :ref:`NXinteraction_vol_em`: + A base class to describe details about e.g. the assumed or simulated volume of interaction of the electrons with the specimen. + + :ref:`NXion`: + A base class to describe molecular ions with an adjustable number of atoms/isotopes building each ion. Right now the maximum number of atoms supported building a molecular ion is 32. Suggestions made in reference `DOI: 10.1017/S1431927621012241 `_ are used to map isotope to hash values with which all possible isotopes can be described. + + :ref:`NXlens_em`: + A base class to detail an electro-magnetic lens. In practice, an electron microscope has many such lenses. It is possible to specify as many lenses as necessary to represent eventually each single lens of the microscope and thus describe how the lenses are affecting the electron beam. This can offer opportunities for developers of software tools which strive to model the instrument e.g. to create digital twins of the instrument. We understand there is still a way to go with this to arrive there though. Consequently, we suggest to focus first on which details should be collected for a lens as a component so that developers of application definitions can take immediate advantage of this work. + + :ref:`NXfabrication`: + A base class to bundle manufacturer/technology-partner-specific details about a component or device of an instrument. + + :ref:`NXoptical_system_em`: + A base class to store for now qualitative and quantitative values of frequent interest + which are affected by the interplay of the components and state of an electron microscope. + Examples are the semiconvergence angle or the depth of field and depth of focus, the magnification, or the camera length. + + :ref:`NXpeak`: + A base class to describe peaks mathematically. + + :ref:`NXpump`: + A base class to describe details about pump(s) as components of an electron microscope. + + :ref:`NXscanbox_em`: + A base class to represent the component of an electron microscope which realizes a controlled deflection + (and eventually shift, blanking, and/or descanning) of the electron beam to illuminate the specimen in a controlled manner + This base class can be used to document the scan pattern. The base class focuses mostly on the concept idea that there + is a component in a microscope which controls eventually multiple other components such as beam deflectors to achieve deflection. + + :ref:`NXspectrum_set`: + A base class and specializations comparable to :ref:`NXimage_set` but for storing spectra. Specialized base classes should use including controlled vocabulary items as prefixes such as **eels** electron energy loss spectroscopy, **xray** X-ray spectroscopy (EDS/STEM, EDX, SEM/EDX, SEM/EDS), **auger** Auger spectroscopy, or **cathodolum** for cathodoluminescence spectra. + + :ref:`NXstage_lab`: + A base class to describe the stage/specimen holder which offers place for the documentation of the small-scale laboratory functionalities + which modern stages of electron microscopes typically offer. + + +.. _EmAnalysisClasses: + +We provide specific base classes which granularize frequently collected or analyzed quantities in specific application fields of electron microscopy to deal +with the situation that there are cases were logical connections between generated data artifacts mainly exist for the fact that the data artifacts were +collected during a workflow of electron microscopy research (e.g. taking measurements and then performing method-specific analyses generating new data and conclusions). We see a value in granularizing out these pieces of information into own classes. In fact, one limitation of application definitions in NeXus is currently that they define a set of constraints on their graph of controlled concepts and terms. If we take for example diffraction experiments with an electron microscope, it is usually the case that (diffraction) patterns are collected in the session at the microscope. However, all scientifically relevant conclusions are typically drawn later, i.e. through post-processing the collected diffraction (raw) data. These numerical and algorithmic steps define computational workflows were data from an instance of an application definition such as NXem are used as input but many additional concepts and constraints are applied without these demanding necessarily for changing constraints on fields or groups of NXem. If we were to modify NXem for these cases, NXem would combinatorially diverge as every different combination of required constraints demands having an own but almost similar application definition. For this reason, the concept of partner application definition are currently used which have fields/links whereby specifically relevant sources of information are connected to e.g. NXem. + +More consolidation through the use of NXsubentry classes should be considered in the future. For now we use an approach whereby base classes are combined to reuse vocabulary and a hierarchical organization of pieces of information with specific constraints which are relevant only for specific usage of such data by specific tools used by an eventually smaller circle of users. + + :ref:`NXem_ebsd`: + Application definition for collecting and indexing Kikuchi pattern into orientation maps for the two-dimensional, three- (serial sectioning) and four-dimensional (spatial and time-dependent) case. + +The definition of several new base classes is motivated by by NXem_ebsd: + + :ref:`NXem_conventions`, :ref:`NXem_conventions_ebsd`: + A base class to store all reference frames and rotation conventions which are necessary to interpret the alignment and conventions used when working with orientation data. + + :ref:`NXcrystal_structure`: + A base class to store crystalline phase/structure used for a simulation of diffraction pattern and comparison of these pattern against patterns to support indexin. diff --git a/manual/source/classes/contributed_definitions/icme-structure.rst b/manual/source/classes/contributed_definitions/icme-structure.rst new file mode 100644 index 0000000000..07aa6ee4e1 --- /dev/null +++ b/manual/source/classes/contributed_definitions/icme-structure.rst @@ -0,0 +1,40 @@ +.. _Icme-Structure: + +============================================== +Integrated Computational Materials Engineering +============================================== + +.. index:: + IcmeMsModels + +.. _IcmeMsModels: + +Application definitions for ICME models +####################################### + +It is important to embrace the large research community of materials engineers +as they are frequent users of electron microscopy and atom probe microscopy. +ICME is an abbreviation for Integrated Computational Materials Engineering, which is +a design strategy and workflow whereby physics-based modelling of microstructure +evolution is used to understand the relations between the microstructure and +its technologically relevant descriptors to understand and tailor properties of materials. + +The following application definitions are proposed to support the discussion on how +materials-engineering-specific data schemas can connect to or be mapped on +concepts which are equally modellable with NeXus: + + :ref:`NXms`: + An application definition for arbitrary spatiotemporally resolved simulations. + + :ref:`NXms_recon`: + A base class for documenting results of reconstructed microstructures. + + :ref:`NXms_score_config`: + A specific example of how :ref:`NXapm_paraprobe_config_ranger` can be + specialized for documenting the configuration of a computer simulation + with the static recrystallization cellular automata model SCORE. + + :ref:`NXms_score_results`: + A specific example of how :ref:`NXms` can be specialized for documenting + results of computer simulations with the static recrystallization + cellular automata model SCORE. diff --git a/manual/source/classes/contributed_definitions/mpes-structure.rst b/manual/source/classes/contributed_definitions/mpes-structure.rst new file mode 100644 index 0000000000..df89809bfb --- /dev/null +++ b/manual/source/classes/contributed_definitions/mpes-structure.rst @@ -0,0 +1,76 @@ +.. _Mpes-Structure: + +======================================= +Photoemission & core-level spectroscopy +======================================= + +.. index:: + IntroductionMpes + MpesAppDef + MpesBC + MpesCommonBC + MpesExtendedBC + + +.. _IntroductionMpes: + +Introduction +############ + +Set of data storage objects to describe photoemission experiments including x-ray photoelectron spectroscopy (XPS), ultraviolet photoelectron spectroscopy (UPS), +hard x-ray photoelectron spectroscopy (HAXPES), angle-resolved photoemission spectroscopy (ARPES), two-photon photoemission (2PPE) +and photoemission electron microscopy (PEEM). Also includes descriptors for advanced specializations, such as spin-resolution, time resolution, +near-ambient pressure conditions, dichroism etc. + +.. _MpesAppDef: + +Application Definitions +####################### + +:ref:`NXmpes`: + A general appdef with minimalistic metadata requirements, apt to describe all photemission experiments. + +.. _MpesBC: + +Base Classes +############ + +:ref:`NXelectronanalyser`: + A base class to describe electron kinetic energy analizers. Contains the collective characteristics of the instrument such as energy resolution, and includes the following subclasses: + + :ref:`NXcollectioncolumn`: + Base class to describe the set of electronic lenses in the electron collection column (standard, PEEM, momentum-microscope, etc.). + + :ref:`NXenergydispersion`: + Base class to describe the energy dispersion sytem (hemispherical, time-of-flight, etc.). + + :ref:`NXspindispersion`: + Base class to describe the set of electronic lenses in the electron collection column. + +:ref:`NXmanipulator`: + A base class to describe the complex manipulators used in photoemission experiments, often with > 4 degrees of freedom, + cryogenic cooling and other advanced features. + +Three base classes to describe data processing, which can be used as subclasses of :ref:`NXprocess` if describing post-processing or as subclasses of :ref:`NXdetector` if describing live, electronics level processing: + + :ref:`NXcalibration`: + A base class to describe the 1D calibration of an axis, with a function mapping a raw data scale to a calibrated scale with the same number of points. + + :ref:`NXdistortion`: + A base class to describe the 2D distortion correction of an axis, with a matrix mapping a raw data image to a undistorted image. + + :ref:`NXregistration`: + A base class to describe the rigid transformations that are applied to an image. May be redundant as they can be described with :ref:`NXtransformations`. + +.. _MpesCommonBC: + +Common Base Classes +################### + +There are two related base classes that are common to other techniques: + + :ref:`NXlens_em`: + A class to describe all types of lenses. Includes electrostatic lenses for electron energy analysers. + + :ref:`NXdeflector` + A class to describe all kinds of deflectors, including electrostatic and magnetostatic deflectors for electron energy analysers. \ No newline at end of file diff --git a/manual/source/classes/contributed_definitions/sample-prep-structure.rst b/manual/source/classes/contributed_definitions/sample-prep-structure.rst new file mode 100644 index 0000000000..39f8249e9e --- /dev/null +++ b/manual/source/classes/contributed_definitions/sample-prep-structure.rst @@ -0,0 +1,20 @@ +.. _Synthesis-Structure: + +================== +Sample preparation +================== + +.. index:: + SamplePreparation + +.. _SamplePreparation: + +Document steps of wet-lab sample preparation +############################################ + +Virtually all experiments require a preparation of the sample. As most techniques are surface-sensitive or probe exclusively the surface, the use of careful preparation +techniques is the key to successful experiments. Unfortunately, the quality of such processes is often difficult to reproduce. Nevertheless, documenting how samples +are prepared is relevant. This part of the proposal provides prototypes how descriptions of steps performed by human or robots in a lab could be described using NeXus. + + :ref:`NXlab_electro_chemo_mechanical_preparation`, :ref:`NXlab_sample_mounting`: + Prototype application definitions for documenting steps during sample preparation. diff --git a/manual/source/classes/contributed_definitions/sts-structure.rst b/manual/source/classes/contributed_definitions/sts-structure.rst new file mode 100644 index 0000000000..42aef5e6e6 --- /dev/null +++ b/manual/source/classes/contributed_definitions/sts-structure.rst @@ -0,0 +1,47 @@ +.. _Stm-Structure: + +=============================== +Scanning Tunneling Spectroscopy +=============================== + +.. index:: + StsAppDef + StsBC + +.. _StsAppDef: + +Application Definition +###################### + + :ref:`NXsts`: + An application definition for scanning tunneling spectroscopy experiments. + +.. _StsNewBC: + +Base Classes +############ + + :ref:`NXamplifier`: + A base class + + :ref:`NXbias_spectroscopy`: + A base class + + :ref:`NXcircuit`: + A base class + + :ref:`NXiv_bias`: + A base class + + :ref:`NXlockin`: + A base class + + :ref:`NXpid`: + A base class + + :ref:`NXpositioner_sts`: + A base class + + :ref:`NXsensor_scan`: + A base class + diff --git a/manual/source/classes/contributed_definitions/transport-structure.rst b/manual/source/classes/contributed_definitions/transport-structure.rst new file mode 100644 index 0000000000..3d06c840cf --- /dev/null +++ b/manual/source/classes/contributed_definitions/transport-structure.rst @@ -0,0 +1,24 @@ +.. _Transport-Structure: + +=================== +Transport Phenomena +=================== + +.. index:: + IntroductionTransport + TransportAppDef + + +.. _IntroductionTransport: + +Introduction +############ + + +.. _TransportAppDef: + +Application Definitions +####################### + + :ref:`NXiv_temp`: + Application definition for temperature dependent IV curve measurements. diff --git a/manual/source/conf.py b/manual/source/conf.py old mode 100644 new mode 100755 index 51b35e4bb3..bebe22b2ae --- a/manual/source/conf.py +++ b/manual/source/conf.py @@ -6,23 +6,23 @@ # -- Path setup -------------------------------------------------------------- -import sys, os, datetime +import datetime +import os +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - +# add the abs path to the custom extension for collecting the contributor variables from the rst files +sys.path.insert(0, os.path.abspath('../../../dev_tools/ext')) # -- Project information ----------------------------------------------------- -project = 'nexus' -author = 'NIAC, https://www.nexusformat.org' -copyright = u'1996-{}, {}'.format(datetime.datetime.now().year, author) -description = u'NeXus: A Common Data Format for Neutron, X-ray, and Muon Science' +project = 'NeXus-FAIRmat' +author = 'The FAIRmat collaboration' +copyright = u'2022-{}, {}'.format(datetime.datetime.now().year, author) +description = u'Proposal of NeXus expansion for FAIRmat data' # The full version, including alpha/beta/rc tags version = u'unknown NXDL version' @@ -36,20 +36,24 @@ # -- General configuration --------------------------------------------------- # https://github.com/nexusformat/definitions/issues/659#issuecomment-577438319 -needs_sphinx = '2.3' +needs_sphinx = '2.5' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx_toolbox.collapse', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', + 'sphinx_comments', 'sphinx.ext.todo', - 'sphinx_tabs.tabs' + 'sphinx_tabs.tabs', + 'contrib_ext' ] + # Show `.. todo` directives in the output # todo_include_todos = True @@ -67,8 +71,9 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -# html_theme = 'alabaster' -html_theme = 'sphinxdoc' +html_theme = 'alabaster' +# html_theme = 'sphinxdoc' +# html_theme = 'sphinx_rtd_theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -77,22 +82,86 @@ # Add extra files html_extra_path = ['CNAME'] - -html_sidebars = { +html_logo = 'img/FAIRmat_new.png' + +if html_theme== 'sphinx_rtd_theme': + html_theme_options = { + 'logo_only': False, + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False + } + def setup(app): + app.add_css_file('to_rtd.css') +elif html_theme== 'alabaster': # Alabaster allows a very high degree of control form Sphinx conf.py + html_sidebars = { '**': [ - 'localtoc.html', - 'relations.html', - 'sourcelink.html', - 'searchbox.html', + 'about.html', + 'navigation.html', + 'localtoc.html', + 'relations.html', + 'sourcelink.html', + 'searchbox.html', 'google_search.html' - ], -} + ], + } + html_theme_options = { + 'body_text_align': 'justify', + 'logo_name': True, + 'github_button': True, + 'github_type': 'watch', + 'github_repo': 'nexus_definitions', + 'github_user': 'FAIRmat-NFDI', + 'github_count': 'false', # We don't get the cute counter baloon if we want to point to the branch + 'sidebar_width': '300px', + 'body_max_width': 'auto', + 'page_width': 'auto', + 'font_size': '12pt', + 'font_family': 'Arial', + 'description': 'Proposal of NeXus expansion for FAIRmat data.', + 'show_powered_by': True, + 'sidebar_header': '#ffffff', + 'sidebar_hr': '#ffffff', + 'sidebar_link': '#ffffff', + 'sidebar_list': '#ffffff', + 'sidebar_link_underscore': '#ffffff', + 'sidebar_text': '#ffffff' + } + def setup(app): + app.add_css_file('to_alabaster.css') +else: + html_sidebars = { + '**': [ + 'localtoc.html', + 'relations.html', + 'sourcelink.html', + 'searchbox.html', + 'google_search.html' + ], + } + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = "../../../common/favicon.ico" # Output file base name for HTML help builder. htmlhelp_basename = 'NeXusManualdoc' +comments_config = { + "hypothesis": True +} + # -- Options for Latex output ------------------------------------------------- latex_elements = { - 'maxlistdepth':7, # some application definitions are deeply nested - 'preamble': '\\usepackage{amsbsy}\n' + 'maxlistdepth': 25, # some application definitions are deeply nested + 'preamble': r''' + \usepackage{amsbsy} + \listfiles + \DeclareUnicodeCharacter{1F517}{X} + \DeclareUnicodeCharacter{2906}{<=} + \DeclareUnicodeCharacter{394}{$\Delta$} + \DeclareUnicodeCharacter{2206}{$\Delta$}''' } diff --git a/manual/source/design.rst b/manual/source/design.rst index 956b102f18..64cbdc5a90 100644 --- a/manual/source/design.rst +++ b/manual/source/design.rst @@ -412,7 +412,7 @@ a URL to a group in another file. More information about the ``@napimount`` attribute is described in the *NeXus Programmers Reference*. [#]_ -.. [#] https://manual.nexusformat.org/_static/NeXusIntern.pdf +.. [#] https://github.com/nexusformat/code/raw/master/doc/api/NeXusIntern.pdf .. index:: link; external file, NeXus link diff --git a/manual/source/ellipsometry-structure.rst b/manual/source/ellipsometry-structure.rst new file mode 100644 index 0000000000..223643d685 --- /dev/null +++ b/manual/source/ellipsometry-structure.rst @@ -0,0 +1,136 @@ +.. _Ellipsometry-Structure-Fairmat: + +======================== +B4: Optical spectroscopy +======================== + +.. index:: + Ellipsometry1 + DispersiveMaterial1 + + +.. _Ellipsometry1: + +Ellipsometry +############## + +Ellipsometry is an optical characterization method to describe optical properties of interfaces and thickness of films. The measurements are based on determining how the polarization state of light changes upon transmission and reflection. Interpretation is based on Fresnel equations and numerical models of the optical properties of the materials. + +In the application definition we provide a minimum set of description elements allowing for a reproducible recording of ellipsometry measurements. + + +Application Definitions +----------------------- + +We created one application definition: + + :ref:`NXellipsometry`: + A general application definition for ellipsometry measurements, including complex systems up to variable angle spectroscopic ellipsometry. + + +Dispersive Material +################### + +A dispersive material is a description for the optical dispersion of materials. +This description may be used to store optical model data from an ellipsometric analysis +(or any other technique) or to build a database of optical constants for optical properties of materials. + +Application Definition +---------------------- + + :ref:`NXdispersive_material`: + An application definition to describe the dispersive properties of a material. + The material may be isotropic, uniaxial or biaxial. Hence, it may contain up + to three dispersive functions or tables. + + + +Base Classes +------------ + +There is a set of base classes for describing a dispersion. + + :ref:`NXdispersion` + This is an umbrella base class for a group of dispersion functions to describe the material. + For a simple dispersion it may contain only on NXdispersion_function or NXdispersion_table entry. + If it contains multiple entries the actual dispersion is the sum of all dispersion functions and tables. + This allows for, e.g. splitting real and imaginary parts and describing them seperately or + adding a dielectric background (e.g. Sellmeier model) to an oscillator model (e.g. Lorentz). + + :ref:`NXdispersion_function` + This dispersion is described by a function and its single and repeated parameter values. + It follows a formula of the form ``eps = eps_inf + sum[A * lambda ** 2 / (lambda ** 2 - B ** 2)]`` + (Sellmeier formula). See the formula grammar below for an ebnf grammar for this form. + + :ref:`NXdispersion_single_parameter` + This denotes a parameter which is used outside the summed part of a dispersion function, + e.g. ``eps_inf`` in the formula example above. + + :ref:`NXdispersion_repeated_parameter` + This denotes arrays of repeated parameters which are used to build a sum of parameter values, e.g. + ``A`` and ``B`` are repeated parameters in the formula above. + + :ref:`NXdispersion_table` + This describes a tabular dispersion where the dielectric function is an array versus wavelength or energy. + +Formula Grammar +--------------- + +Below you find a grammar to which the formula should adhere and which can be used to parse and +evaluate the dispersion function. The terms ``single_param_name`` and ``param_name`` should be +filled with the respective single and repeated params from the stored data. + +.. code-block:: + + ?assignment: "eps" "=" kkr_expression -> eps + | "n" "=" kkr_expression -> n + + ?kkr_expression: expression + | "" "+" "1j" "*" term -> kkr_term + + ?expression: term + | expression "+" term -> add + | expression "-" term -> sub + + ?term: factor + | term "*" factor -> mul + | term "/" factor -> div + + ?factor: power + | power "**" power -> power + + + ?power: "(" expression ")" + | FUNC "(" expression ")" -> func + | "sum" "[" repeated_expression "]" -> sum_expr + | NAME -> single_param_name + | SIGNED_NUMBER -> number + | BUILTIN -> builtin + + ?repeated_expression: repeated_term + | repeated_expression "+" repeated_term -> add + | repeated_expression "-" repeated_term -> sub + + + ?repeated_term: repeated_factor + | repeated_term "*" repeated_factor -> mul + | repeated_term "/" repeated_factor -> div + + ?repeated_factor: repeated_power + | repeated_power "**" repeated_power -> power + + ?repeated_power: "(" repeated_expression ")" + | FUNC "(" repeated_expression ")" -> func + | SIGNED_NUMBER -> number + | NAME -> param_name + | BUILTIN -> builtin + + FUNC.1: "sin" | "cos" | "tan" | "sqrt" | "dawsn" | "ln" | "log" | "heaviside" + BUILTIN.1: "1j" | "pi" | "eps_0" | "hbar" | "h" | "c" + + %import common.CNAME -> NAME + %import common.SIGNED_NUMBER + %import common.WS_INLINE + + %ignore WS_INLINE + diff --git a/manual/source/em-structure.rst b/manual/source/em-structure.rst new file mode 100644 index 0000000000..ae9fed2f74 --- /dev/null +++ b/manual/source/em-structure.rst @@ -0,0 +1,9 @@ +.. _Em-Structure-Fairmat: + +======================= +B1: Electron microscopy +======================= + +Electron microscopy is a cross-cutting characterization technique of key demand and relevance within materials science, materials engineering, and bio-science/omics research communities. + +A status report of the ongoing work on data schemas for electron microscopy using NeXus is available here: :ref:`Em-Structure`. diff --git a/manual/source/fairmat-cover.rst b/manual/source/fairmat-cover.rst new file mode 100644 index 0000000000..9545073b62 --- /dev/null +++ b/manual/source/fairmat-cover.rst @@ -0,0 +1,146 @@ +.. _FairmatCover: + +======================= +FAIRmat-NeXus Proposal +======================= + +.. index:: + IntroductionCover + OurScope + Outreach + WhichData + WhatIsNew + +Aim +######################### + +Experiments nowadays create a set of very often voluminous and diverse numerical data and metadata. +These pieces of information represent entities of what is effectively a graph of materials data. +This graph can have a very large number of nodes and edges representing the large variety of +relations which scientists ideally want to identify and master +when transforming experimental research into knowledge. + +Experimentalists face the challenge that these pieces of information come at different levels +of granularity and format, of which many need to be better documented. You have very likely experienced +yourself how file and data formats are routinely encountered tasks to master in your daily +research practice and you might have questioned how these formats are currently handled +when you want to produce FAIR research data and publications. + +The NeXus-FAIRmat proposal is an interdisciplinary data science activity initiated by scientists of the +condensed-matter physics community which strives to develop community-maintained open file and data formats +for describing specific experimental techniques, their numerical data and metadata, +and strategies how to exchange these pieces of information. + +.. _IntroductionCover: + +The FAIRmat proposal to NeXus is an effort by the community of scientists of the `FAIRmat consortium `_ +to refine and expand the structure of NeXus. As a project which aims at creating an infrastructure +for experimental data to be findable, accessible, interoperable, and reusable (FAIR) in the fields of +condensed-matter physics and the chemical physics of solids, FAIRmat has adopted NeXus as the common format. + +`NeXus `_ is a common data exchange format which has its origin in the community of +scientists performing neutron, x-ray, and muon experiments. The development of NeXus is coordinated by the +NeXus International Advisory Committee (NIAC). +NeXus defines a schema of data entries with a controlled vocabulary and defined relations between the entries. +NeXus offers not only tools to document these schema definitions in a version-controlled manner but +also tools to check and verify how and if specific instances of NeXus schemata comply with the intended +schema definition when the data are written to files. Although, the Hierarchical Data Format (HDF5) is the +most commonly used file format to write NeXus file to, NeXus can also be used with other file formats. + +NeXus defines domain-specific rules for organizing data in e.g. HDF5 files (:ref:`application.definitions`) +and defines a dictionary of well-defined domain-specific (a vocabulary) of terms (:ref:`base.class.definitions`). +The meta- and numerical data in a NeXus file represent a hierarchical graph which encodes a specifically +granularized representation of relevant pieces of information and results that should be stored with +an experiment. + +Base classes and application definitions are two key components of the NeXus data model. +A base class represents a set of numerical data and metadata which specify details about +scientists, projects, instruments, and other physical devices, including the numerical data +and metadata which are deemed relevant for their description and the associated +computational analyses. Application definitions are constructed from combining such experiment- +and research-question-specifically customized base classes. + +In this combination, an application definition is a data contract between +a producer and a consumer of these scientific data. + +This design has sufficient flexibility to cover any experimental technique and instrumentation, while +ensuring rigorous, application-specific structures that can be processed in an automated manner. + +In cases where base classes or application definitions have not yet been proposed advantage of NeXus can be taken +if the respective scientific community explicitly designs, implements, uses, and continuously evolves +these classes and definitions. Here the role of the NIAC is to support the community with +data modeling and data science technical expertise, thus taking an important role of +cross-disciplinary review. + +The NeXus-FAIRmat proposal represents the results of this development for experiments and use cases which have not yet used NeXus. +Specifically, the proposal includes cases in the materials-science-branch of electron microscopy (EM), photo-emission spectroscopy, +ellipsometry, and the field of atom probe tomography and related field-ion microscopy, here jointly referred to as atom probe microscopy. + + +The documentation available here includes parts of the contents of the NeXus User Manual (also available `here `_), +reported here for the convenience of the user, but is restricted to the parts most pertinent to the our proposal. + +For more extensive information, please visit the original manual. + +.. _OurScope: + +Our scope and perspective +######################### + +Thanks to a cooperative approach across a wide variety of experimental techniques, +the NeXus-FAIRmat proposal of the FAIRmat project has an opportunity +to expand the set of data/metadata accurately described via NeXus. + +With a closely-connected team of domain experts, we will develop such expansion while at the same time maintaining +a consistent structure across different techniques and methods, striving for the maximum simplicity of use. + +Achieving a standardized and FAIR data structure has a wide spectrum of advantages, ranging from radical +progress in scientific transparency to the development of new, far-reaching tools that can be shared across +the whole scientific community. The convenience of such tools can range from guaranteeing data reusability within +a single lab, to enabling open-source availability of ready-to-use advanced analysis software. + +Perhaps the greatest resource, however, is the inclusion of experimental datasets in the `NOMAD Laboratory `_: +a data infrastructure that already hosts the largest computational material science repository in the world, representing a +homogeneous and machine-readable archive, a human-accessible encyclopedia of materials data +with tools for automated artificial intelligence analyses and data access. + +.. _Outreach: + +Outreach to the community +########################## + +A data infrastructure is not effective if it does not integrate seamlessly in the day-to-day workflow of a laboratory. +For this reason, we approach our newly developed NeXus proposal as a community-driven development. +We have drafted an accurate and consistent expansion of NeXus capabilities for a number of lab-based techniques, +but need extensive testing and tweaking of its characteristics by the community. + +If your data is generated with these techniques and you are interested in producing FAIR data and accessing the FAIRmat tools, we +invite you to try out our proposed structure. If you find any conflicts or inconsistencies, please raise them to us using the +comment section. These comments are implemented with `Hypothesis `_, a modern web annotation +tool from the journalism community. The commenting function for each page of the proposal enable you to contribute to the +creation of a more consistent and practical NeXus structure which, in our firm belief, can serve your community and beyond. + +If you do not find your specific experimental technique but would be interested in participating in the development +of a standard using NeXus, feel also very much invited to contact us directly at the `FAIRmat-Team `_. + +.. _WhichData: + +Which data should I convert? +############################ + +You are free to choose at which point in the workflow you wish to convert the data to NeXus, as its flexibility allows to +describe raw data, pre-processed data and fully processed data. As an entry step, we suggest to use a test dataset +that is fully processed and already published (or, alternatively, of negligible scientific content). These datasets, indeed, require often the most +extensive metadata description, but are most easily converted to NeXus, with minimal to no impact on the data processing pipeline. + +In fact, a low barrier (but high yield!) way to participate to FAIRmat consists in converting only fully processed datasets that +are used for a publication, and publishing them via FAIRmat only when your manuscript is in press. This makes the task of +converting to NeXus much more sporadic than fairifying raw data, to the point that it may be even acceptable not to automate it. At the same time, +it guarantees full control on the data until publication. We are confident that if you take this approach, more appetite will come with eating, +and you will be naturally inclined to gradually integrate FAIRmat structures and tools further in your workflow. + + +.. _WhatIsNew: + +.. What is New? +.. ############## diff --git a/manual/source/icme-structure.rst b/manual/source/icme-structure.rst new file mode 100644 index 0000000000..8ff31eaf78 --- /dev/null +++ b/manual/source/icme-structure.rst @@ -0,0 +1,9 @@ +.. _Icme-Structure-Fairmat: + +============================================== +Integrated Computational Materials Engineering +============================================== + +With a large set of data schemas for computational geometry, and methods from condensed-matter physics as well as materials engineering we are convinced that the NeXus standardization framework can be one component of efforts to harmonize and consolidate the zoo of descriptions and data schemas used within the field of Integrated Computational Materials Engineering (ICME). + +A status report along these lines of thoughts and ongoing efforts is available here: :ref:`Icme-Structure`. diff --git a/manual/source/img/FAIRmat.png b/manual/source/img/FAIRmat.png new file mode 100644 index 0000000000..034aa452de Binary files /dev/null and b/manual/source/img/FAIRmat.png differ diff --git a/manual/source/img/FAIRmat_new.png b/manual/source/img/FAIRmat_new.png new file mode 100644 index 0000000000..e5b7158a78 Binary files /dev/null and b/manual/source/img/FAIRmat_new.png differ diff --git a/manual/source/img/FAIRmat_new_with_text.png b/manual/source/img/FAIRmat_new_with_text.png new file mode 100644 index 0000000000..ef14aa0da6 Binary files /dev/null and b/manual/source/img/FAIRmat_new_with_text.png differ diff --git a/manual/source/index.rst b/manual/source/index.rst index bb47170555..d2d0ee59b8 100644 --- a/manual/source/index.rst +++ b/manual/source/index.rst @@ -1,35 +1,51 @@ -.. image:: img/NeXus.png - :width: 40% - ======================================= User Manual and Reference Documentation ======================================= +Welcome to the user manual of the NeXus for FAIRmat project. + https://www.nexusformat.org/ .. toctree:: :maxdepth: 2 - :numbered: 4 + :numbered: 5 - user_manual - examples/index - ref_doc + fairmat-cover + nexus-index + em-structure + mpes-structure + ellipsometry-structure + apm-structure + transport-structure + sts-structure + cgms-structure + north-structure + laboratory-structure + icme-structure napi - community - installation - utilities history - docs_about + + + ----------- .. rubric:: Publishing Information -This manual built |today|. +| This commit time code <>. +| This commit identifier <>. +| This manual built |today|. + +.. rubric:: Acknowledgements + +| The FAIRmat project is funded by the Deutsche Forschungsgemeinschaft +| (`DFG `_, German Research Foundation) - project 460197019. +| FAIRmat is a consortium within the `German NFDI `_. + .. seealso:: - This document is available in these formats online: + The extended NeXus documentation: :HTML: https://manual.nexusformat.org/ @@ -46,11 +62,14 @@ This manual built |today|. :PDF: https://manual.nexusformat.org/_static/NXImpatient.pdf -.. Suggestions for adding to this manual: + FAIRmat website: + + ``_ + + NOMAD website: + + ``_ + + + - Look for some other "section" such as "introduction.rst" and act similarly. - Any examples go as text files in the examples/ subdirectory and are pulled into - Sphinx inside a :directive:`literalcode` directive. Look for the pattern - or wing it. If you are ambitious, add index entries. Many examples of the - constructs you might use are already in the manual. - diff --git a/manual/source/introduction-napi.rst b/manual/source/introduction-napi.rst index fc3c3a2d2b..160de64a07 100644 --- a/manual/source/introduction-napi.rst +++ b/manual/source/introduction-napi.rst @@ -26,7 +26,7 @@ in the :ref:`NAPI ` chapter and may be downloaded from the NeXus development site. [#]_ For an even more detailed description of the internal workings of NAPI -see the `NeXus Internals manual `_, copied from the NeXus code repository. +see the `NeXus Internals manual `_, copied from the NeXus code repository. That document is written for programmers who want to work on the NAPI itself. If you are new to NeXus and just want to implement basic file reading or writing you should not start by reading that. diff --git a/manual/source/laboratory-structure.rst b/manual/source/laboratory-structure.rst new file mode 100644 index 0000000000..568e6d4823 --- /dev/null +++ b/manual/source/laboratory-structure.rst @@ -0,0 +1,9 @@ +.. _Lab-Structure-Fairmat: + +================== +Sample preparation +================== + +Prototype application definitions for documenting steps during sample preparation are a part of ongoing work. + +A status quo of this work is reported here: :ref:`Synthesis-Structure` via the :ref:`NXlab_electro_chemo_mechanical_preparation` and the :ref:`NXlab_sample_mounting` application definitions. These are drafts. diff --git a/manual/source/mpes-structure.rst b/manual/source/mpes-structure.rst new file mode 100644 index 0000000000..73a1768c26 --- /dev/null +++ b/manual/source/mpes-structure.rst @@ -0,0 +1,30 @@ +.. _Mpes-Structure-Fairmat: + +======================================= +Photoemission & core-level spectroscopy +======================================= + +The NXmpes application definition is designed to describe data and metadata obtained from +various multidimensional photoemission spectroscopy (MPES) techniques. +This definition is very flexible and requires just a reasonable amount of +metadata to make the stored data interoperable and reproducible. +The only requirement for the actual data is the existence of an energy axis. + +The experimental techniques covered by this application definition are primarily limited +to photon-in photoelectron-out methods. If you are searching for related techniques, +there is a good chance you will find valuable information here. + +Example techniques covered by this application definition include: + +- X-ray/UV photoelectron spectroscopy (XPS/UPS) +- Angle-resolved photoemission spectroscopy (ARPES) +- Two-photon photoemission (2PPE) +- Photoemission electron microscopy (PEEM) + +Additionally, we offer descriptors for specialized applications, +such as spin- and time-resolution, near-ambient pressure conditions, dichroism, and more. + +Here's a list of application definitions related to photoemission spectroscopy: + + :ref:`NXmpes`: + A universal application definition with minimal metadata requirements for describing all photoemission experiments. diff --git a/manual/source/nexus-index.rst b/manual/source/nexus-index.rst new file mode 100644 index 0000000000..1e9bf529ac --- /dev/null +++ b/manual/source/nexus-index.rst @@ -0,0 +1,20 @@ +.. _NexusIndex: + +======================================= +NeXus Documentation +======================================= + +Welcome to the user manual of the NeXus. + +https://www.nexusformat.org/ + +.. toctree:: + :maxdepth: 2 + + user_manual + examples/index + ref_doc + community + installation + utilities + docs_about \ No newline at end of file diff --git a/manual/source/north-structure.rst b/manual/source/north-structure.rst new file mode 100644 index 0000000000..26526638d2 --- /dev/null +++ b/manual/source/north-structure.rst @@ -0,0 +1,26 @@ +.. _North-Structure-Fairmat: + +============================ +NOMAD OASIS Remote Tools Hub +============================ + +.. index:: + IntroductionNorth + IntroductionApmTools + +.. _IntroductionNorth: + +Introduction to NORTH +##################### +The NOMAD OASIS Remote Tools Hub (NORTH), is a `NOMAD OASIS `_ service which provides access to containerized applications. +These containers contain pre-configured scientific software of different academic communities and offer access to the data inside the NOMAD OASIS research data management system. +This page delivers status reports of ongoing work specific to NeXus and how NeXus is being used by tools within specific containers offered by NORTH. + +.. _IntroductionApmTools: + +apmtools container +################## + +One containerized application in NORTH and its apmtools container, is the paraprobe-toolbox. This software is developed by `M. Kühbach et al. `_. +The software provides an implementation which exemplifies how NeXus/HDF5 and community tools for atom probe can be used to document provenance and steps of post-processing +for many steps relevant within the field of atom probe tomography and related field-ion microscopy: Inspect :ref:`Apm-Structure` for a status report and details. diff --git a/manual/source/sed/entry-page.html b/manual/source/sed/entry-page.html new file mode 100644 index 0000000000..b7c84946c2 --- /dev/null +++ b/manual/source/sed/entry-page.html @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/manual/source/sts-structure.rst b/manual/source/sts-structure.rst new file mode 100644 index 0000000000..26d406c305 --- /dev/null +++ b/manual/source/sts-structure.rst @@ -0,0 +1,8 @@ +.. _Stm-Structure-Fairmat: + +=============================== +Scanning Tunneling Spectroscopy +=============================== + +Scientists of the scanning tunneling spectroscopy community and FAIRmat have worked together to create an application definition and related base classes for documenting scanning tunneling spectroscopy experiments. +This is one community under the large umbrella of scanning (probe) microscopy methods. A status report of these efforts will be reported here: :ref:`Stm-Structure`. diff --git a/manual/source/transport-structure.rst b/manual/source/transport-structure.rst new file mode 100644 index 0000000000..d75649a1fd --- /dev/null +++ b/manual/source/transport-structure.rst @@ -0,0 +1,14 @@ +.. _Transport-Structure-Fairmat: + +=================== +Transport Phenomena +=================== + +Work of scientists within FAIRmat how to handshake between instrument control software like EPICS and CAMELS using NeXus resulted in an application definition for exemplar temperature dependent IV curve measurements. +IV curve measurements are one example of a large group of so-called transport measurements. The key idea behind these is to monitor one or more observables under controlled environmental conditions and eventual stimuli applied on a sample. + +Many techniques especially used within materials engineering fall into this category and thus could make use of specializations or extensions of NXiv_temp. +Examples include hardness measurements, nanoindentation, resistance, electro-chemical probing, or diffusion. + + :ref:`NXiv_temp`: + Application definition for temperature dependent IV curve measurements. diff --git a/nyaml.mk b/nyaml.mk new file mode 100644 index 0000000000..baf000b560 --- /dev/null +++ b/nyaml.mk @@ -0,0 +1,25 @@ +BASE_CLASS_DIR := base_classes +CONTRIB_DIR := contributed_definitions +APPDEF_DIR := applications +NYAML_SUBDIR := nyaml +NXDL_BC_TARGETS = $(addprefix $(BASE_CLASS_DIR)/nyaml/,$(notdir $(patsubst %.nxdl.xml,%.yaml,$(wildcard $(BASE_CLASS_DIR)/*.nxdl.xml)))) +NXDL_APPDEF_TARGETS = $(addprefix $(APPDEF_DIR)/nyaml/,$(notdir $(patsubst %.nxdl.xml,%.yaml,$(wildcard $(APPDEF_DIR)/*.nxdl.xml)))) +NXDL_CONTRIB_TARGETS = $(addprefix $(CONTRIB_DIR)/nyaml/,$(notdir $(patsubst %.nxdl.xml,%.yaml,$(wildcard $(CONTRIB_DIR)/*.nxdl.xml)))) + +.PHONY: all nyaml + +$(BASE_CLASS_DIR)/$(NYAML_SUBDIR)/%.yaml : $(BASE_CLASS_DIR)/%.nxdl.xml +@mkdir -p $(@D) +nyaml2nxdl $< --output-file $@ + +$(CONTRIB_DIR)/$(NYAML_SUBDIR)/%.yaml : $(CONTRIB_DIR)/%.nxdl.xml +@mkdir -p $(@D) +nyaml2nxdl $< --output-file $@ + +$(APPDEF_DIR)/$(NYAML_SUBDIR)/%.yaml : $(APPDEF_DIR)/%.nxdl.xml +@mkdir -p $(@D) +nyaml2nxdl $< --output-file $@ + +nyaml: $(NXDL_BC_TARGETS) $(NXDL_APPDEF_TARGETS) $(NXDL_CONTRIB_TARGETS) + +all: nyaml \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 6d024bda3a..d27f482456 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,15 +1,18 @@ # Prepare for Documentation -lxml +lxml pyyaml +nyaml # Documentation building sphinx>=5 sphinx-tabs +sphinx-toolbox +sphinx_comments # Testing pytest # Code style and auto-formatting -black>=22.3 +black>=24.1.1 flake8>=4 isort>=5.10