diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml old mode 100755 new mode 100644 diff --git a/applications/NXapm.nxdl.xml b/applications/NXapm.nxdl.xml new file mode 100644 index 0000000000..1a65930e12 --- /dev/null +++ b/applications/NXapm.nxdl.xml @@ -0,0 +1,1597 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of hit qualities, the so-called hit types, distinguished. + + + + + Number of delay-line-detector (DLD) wires of the detector. + + + + + Number of bins used in the mass-to-charge-state-ratio spectrum. + + + + + Number of pulses collected in between start_time and end_time resolved by an + instance of :ref:`NXevent_data_apm`. If this is not defined, p is the number of + ions included in the reconstructed volume if the application definition is used + to store results of an already reconstructed dataset. + + + + + Number of pulses returned by the hit_finding algorithm. + Neither necessarily equal to p nor to n. + + + + + Number of ions spatially filtered from results of the hit_finding algorithm + from which an instance of a reconstructed volume has been generated. + These ions get new identifier assigned in the process, the so-called + evaporation_id. This identifier must not be confused with the pulse_id. + This value is typically smaller than both p and p_out. + + + + + Number of mass resolution values. + + + + + Application definition for real or simulated atom probe and field-ion microscopy experiments. + + Atom probe tomography and field-ion microscopy are methods for characterizing materials + through induced controlled extraction of individual atoms as ions and molecular ions from + a sharp needle-shaped specimen. + + Offering isotopic and nanometer-scale resolution, atom probe data enable quantification of + local chemical composition and computing of volumetric reconstructions which are models for + the atomic architecture of the small specimen volume analyzed. These reconstructions provide + input for characterization of atomic segregation at crystal defects. The term microstructural features + is considered as a narrow synonym for crystal defects. + + The aim of the NXapm application definition is to provide a general yet specific enough + solution to serialize artifacts for virtually all atom probe and field-ion microcopy experiments. + + Before summarizing the design of the base classes and the parts of the NXapm application definition, + it is worthwhile to recall and distinguish concepts that are related to atom extraction + events and the molecular ions that are frequently generated by the sequence of events: + + * An atom probe instrument uses laser or voltage pulsing events to trigger ion extraction events. + * These ions are accelerated in an electric field towards a position-sensitive detector system. + Physical events and corresponding signal on this detector is triggered by an ion hitting the detector. + Some of these events are not necessarily caused by or directly correlated with an identifiable pulsing event. + * Note that only a part the specimen volume can be measured and finite detection efficiency means that + not all atoms in the measured volume will be detected. Neutral atoms can escape detection. Some ions + escape detection because they hit into walls of the analysis_chamber. + + Raw data are typically processed as follows: + + * Detector pulses and their timing are processed and discriminated into signal events of different quality levels. + High quality events might be considered in further processing to identify the corresponding molecular ion + and its original position in the reconstructed volume. + * Signal calibration and filtering steps are applied to convert raw time-of-flight data to calibrated + mass-to-charge state ratio values and obtain calibrated impact positions on the detector. + * Ranging and identifying an ion that corresponds to each detector event. + Isotopic abundance and theoretical models inform these ranging algorithms. + * Finally, such selected ion impact positions and iontypes are used to compute a reconstructed volume of + the specimen using backprojection algorithms. In effect, an atom probe measurement is a combination of + a data acquisition and a data analysis workflow. + + Not only in AMETEK/Cameca's APSuite/IVAS software, which the majority of atom probers use, these concepts + are well distinguished. However, the algorithms used to transform correlations between pulses and physical + events into actual events, the so-called detector hits of ions, is a proprietary one. This algorithm is also + referred to as the hit finding algorithm. + + Due to this practical inaccessibility of details, virtually all atom probe studies currently use a reporting + schema where the course of the specimen evaporation is documented such that quantities are a function of + evaporation_id i.e. actual event/ion, i.e. after having the hit finding algorithm and correlations applied. + That is the evaporation_id values take the role of an implicit time and course of the experiment given that + ion extraction physically is a sequential process. + + This application definition includes fields that the atom probe community has decided to represent best practices + for reporting atom probe measurements. Exemplar mapping tables are provided for documents that reported these + best practices to translate technical term into concepts of the NXapm application definition. + + *The NeXus application definition NXapm defines a hierarchical data model with ten building blocks:* + + The data model represents a tree of concepts. The tree is constructed from groups of concepts representing + the branches, together with fields and attributes representing leaves. NXapm is defined by composing and + specializing base classes into the following ten categories: + + - The field ``definition`` specifies that the data schema is NXapm. In combination with + administrative metadata such as the attribute ``NeXus_version`` provided by :ref:`NXroot` this + specifies which version of NXapm the instance data in a NeXus/HDF5 file are compliant with. + - The fields ``run_number``, ``experiment_alias``, ``experiment_description`` and + the group ``userID`` provide concepts for storing organizational metadata that + contextualize the work within the research workflow and humans involved in this. + - The fields ``start_time``, ``end_time`` provide concepts for framing a temporal context for the research. + - The groups ``citeID``, ``noteID`` provide concepts for adding contextual details such as citations or notes + that are associated with the data, i.e. other artifacts that are deemed relevant when reporting about + a measurement or simulation. These groups are useful when NXapm is used as a serialization format for + technology-partner-agnostic archival of data and metadata that have been collected during a session with + an atom probe instrument. The terms run and session are understood as exact synonyms that refer to an + uninterrupted period of measurement. Resuming measurement on a specimen after an interruption is viewed + as a new run and the new data should not be appended to the previous run, but written to either a new NXentry, + or a new file. Removing the specimen from the instrument is an interruption. Changing evaporation conditions + while the specimen is remains in the analysis_chamber and resuming thereafter the measurement + is not considered as an interruption. It is a common strategy to probe the evaporation process for different + instrument parameters. Each individual collection should then though be stored in an own NXevent_data_apm + group. Parking the specimen to the buffer_chamber and resuming the measurement at a later stage is an interruption. + During a run, the microscope is used for a certain amount of time to characterize a single specimen. + - The groups ``sample`` and ``specimen`` provide concepts for storing metadata about the sample and the specimen, + i.e. the smaller part that was removed from the sample to be measured in the atom probe session. + The term "tip" in the context of atom probe research is considered jargon. + Specimen is an exact synonym for tip. + - The field ``operation_mode`` and group ``measurement`` provides concepts that + are useful for describing a measurement during a session with an atom probe or field-ion microscope. + This includes the chain of events of data and metadata that were collected during such a session. + - The group ``simulation`` provides concepts that are useful for describing a simulation of an + atom extraction, ionization, and ion trajectory simulation. Combined with ``measurement`` + this provides a data schema for defining a digital twin of the instrument and its setup. + - The groups ``consistent_rotations``, and ``NAMED_reference_frame`` provide concepts for + reporting coordinate systems (frames of reference) and rotation conventions that clarify how data + should be interpreted specifying the rotation of orientable objects in the microscope, its components, + or of crystals and crystal defects in the material analyzed. + - The group ``atom_probeID`` provides concepts for the computational workflows that were + used to convert raw detector data into reconstructed ion positions and documentation of + ranging definitions made. + - The group ``profiling`` provides concepts for reporting computational details such as + programs and libraries used, for documenting the libraries of virtual environments such as those used + by conda or python virtual environment, including details about the computing hardware used, and + documenting capabilities for performance analyses and benchmarking of the software or its parts. + + *Design choices:* + + Given that most atom probe instruments across the globe were built by AMETEK/Cameca and are delivered + with the AP Suite/IVAS software there is some homogeneity in how a measurement is performed and which data + artifacts and algorithms used for data processing. Complementary use of open-source software specifically for + the reconstruction, ranging, and later data processing stages contributes to a landscape of multiple tools in use. + Therefore, communication of atom probe research differs between user groups. This holds even more so true + for the sub community in atom probe which study physical mechanisms involved during ionization to the point that + here that almost each research work defines different simulation tools with different types of data artifacts. + + NXapm defines constraints on the existence and cardinality of concepts and its concept branches but seeks to + offer a compromise. The key design pattern followed is that most branches are made optional or at most recommended + but their child concepts are conditionally required. Thereby, NXapm can cover a variety of simple but also complex + use cases. An example of this parent-optional-but-childs-stronger-restricted design is the combination of the + optional group ``measurement`` with its required child ``measurement/instrument``: + Users which report simulations are not forced to document the instrument but users which have characterized + a specimen are motivated to report about the instrument. They are though not necessarily required to report all + the details of the instruments' components because the design pattern is applied recursively. + + *NXapm distinguishes and stores instance data based on how long they remain unchanged:* + + ``measurement`` provides two groups ``measurement/instrument`` and ``measurement/eventID``. + The first group is designed for storing metadata about the instrument that do not change over the course of the session. + Examples are the name of the technology partner who built the microscope or whether a laser or voltage pulser + and reflectron exists or not. The second group is designed for metadata and data that are collected during + the session with the instrument. These, are stored as instances of ``measurement/eventID``, + events that can be time-stamped individually. + Each instance of a group ``measurement/eventID`` contains ``measurement/instrument`` whose purpose is to + store those specific state and settings of the instrument that was present during the collection of the event. + Thereby, changing conditions such as compaigns with different target detection rate can be stored. + + Noteworthy, such an approach of the atom probe detecting groups of events and storing these as groups has also + been in use in the proprietary software via CamecaRoot, a set of customized data structures and file formats that use + the CernRoot library. By virtue of design this reduces unnecessary repetition of metadata stored in the first group. + + ``atom_probeID`` offer classes for the each task relevant task in the data processing pipeline that converts raw detector + event data to calibrated mass-to-charge-state-ratio values and hit_position on the detector. These include + ``initial_specimen``, and ``final_specimen`` locations for storing images of the specimen prior/after the measurement as + considered best practice by AMETEK/Cameca, ``raw_data`` for delay-line timing data, ``hit_finding`` for details of the + hit finding algorithm, ``hit_spatial_filtering`` a process that filters hits of too low quality and those laying outside the about + to be computed reconstruction volume. Furthermore, group ``voltage_and_bowl`` offers a place for documenting calibrations + and processing non-linearities. Group ``mass_to_charge_conversion`` is used to document the mass calibration and the + conversion from time-of-flight to mass-to-charge-state-ratio values. + + Finally, the groups ``reconstruction`` and ``ranging`` were designed to match and document the classical approaches how + from all the previous sources of input one can compute a reconstructed volume, and apply peak fitting routines on the + mass-to-charge-state-ratio histogram to label ions, i.e. range them for their isotopic identity. + Group ``atom_probeID/reconstruction/naive_discretization`` offers a standardized way to report simple + three-dimensional histograms. Group ``atom_probeID/ranging/peak_identification/ionID`` and its + complementing group ``atom_probeID/ranging/peak_identification/ionID/charge_state_analysis`` + solves the issue that the ranging definitions in classical file formats are not reported for always for their isotopic identity + and charge state. The field ``atom_probeID/ranging/peak_identification/iontypes`` provides a place for + storing a compact representation of the results of each ranging definition made at the level of each ion. + + *The compatibility of NXapm and NXem:** + + The design of NXapm mirrors that of :ref:`NXem`. This was an intentional choice to support the increasingly stronger connection between + these two materials characterization methods, especially in light of recent advances in the direct coupling of atom probe and + transmission electron microscopes and scanning transmission electron microscopes. + + + + + + + + + + + The configuration of the software that was used to generate this NeXus file. + + + + 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. + + + + + + + + Programs and libraries representing the computational environment + + + + + + + + + + + The identifier whereby the experiment is referred to in the control software. + + It is common practice in atom probe research to refer to a measurement on a single + specimen as a run. When working with AMETEK/Cameca instruments it is a common + practice also to store all data associated with such a run in files whose name + is composed from a prefix that details the type of instrument (e.g. R5076) followed + by the run_number. These filenames are often used as the specimen_name or + experiment_identifier. The terms run and session are understood as exact synonyms. + + For other instruments, such as the one from Stuttgart or Oxcart from Erlangen, + or the instruments at GPM in Rouen, use the identifier which matches + best conceptually 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; provided these + RHIT or HITS files respectively are stored alongside a data artifact. + With NXapm the RHIT or HITS can be stored via NXnote in the + hit_finding algorithm section. + + 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. Such interrupted runs + should be stored as individual :ref:`NXentry` instances in one NeXus file. + + + + + Alias or short name which scientists can use to refer to this experiment. + + + + + Free-text description about the experiment. + + Users are strongly advised to parameterize the description of their experiment + by using respective groups and fields and base classes instead of writing prose + into the field. + + + + + ISO 8601 time code with local time zone offset to UTC information + included when the atom probe session started. If the exact duration of + the measurement is not relevant, start_time only should be used. + + The start_time is required in order to ensure that at least one point in time + is provided for full temporal context to a measurement and simulation + when writing instance data using NXapm. Otherwise, the instance data + can not be sorted in order or even placed in a logical sequence to other + steps of the research workflow, which would disallow using functionalities + in research data management systems that rely on temporal context. + + Specifying start_time and end_time is useful for capturing more detailed + bookkeeping 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. For this + purpose the :ref:`NXevent_data_apm` instance should be used. + + + + + ISO 8601 time code with local time zone offset to UTC included + when the atom probe session ended. + + Writing the end_time can be a tricky in practice. If written at the start + of the experiment, it can only be an estimate. If written at the end, there + is the risk for having the computer crash or lose power. The absence of + end_time should not be interpreted as that the experiment was aborted. + Only, the field ``status`` should be used for communicating such abortion. + + + + + How long did the measurement take e.g. use CRunHeader.CAnalysis.fElapsedTime + + + + + + + + + + + + + + What type of atom probe experiment is performed to inform research data management + systems and allow filtering: + + * apt are experiments where the analysis_chamber has no imaging gas. + Experiments with LEAP instruments are typically with this operation_mode. + * 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. + Few experiments of this type have been performed, as it can be detrimental + to LEAP systems (see `S. Katnagallu et al. <https://doi.org/10.1017/S1431927621012381>`_). + + + + + + + + + + + + + + + + Description of the sample from which the specimen was prepared or + site-specifically cut out using e.g. a focused-ion beam instrument. + + In NXapm, a measurement is performed on a specimen. Since APM specimens + are very small, they are typically cut from a larger object with some + scientific significance, which NXapm refers to as a sample. + + + + + False, if the sample is a real one. + True, if the sample is a virtual one. + + + + + Given name/alias for the sample. + + + + + Qualitative information about the grain size, here specifically + described as the equivalent spherical diameter of an assumed + average grain size for the crystal ensemble. + + If the specimen does not contain many crystals average values + might be an unreliable descriptor. + + Reporting a grain size may be 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. + + + + + An array of elapsed time, the independent axis, of a time-temperature curve. + + This field can be used in combination with heat_treatment_temperature and + heat_treatment_temperature_errors as well as heat_treatment_quenching_rate + and heat_treatment_quenching_rate_errors respectively. In this case, these fields + should also be stored as an array with the same dimensions as heat_treatment_time + to store the dependant axes of a time-temperature curve as well as its first derivative. + + + + + If heat_treatment_time is absent, 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 a documentation of the annealing + treatment as a function of time is available one should better + rely on this information and have it stored alongside the NeXus file. + + If heat_treatment_time is provided, the temperature. + Consult the docstring of heat_treatment_time. + + + + + Magnitude of the standard deviation of the heat_treatment_temperature. + + If heat_treatment_time is provided, the magnitude of the standard derivation of the + temperature. Consult the docstring of heat_treatment_time. + + + + + If heat_treatment_time is absent, the rate of the last quenching step. + + Knowledge about this value can give an idea how the sample was heat treated. + However, there are many situations where one can imagine that the scalar value + for just the quenching rate is insufficient. + + If heat_treatment_time is provided, the first derivative of the time-temperature curve. + Consult the docstring of heat_treatment_time for further details. + + + + + Magnitude of the standard deviation of the heat_treatment_quenching_rate. + + If heat_treatment_time is provided, the magnitude of the standard deviation of + the first derivative of the time-temperature curve. + Consult the docstring of heat_treatment_time for further details. + + + + + + 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. + + + + + + + + + + + + Description of the specimen that was cut off from the sample. + + In atom probe jargon this is typically referred to as the tip. + + + + + False, if the specimen is a real one. + True, if the specimen is a virtual one. + + + + + Given name or an alias. Better use identifierNAME and identifier_parent instead. + + A single NXentry should be used only for the characterization of a single specimen. + + + + + Identifier of the sample from which the specimen was cut or the string "n/a". + + 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 identifier_parent. + + 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. + + + + + List of comma-separated elements from the IUPAC periodic table that are + contained in the specimen. If the specimen 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 identifier_parent or walk through + eventually deeply nested groups in data instances. + + + + + Discouraged free-text field. + + + + + True, if the specimen contains a grain or phase boundary. + False, if the specimen is a single crystal. + + + + + True, if the specimen is amorphous. + False, if the specimen is not. + + + + + Ideally measured otherwise best elaborated guess of the initial radius of the + specimen. + + + + + Ideally measured, otherwise best estimate, of the initial 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 smallest angle + between the specimen space z-axis and a vector on the lateral surface + of the cone. + + + + + + The conventions used when reporting crystal orientations. + We follow the best practices of the Material Science community + that are defined in reference `<https://doi.org/10.1088/0965-0393/23/8/083501>`_. + + + + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin. + This is in accordance with convention 2 of reference `<https://doi.org/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 reference `<https://doi.org/10.1088/0965-0393/23/8/083501>`_. + + + + + + + + + How are Euler angles interpreted given that there are several choices e.g. zxz, xyz + according to convention 4 of reference `<https://doi.org/10.1088/0965-0393/23/8/083501>`_. + + The most frequently used convention in Materials Science is zxz, which is based on the work + of H.-J. Bunge but using other conventions is possible. Proper Euler angles are distinguished + from Tait-Bryan angles. + + + + + + + + + + + + + + + + + + + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of reference `<https://doi.org/10.1088/0965-0393/23/8/083501>`_. + + + + + + + + Which sign convention is followed when converting orientations + between different parametrizations/representations according + to convention 6 of reference `<https://doi.org/10.1088/0965-0393/23/8/083501>`_. + + + + + + + + + + A coordinate system. Multiple instances require unique names. + + Several Euclidean coordinate systems (CS) are used in the field of atom probe: + + * 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. + Suggested name of the group ``laboratory_reference_frame``. + * The specimen space; + a CS affixed to either the base or the initial apex of the specimen, + whose z axis points towards the detector. + Suggested name of the group ``specimen_reference_frame``. + * 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. + Suggested name of the group ``detector_reference_frame``. + * 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. + Suggested name of the group ``reconstruction_reference_frame``. + + To achieve unique names, the prefix "NAMED" should be replaced to + with something derived from an alias for the coordinate system, + or the value of the "alias" field. + + Use the suffix _reference_frame when creating specific instances + of NXcoordinate_system e.g. laboratory_reference_frame, + reconstruction_reference_frame and so on and so forth. + + 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 identifier interval. Typically, the set of + ion evaporation sequence identifiers 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. + + To avoid these ambiguities, instances of :ref:`NXtransformations` should be used. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A region-of-interest analyzed either during or after the session for which + specific processed data of the measured or simulated data are available. + + If a single instance is required the group should be named atom_probe. + If multiple groups are required these should be named atom_probe1, atom_probe2, + and so on and so forth. + + + + SEM or TEM image of the initial specimen taken before the measurement. + + + + + + + + + + + + + + + + + + + + + + + SEM or TEM image of the final specimen taken after completion of the + measurement. + + + + + + + + + + + + + + + + + + + + + + + Document the control software that was used on the instrument with which raw data + were collected. + + For almost all atom probe instruments, the recorded raw data and metadata follow + proprietary semantics. Therefore, this group can currently often not be filled with + more than the control software and some pointing to digital artifacts (e.g. proprietary files) + that have been collected during the measurement in an effort to document as best as + possible all steps of an analysis workflow. + + The physical quantities measured in an atom probe experiment are time-of-flight and + tuples of arrival_time_pairs as a function of the event chain on the pulser. + From these tuples, hits are computed in a process called hit_finding. + + + + + The control software that was used for running the measurement. + + At least the main software should be reported. If this is the only program + to report name the group "program" and use its below fields program and + version to detail the version used. E.g. program AP Suite, version 6.3 + + It is recommended to report multiple programs though, i.e. also the libraries + and dependencies of the software. In the case of AP Suite/IVAS this can be used + to document the AP Suite GUI, LAS, CamecaRoot, and CernRoot versions. + In this case always name the program groups program1, program2, ... + with program one being AP Suite/IVAS. + + In the case of an open-source instrument, like P. Felfer's Oxcart or G. Schmitz's + M-TAP instruments, also use program1, program2, ... with program1 representing + the control software e.g. `M. Monajem and P. Felfer pyCCAPT <https://pyccapt.readthedocs.io/en/latest/>`_. + Further instances (program2, ...) can be used to list the dependencies, the + python virtual environment. + + + + + + + + Possibility to point to files that contain raw data. + + Exemplar files that could be pointed to here when working with + AMETEK/Cameca instruments are the proprietary STR, RRAW, or HITS + files that AP Suite/IVAS generates. + + + + + + + + + The number of delay-line-detector (DLD) wires present. + + + + + + + + + + Alias tuple, typical for the begin and the end of each DLD wire + of the detector. Order follows arrival_time_pairs. + + The order of the first dimension should match that of the + second dimension of the arrival_time_pairs field. + + + + + + + + + Raw readings from the analog-to-digital-converter + timing circuits of the detector wires. + + + + + + + + + + + The configuration of a hit finding algorithm and its output. + + Hit finding is the process of deciding which detector signals are significant + and assigning specific ions colliding with the detector + to each observed event. + + + + + + + + + + + + + + + + Evaluated ion impact coordinates on the detector. + Use the depends_on field to specify which reference + frame the positions are defined in. + + + + + + + + Contains the path to an instance of NX_coordinate_system + in which the positions are defined. + + + + + + Number of events of type "golden" when APSuite/IVAS was used as the + software with which the measurement was performed. + + The value can be extracted from the CRunHeader.fTotalEventGolden + field of a CamecaRoot RHIT/HITS file. + + + + + Number of events of type "incomplete" when APSuite/IVAS was used as the + software with which the measurement was performed. + + The value can be extracted from the CRunHeader.fTotalEventIncomplete + field of a CamecaRoot RHIT/HITS file. + + + + + Number of events of type "multiple" when APSuite/IVAS was used as the + software with which the measurement was performed. + + The value can be extracted from the CRunHeader.fTotalEventMultiple + field of a CamecaRoot RHIT/HITS file. + + + + + Number of events of type "partials" when APSuite/IVAS was used as the + software with which the measurement was performed. + + The value can be extracted from the CRunHeader.fTotalEventPartials + field of a CamecaRoot RHIT/HITS file. + + + + + Number of events when APSuite/IVAS was used as the + software with which the measurement was performed. + + The value can be extracted from the CRunHeader.fTotalEventRecords + field of a CamecaRoot RHIT/HITS file. + + + + + Hit quality is an integer that specifies which category/type a hit was assigned to. + This field lists the human-readable, possibly though proprietary types distinguished. + The indices of this array are used in hit_quality to encode hit_quality for each + pulse in a more efficient way than by repeating the string that is used for each + type as it is provided in this field. + + As an example, assume two types, "golden" and "partial", are distinguished. + If hit_quality_type stores the array "golden", "partial", the index 0 + in hit_quality identifies all those pulses of category "golden", + while the index 1 in hit_quality identifies all of category "partial". + + + + + + + + Hit quality identifier for each pulse. + Identifier has to be within hit_quality_type. + + + + + + + + The number of ions determined to have been collected on the same pulse. + These ions may hit different pixels, or even the same detector pixel. + The hit_multiplicity is not related to the makeup of the ions and should not be + confused with the number of atoms or elements that constitute a molecular ion. + + + + + + + + + + + + + + + + + + + + + + Integer which defines the first evaporation_id. + Typically, this is either zero or one. + + + + + There are two possibilities to report evaporation_id values: + + If evaporation_id_offset is provided, the evaporation_id values are defined + by the sequence :math:`[evaporation\_id\_offset, evaporation\_id\_offset + n]` + with :math:`n` the number of ions in the reconstructed volume. + + Alternatively, evaporation_id_offset is not provided but instead a + a sequence of :math:`n` values is defined, these integer values + do not need to be sorted. + + + + + + + + + + + + + + + Configuration of and results obtained from a voltage-and-bowl time-of-flight correction algorithm. + + The voltage-and-bowl correction is a data post-processing step to correct ion impact + positions for flight path differences, detector bias, and nonlinearities. + + + + + + + + + + + + + + + + + Reference mass-to-charge state ratio value + + For example 16 Da as mentioned by `T. Blum et al. <https://doi.org/10.1002/9781119227250.ch18>`_ (page 371). + + + + + + Raw time-of-flight data without corrections. + + + + + + + + The parameter :math:`t_0`, CAnalysis.CCalibMass.fT0Estimate + + + + + Calibrated time-of-flight. + + + + + + + + + + + + + + + + + + + + + + + Mass calibration with unit peaks/interp. as mentioned by `T. Blum et al. + <https://doi.org/10.1002/9781119227250.ch18>`_ (page 371). + + + + + Inverse of the mass resolution :math:`\frac{M}{\Delta M}` as mentioned by `T. Blum et al. <https://doi.org/10.1002/9781119227250.ch18>`_ (page 371). + + Multiple values can be reported but reporting each is only useful when stating also: + + * The full width at which :math:`{\Delta M}_{fw}` fraction of maximum this value was defined. + Examples are at tenth :math:`{\Delta M}_{10}` or at half maximum (FWHM). + Consequently, mass_resolution_fw should needs to be a vector of the same length + and using the same order like used for mass_resolution, i.e. the first mass resolution was + defined at the maximum as defined by the first value from mass_resolution_fw. + * The reference molecular ion e.g. :math:`^{16}{O_{2}}^{+}` + As many instances of mass_resolutionION should be used with instances + numbered starting from 1 up to the length of the mass_resolution vector. + + + + + + + + The full width at which :math:`{\Delta M}_{fw}` fraction of maximum this value was defined. + Examples are at tenth :math:`{\Delta M}_{10}` or at half maximum (FWHM). + Consequently, mass_resolution_fw should needs to be a vector of the same length + and using the same order like used for mass_resolution, i.e. the first mass resolution was + defined at the maximum as defined by the first value from mass_resolution_fw. + + + + + + + + The reference molecular ion e.g. :math:`^{16}{O_{2}}^{+}` + As many instances of mass_resolutionION should be used with instances + numbered starting from 1 up to the length of the mass_resolution vector. + + + + + + + + + + + + + + + + + + + + + For LEAP and APSuite/IVAS-based analyses the root file which stores + the settings whereby an RHIT/HITS file can be used to regenerate the + reconstructed volume that is here referred to. + + The respective RHIT/HITS file should ideally be specified in the serialized + group of the hit_finding section of this application definition. + + + + + + + + + For LEAP and APSuite/IVAS-based analyses the resulting typically + file with the reconstructed positions and calibrated mass-to-charge- + state ratio values. + + For other data collection/analysis software the data artifact which comes + closest conceptually to AMETEK/Cameca's typical file formats. + + These are typically exported as a POS, ePOS, APT, ATO, ENV, or HDF5 file, + which should be stored alongside this record in the research data + management system. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The respective ranging definitions file RNG/RRNG/ENV/HDF5. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + (Out-of-sync, time-independent) background levels in ppm/ns + reported by e.g. APSuite/IVAS for LEAP systems. + + + + + The mass-resolving power (MRP) value + + `D. Larson et al. <https://doi.org/10.1007/978-1-4614-8721-0>`_ report Eq. D.8 in page 282: + + :math:`MRP = \frac{1}{2\delta t} \cdot \sqrt{\frac{m}{n}\frac{1}{2eV}L}`, + + with :math:`\delta t` representing the timing imprecision, :math:`\frac{m}{n}` the mass-to-charge state ratio, + :math:`e` the elementary charge, :math:`V` the potential difference, and :math:`L` the flight path length. + + Timing imprecision is caused by variations of flight path length and voltage, + the fact that the precision of electronics is finite and a spread of the + time-of-departure of individual ions is observed. + + + + + Mass-to-charge state ratio :math:`\frac{m}{n}` at which mrp_value was specified. + + + + + Potential difference :math:`V` at which mrp_value was specified. + + + + + Flight path length :math:`L` at which mrp_value was specified. + + + + + + + + + + + + + + + + Category for the peak offering a qualitative statement of the location of the peak + in light of limited mass-resolving power that is relevant for + composition quantification. See `D. Larson et al. (p172) <https://doi.org/10.1007/978-1-4614-8721-0>`_ + for examples of each category: + + * 0, well-separated, :math:`^{10}B^{+}`, :math:`^{28}Si^{2+}` + * 1, close, but can be sufficiently separated for quantification in a LEAP system, :math:`^{94}Mo^{3+}`, :math:`^{63}Cu^{2+}` + * 2, closely overlapping, demands better than LEAP4000X MRP can provide :math:`^{14}N^{+}`, :math:`^{28}Si^{2+}` at different charge states + * 3, overlapped exactly due to multi-charge molecular species, :math:`^{16}{O_{2}}^{2+}`, :math:`^{16}O^{+}` + * 4, overlapped, same charge state, cannot as of 2013 be discriminated with a LEAP4000X, :math:`^{14}{N_{2}}^{+}`, :math:`^{28}Si^{+}` + * 5, overlapped, same charge state, any expectation of resolvability, :math:`^{54}Cr^{2+}`, :math:`^{54}Fe^{2+}` + + + + + + + + + + + + + + + + + + + + + + + + + + Ions that were ranged. + + The value zero is reserved for documenting that an ion was unranged. + Identifier for ranged ions need to start at 1 up to number_of_ion_types. + + + + + + + + + + + + + + + + + + + + + + + + The iontype identifier for each ion that was best matching; + stored in the order of the evaporation_id. + + The value zero is reserved for documenting that an ion was unranged. + Identifier for ranged ions need to start at 1 up to number_of_ion_types. + + + + + + + + + + diff --git a/base_classes/NXapm_charge_state_analysis.nxdl.xml b/base_classes/NXapm_charge_state_analysis.nxdl.xml new file mode 100644 index 0000000000..44823beb87 --- /dev/null +++ b/base_classes/NXapm_charge_state_analysis.nxdl.xml @@ -0,0 +1,155 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The number of ion candidates. + + + + + Maximum number of allowed atoms per ion. + + + + + Number of entries + + + + + Base class to document the parameters, configuration, and results of a processing for recovering + the charge state and nuclide composition of an ion from ranging definitions as used in the research + field of atom probe microscopy. + + A ranging definition classically reports only the mass-to-charge-state-ratio interval plus the + elemental composition, but not necessarily the nuclide that compose the ion. + + As the mass-resolving-power in an atom probe instrument is finite and typically lower + than for cutting edge tandem mass spectrometry it is possible that different combinations of nuclides + are indistinguishable and thus multiple ions in eventually even different charge states can be valid + labels for a given mass-to-charge-state-ratio peak. Enumerating the possible combinations + is a programmatic approach that can help with peak identification. + + + + Parameters for the algorithm used to recover which combinations of nuclides + have a mass and charge that matches a set of constraints. + + Each parameter in this group is defines one constraint. + + + + Parameter that defines the elements considered in the combinatorial search. + The array contains nuclides as many times as their multiplicity and must not be empty. + Nuclides are encoded using the hashing rule that is defined in by nuclide_hash of :ref:`NXatom`. + + Constraining the elements or nuclides instead of providing all nuclides + reduces the time to perform an exhaustive combinatorial search. + + + + + + + + Parameter that defines the interval :math:`[{\frac{m}{q}}_{min}, {\frac{m}{q}}_{max}]` within which + ions with given mass-to-charge-state-ratio qualify as candidates. + + + + + + + + Parameter that defines the minimum half life for how long each nuclide of each + ion needs to be stable such that the ion qualifies as a candidate. + + + + + Parameter that defines the minimum natural abundance of each nuclide of each + ion such that the ion qualifies as a candidate. + + + + + If the value is false, it means that non-unique solutions are accepted. + These are solutions where multiple candidates have been built from + different nuclide instances but the charge_state of all the ions is the same. + + + + + + Signed charge, i.e. integer multiple of the elementary + charge of each candidate. + + + + + + + + Table of nuclide instances of which each candidate is composed. + Each row vector is sorted in descending order. + Unused entries in the matrix should be set to 0. + Use the hashing rule that is defined in nuclide_hash of :ref:`NXatom`. + + + + + + + + + Accumulated mass of the nuclides in each candidate. + Not corrected for quantum effects. + + + + + + + + The product of the natural abundances of the nuclides for each candidate. + + + + + + + + For each candidate the half life of the nuclide that has the + shortest half life. + + + + + + diff --git a/base_classes/NXapm_measurement.nxdl.xml b/base_classes/NXapm_measurement.nxdl.xml new file mode 100644 index 0000000000..c536a2daf1 --- /dev/null +++ b/base_classes/NXapm_measurement.nxdl.xml @@ -0,0 +1,70 @@ + + + + + + Base class for collecting a run with a real or a simulated atom probe or field-ion microscope. + + The term run is understood as an exact synonym for session, i.e. the usage of a real or simulated + tomograph or microscope for a certain amount of time during which one characterizes a single specimen. + + Research workflows for experiments and simulations of atom probe and related field-evaporation + evolve continuously and become increasingly connected with other methods used for material + characterization specifically electron microscopy. A few examples in this direction are: + + * `T. Kelly et al. <https://doi.org/10.1017/S1431927620022205>`_ + * `C. Fleischmann et al. <https://doi.org/10.1016/j.ultramic.2018.08.010>`_ + * `W. Windl et al. <https://doi.org/10.1093/micmic/ozad067.294>`_ + * `C. Freysoldt et al. <https://doi.org/10.1103/PhysRevLett.124.176801>`_ + * `G. da Costa et al. <https://doi.org/10.1038/s41467-024-54169-2>`_ + + The majority of atom probe research is performed using the so-called Local Electrode Atom Probe (LEAP) instruments + from AMETEK/Cameca. In addition, several research groups have built their own instruments and shared different + aspects of the technical specifications and approaches including how these groups apply data processing e.g.: + + * `M. Monajem et al. <https://doi.org/10.1017/S1431927622003397>`_ + * `P. Stender et al. <https://doi.org/10.1017/S1431927621013982>`_ + * `I. Dimkou et al. <https://doi.org/10.1093/micmic/ozac051>`_ + + to name but a few. + + + + A statement whether the measurement completed successfully, or was aborted. + + + + + + + + + Statement about the quality of the measurement. + + The value can be extracted from the CAnalysis.CResults.fQuality + field of a CamecaRoot ROOT file. + + + + + diff --git a/base_classes/NXapm_ranging.nxdl.xml b/base_classes/NXapm_ranging.nxdl.xml new file mode 100644 index 0000000000..86ac98719f --- /dev/null +++ b/base_classes/NXapm_ranging.nxdl.xml @@ -0,0 +1,118 @@ + + + + + + Base class for the configuration and results of ranging definitions. + + Ranging is a data post-processing step used in the research field of + atom probe during which elemental, isotopic, and/or molecular identities + are assigned to mass-to-charge-state ratios within certain intervals. + The documentation of these steps is based on ideas that + have been 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>`_ + + + + + + Specifies the mass-to-charge-state ratio histogram. + + + + + Smallest :math:`{\frac{m}{q}}_{min}` mass-to-charge-state ratio value. + + The lower (left-hand side) inclusive bound of the interval :math:`[{\frac{m}{q}}_{min}`, {\frac{m}{q}}_{max}]`. + + + + + Largest :math:`{\frac{m}{q}}_{max}` mass-to-charge-state ratio value. + + The upper (right-hand side) inclusive bound of the interval :math:`[{\frac{m}{q}}_{min}`, {\frac{m}{q}}_{max}]`. + + + + + The number of bins on the interval :math:`[{\frac{m}{q}}_{min}`, + {\frac{m}{q}}_{max}]`. + + + + + A default histogram aka mass spectrum of + the mass-to-charge-state ratio values. + + + + + + Details of the background model that was used to + correct the total counts per bin into counts. + + + + + Free-text field to describe how atom probers define a background model. + + Thereby, community feedback can be collected to inform an improved + version of this base class in the future. + + + + + + How were peaks in the mass-to-charge-state ratio histogram identified. + + + + + + + Details about how peaks, with taking into account + error models, were interpreted as ion types or not. + + + + + 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 representing a reserved value. + + Consequently, start counting iontypes from 1. + + + + + Assumed maximum value that suffices to store all relevant molecular ions, + even the most complicated ones that one can typically observe and distinguish + typically. Currently, a value of 32 is used (see M. Kühbach et al. <https://doi.org/10.1017/S1431927621012241>`_). + + + + + diff --git a/base_classes/NXapm_reconstruction.nxdl.xml b/base_classes/NXapm_reconstruction.nxdl.xml new file mode 100644 index 0000000000..43068bd667 --- /dev/null +++ b/base_classes/NXapm_reconstruction.nxdl.xml @@ -0,0 +1,275 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of ions spatially filtered from results of the hit_finding algorithm + from which an instance of a reconstructed volume has been generated. + These ions get new identifier assigned in the process - the so-called + evaporation_id, which must not be confused with the pulse_id! + + + + + Base class for the configuration and results of a reconstruction algorithm. + + Generating a tomographic reconstruction of the specimen uses selected and + 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. + + + + + + + Parameters that configure a reconstruction algorithm which takes + hit data and mass-to-charge-state ratio values to construct a model + of the evaporated specimen. This model is called the reconstructed volume. + Researchers in the field of atom probe call these algorithms reconstruction + protocols. + + Different such protocols exist. Although these are qualitatively similar, + each protocol uses and interprets the parameters slightly differently. + + The majority of reconstructions is performed with the proprietary software + APSuite / IVAS, the source code for the reconstruction protocols that this + software implements in detail is not open but the parameters and their qualitative + effect on the reconstructed volume follows the protocols that are discussed in + the atom probe literature. This group allows to document these parameters in + a standardized manner. + + + + Lowest voltage at which an ion that is considered in the reconstructed + volume has been extracted from the specimen. + + + + + Highest voltage at which an ion that is considered in the reconstructed + volume has been extracted from the specimen. + + + + + Qualitative statement about which reconstruction protocol was used. + + For reconstructions performed with APSuite / IVAS the value "cameca" + should be used. + + + + + + + + + + + Assumed primary element based on which the reconstruction is calibrated. + + The value can be extracted from the CAnalysis.CSpatial.fPrimaryElement + field of a CamecaRoot ROOT file. + + + + + Assumed detection efficiency + + The value can be extracted from the CAnalysis.CSpatial.fEfficiency + field of a CamecaRoot ROOT file. + + + + + Nominal flight path + + The value can be extracted from the CAnalysis.CSpatial.fFlightPath + field of a CamecaRoot ROOT file. + + + + + Assumed evaporation electric field + + The value can be extracted from the CAnalysis.CSpatial.fEvaporationField + field of a CamecaRoot ROOT file. + + + + + Image compression factor (ICF) + + The value can be extracted from the CAnalysis.CSpatial.fImageCompression + field of a CamecaRoot ROOT file. + + + + + Sum of ion volumes + + The value can be extracted from the CAnalysis.CSpatial.fKfactor + field of a CamecaRoot ROOT file. + + + + + Shank angle + + The value can be extracted from the CAnalysis.CSpatial.fShankAngle + field of a CamecaRoot ROOT file. + + + + + Assumed atomic volume + + + + + The value can be extracted from the CAnalysis.CSpatial.fTipRadius + field of a CamecaRoot ROOT file. + + + + + The value can be extracted from the CAnalysis.CSpatial.fTipRadius0 + field of a CamecaRoot ROOT file. + + + + + The value can be extracted from the CAnalysis.CSpatial.fVoltage0 + field of a CamecaRoot ROOT file. + + + + + Different strategies for crystallographic calibration of the + reconstruction are possible. Therefore, we collect first such + feedback before parametrizing this further. + + If no crystallographic calibration was performed, the field + should be filled with the n/a, meaning not applied. + + + + + Possibility of a free text field that allows to report additional details related to + the reconstruction protocol. For LEAP systems and reconstructions that are + performed with APSuite / IVAS see also `B. Gault et al. <https://doi.org/10.1093/mam/ozae081>_` + and `T. Blum et al. <https://doi.org/10.1002/9781119227250.ch18>`_ (page 371). + for best practices on the reporting of metadata in atom probe tomography. + + + + + + + Three-dimensional positions of the ions in the reconstructed volume. + + + + + + + + The instance of :ref:`NXcoordinate_system` in which the positions are defined. + + + + + + + + + Visual overview of the reconstructed dataset via a three-dimensional + histogram of ion counts. Ion counts are characterized using one nanometer + cubic bins without applying any smoothening of reconstructed positions + during the histogram computation. + + Such preview is useful to get an impression of the macroscopic shape of the + reconstructed volume. Visualizing by ion counts highlights density variations + the reconstructed volume that are signatures of features such as poles, + interfaces or irregularities of the specimen shape. + + + + + + Sum of ion volumes + + The value can be extracted from the CAnalysis.CSpatial.fRecoVolume + field of a CamecaRoot ROOT file. + + + + + + The nominal diameter of the specimen ROI which is measured in the + experiment. The physical specimen cannot be measured completely + because ions may launch but hit in locations other than the detector. + + + + + Tight, axis-aligned bounding box about the point cloud of the reconstruction. + + + + Minimum coordinate value along the x-direction + + + + + Maximum coordinate value along the x-direction + + + + + Minimum coordinate value along the y-direction + + + + + Maximum coordinate value along the y-direction + + + + + Minimum coordinate value along the z-direction + + + + + Maximum coordinate value along the z-direction + + + + diff --git a/contributed_definitions/NXchamber.nxdl.xml b/base_classes/NXapm_simulation.nxdl.xml similarity index 65% rename from contributed_definitions/NXchamber.nxdl.xml rename to base_classes/NXapm_simulation.nxdl.xml index 30da2e9d8d..cd726f04c7 100644 --- a/contributed_definitions/NXchamber.nxdl.xml +++ b/base_classes/NXapm_simulation.nxdl.xml @@ -2,9 +2,9 @@ - + - Component of an instrument to store or place objects and specimens. + Base class for simulation of ion extraction from matter via laser and/or voltage + pulsing. - - - Given name/alias. - - - - - Free-text field for describing details about the chamber. - For example out of which material was the chamber built. - - + + + + diff --git a/base_classes/NXatom.nxdl.xml b/base_classes/NXatom.nxdl.xml new file mode 100644 index 0000000000..e8f2a55598 --- /dev/null +++ b/base_classes/NXatom.nxdl.xml @@ -0,0 +1,218 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of atom positions. + + + + + Dimensionality + + + + + Maximum number of atoms/isotopes allowed per ion. + + + + + Number of mass-to-charge-state-ratio range intervals for ion type. + + + + + Base class for documenting a set of atoms. + + Atoms in the set may be bonded. The set may have + a net charge to represent an ion. + An ion can be a molecular ion. + + + + Given name for the set. + + This field could for example be used in the research field + of atom probe tomography to store a standardized human-readable + name of the element or ion like such as Al +++ or 12C +. + + + + + Given numerical identifier for the set. + + The identifier zero is reserved for the special unknown ion type. + + + + + Identifier used to refer to if the set of atoms represents a substance. + + + + + + + + Signed net (partial) charge of the (molecular) ion. + + Different methods for computing charge are in use. + Care needs to be exercised with respect to the integration. + `T. A. Manz <10.1039/c6ra04656h>`_ and `N. G. Limas <10.1039/C6RA05507A>`_ discuss computational details. + + + + + Charge reported in multiples of the charge of an electron. + + For research using atom probe tomography the value should be set to + zero if the charge_state is unknown and irrecoverable. This can happen + when classical ranging definition files in formats like RNG, RRNG are used. + These file formats do not document the charge state explicitly but only + the number of atoms of each element per molecular ion surplus the + respective mass-to-charge-state-ratio interval. + + Details on ranging definition files in the literature are `M. K. Miller <https://doi.org/10.1002/sia.1719>`_. + + + + + Assumed volume affected by the set of atoms. + + Neither individual atoms nor a set of cluster of these have a volume + that is unique as a some cut-off criterion is required. + + + + + Index for each atom at locations as detailed by position. + Indices can be used as identifier and thus names for individual atoms. + + + + + + + + Nuclide information for each atom at locations as detailed by position. + + One `approach <https://doi.org/10.1017/S1431927621012241>`_ for storing nuclide information + efficiently is via individual hash values. + Consult the docstring of ``nuclide_hash`` for further details. + + + + + + + + Position of each atom. + + + + + + + + Path to a reference frame in which positions are defined + to resolve ambiguity when the reference frame is different + to the NeXus default reference frame (McStas). + + + + + + Relative occupancy of the atom position. + + This field is useful for specifying the atomic motif in + instances of :ref:`NXunit_cell`. + + + + + + + + Vector of nuclide hash values. The vector is sorted in decreasing order. + + Individual hash values :math:`H` `encode <https://doi.org/10.1017/S1431927621012241>`_ + for each nuclide or element the number of protons :math:`Z` and a constant :math:`c` + via the following hashing rule :math:`H = Z + c \cdot 256` . :math:`Z and c` must be 8-bit unsigned integers. + + The constant :math:`c` is either set to number of neutrons :math:`N` or to the special value 255. + The special value 255 is used to refer to all isotopes of an element from the IUPAC periodic table. + + Exemplified for hydrogen (meaning irrespective which isotope), its hash value is :math:`H = 1 + 255 \cdot 256 = 65281`. + Exemplified for the :math:`^{1}H` hydrogen isotope (:math:`Z = 1, N = 0`), its hash value is :math:`H = 1 + 0 \cdot 256 = 1`. + Exemplified for the :math:`^{2}H` deuterium isotope (:math:`Z = 1, N = 1`), its hash value is :math:`H = 1 + 1 \cdot 256 = 257`. + Exemplified for the :math:`^{3}H` tritium isotope (:math:`Z = 1, N = 2`), its hash value is :math:`H = 1 + 2 \cdot 256 = 513`. + Exemplified for the :math:`^{99}Tc` technetium isotope (:math:`Z = 43, N = 56`), its hash value is :math:`H = 43 + 56 \cdot 256 = 14379`. + The special hash value :math:`0` is a placeholder. + + This hashing rule implements a bitshift operation. The benefit is that this enables encoding of all + currently known nuclides and elements efficiently into an 16-bit unsigned integer. Sufficient + unused indices remain to case situations when new elements will be discovered. + + + + + + + + Table which decodes the entries in nuclide_hash into a human-readable matrix + instances for either nuclids or elements. Specifically, the first row specifies the + nuclide mass number. When the nuclide_hash values are used this means + the row should report the sum :math:`Z + N` or 0. The value 0 documents that + an element from the IUPAC periodic table is meant. + The second row specifies the number of protons :math:`Z`. + The value 0 in this case documents a placeholder or that no element-specific + information is relevant. + + Taking a carbon-14 nuclide as an example the mass number is 14. + That is encoded as a column vector (14, 6). + The array is stored matching the order of nuclide_hash. + + + + + + + + + Associated lower :math:`{\frac{m}{q}}_{min}` and upper :math:`{\frac{m}{q}}_{max}` bounds of the + mass-to-charge-state ratio interval(s) :math:`[{\frac{m}{q}}_{min}, {\frac{m}{q}}_{max}]`. + (boundaries inclusive). This field is primarily of interest for documenting :ref:`NXprocess` + steps of indexing a ToF/mass-to-charge-state ratio histogram. + + + + + + + diff --git a/base_classes/NXchemical_composition.nxdl.xml b/base_classes/NXchemical_composition.nxdl.xml new file mode 100644 index 0000000000..d1f0f91639 --- /dev/null +++ b/base_classes/NXchemical_composition.nxdl.xml @@ -0,0 +1,93 @@ + + + + + + + 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. + + + + 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 which are of a particular type. + By contrast, weight_percent normalization factorizes in the + respective mass of the elements. Software libraries that work with + units, like pint in Python, are challenged by these differences as + at.-% and wt.-% are both fractional quantities. + + + + + + + + + Total formula mass or number of atoms, depending on the + normalization stated in the normalization field. + + + + + + + + If this group is used to report the composition of elements from the periodic table, + the group should use the chemical symbol of that element. For other case the + group name is unconstrained. + + + + Count or weight which, when divided by total yields the composition + of this element, isotope, molecule, or ion. + + + + + + + + Composition value for the element/ion referred to under name. + Composition is reported either normalized for atomic or weight + percent. The field normalization should be used to communicate + this explicitly. Composition should be reported consistently + for all instances ELEMENT. + + + + + Magnitude of the standard deviation of the composition. + + + + diff --git a/base_classes/NXcircuit.nxdl.xml b/base_classes/NXcircuit.nxdl.xml new file mode 100644 index 0000000000..23bd777d5c --- /dev/null +++ b/base_classes/NXcircuit.nxdl.xml @@ -0,0 +1,152 @@ + + + + + + Base class for documenting circuit devices. + + Electronic circuits are hardware components that connect several electronic components to achieve + specific functionality, e.g. amplifying a voltage or convert a voltage to binary numbers, etc. + + + + Hardware where the circuit is implanted; includes information about the + hardware manufacturers and type (e.g. part number) + All the elements below may be single numbers of an array of values with length N_channel + describing multiple input and output channels. + + + + + List of components used in the circuit, e.g., resistors, capacitors, transistors or any + other complex components. + + + + + Description of how components are interconnected, including connection points + and wiring. + + + + + Details of the power source for the circuit, including voltage and current + ratings. + + + + + Type of signal (input signal) the circuit is designed to handle, e.g., analog, + digital, mixed-signal. + + + + + + The operating frequency of the circuit, see also bandwidth, which is possibly + but not necessarily centered around this frequency (e.g. running a 100 kHz bandwidth + amplifier at low, audio frequencies 1 - 20,000 Hz). + + + + + The bandwidth of the frequency response of the circuit. + + + + + + Input impedance of the circuit. + + + + + Output impedance of the circuit. + + + + + Gain of the circuit, if applicable, usually all instruments have a gain + which might be important or not. + + + + + Root-mean-square (RMS) noise level (in current or voltage) + in the circuit in voltage or current. + + + + + Operating temperature range of the circuit. + + + + + Calibration data for the circuit. + + + + + Offset value for current or voltage. + + + + + Number of output channels connected to this circuit. Most probably N_channel. + + + + + Type of output signal, e.g., voltage, current, digital. + + + + + Power consumption of the circuit per unit time. + + + + + Status indicators for the circuit, e.g., LEDs, display readouts. + + + + + Protection features built into the circuit, e.g., overvoltage protection, + thermal shutdown. + + + + + Updated rate for several processes using the input signal, e.g., History Graph, the circuit + uses for any such process. + + + + + The rate at which the signal changes when ramping from the starting + value. + + + diff --git a/base_classes/NXcs_computer.nxdl.xml b/base_classes/NXcs_computer.nxdl.xml new file mode 100644 index 0000000000..d02a32e4f4 --- /dev/null +++ b/base_classes/NXcs_computer.nxdl.xml @@ -0,0 +1,69 @@ + + + + + + Base class for reporting the description of a computer + + + + 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. + + + + + + + A globally unique persistent identifier of the computer, i.e. + the Universally Unique Identifier (UUID) of the computing node. + + + + + Multiple instances should be named processor1, processor2, etc. + + + + + Multiple instances should be named memory1, memory2, etc. + + + + + Multiple instances should be named storage1, storage2, etc. + + + diff --git a/base_classes/NXcs_filter_boolean_mask.nxdl.xml b/base_classes/NXcs_filter_boolean_mask.nxdl.xml new file mode 100644 index 0000000000..c4e453e028 --- /dev/null +++ b/base_classes/NXcs_filter_boolean_mask.nxdl.xml @@ -0,0 +1,86 @@ + + + + + + + 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. + + + + + Base class for packing and unpacking booleans. + + The field mask should be constructed from packing a vector of booleans + (a bitfield) into unsigned integers with bytesize bitdepth. Padding to + an integer number of such integers is assumed. + + Thereby, this base class can be used to inform software about necessary modulo + operations to decode the mask to recover e.g. set membership of objects in sets + whose membership has been encoded as a vector of booleans. + + This is useful e.g. when processing object sets such as point cloud data. + If e.g. a spatial filter has been applied to a set of points, we may wish to document + memory-space efficiently which points were analyzed. An array of boolean values + is one option to achieve this. A value is true if the point is included and false otherwise. + + + + 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. + + + diff --git a/base_classes/NXcs_memory.nxdl.xml b/base_classes/NXcs_memory.nxdl.xml new file mode 100644 index 0000000000..0dfa2e171f --- /dev/null +++ b/base_classes/NXcs_memory.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + Base class for reporting the description of the memory system of a computer. + + + + Typically, computers have multiple instances of memory. + + + + Qualifier for the type of random access memory. + + + + + + + + + Total amount of data which the medium can hold. + + + + diff --git a/base_classes/NXcs_prng.nxdl.xml b/base_classes/NXcs_prng.nxdl.xml new file mode 100644 index 0000000000..28303a0f6b --- /dev/null +++ b/base_classes/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, like 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 random the resulting sequences actually are, 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/base_classes/NXcs_processor.nxdl.xml b/base_classes/NXcs_processor.nxdl.xml new file mode 100644 index 0000000000..d4d3f7de48 --- /dev/null +++ b/base_classes/NXcs_processor.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + Base class for reporting the description of processing units of a computer. + + Examples are e.g. classical so-called central processing units (CPUs), + coprocessors, graphic cards, accelerator processing units or a system of these. + + + + Typical examples for the granularization of processing units are: + + * A desktop computer with a single CPU; describe using one instance of NXcircuit. + * A dual-socket server; describe using two instances of NXcircuit. + * A server with two dual-socket server nodes; describe with four + instances of NXcircuit surplus a field that defines their level + in the hierarchy. + + + + General type of the processing unit e.g. + + * pu, processing core or hyper-threading core + * cpu, (multi-)core central processing unit + * gpu, (multi-)core general purpose processing unit + * fpga, field programmable gate array + + + + + + + + + + + Clock speed of the circuit + + + + diff --git a/base_classes/NXcs_profiling.nxdl.xml b/base_classes/NXcs_profiling.nxdl.xml new file mode 100644 index 0000000000..7905c13e92 --- /dev/null +++ b/base_classes/NXcs_profiling.nxdl.xml @@ -0,0 +1,150 @@ + + + + + + + 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 i.e. an 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. + + + + + The number of nominal processes that the app invoked at runtime. + + 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 one. If the app exclusively uses GPU parallelization, number_of_gpus + can be larger than one. If no GPU is used, number_of_gpus is zero, + even though the hardware may have GPUs installed. + + + + + The number of nominal threads that the app invoked at runtime. + Specifically here the maximum number of threads used for the + high-level threading library used (e.g. OMP_NUM_THREADS), posix. + + + + + The number of nominal GPUs that the app 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. + ID is an increasing unsigned integer starting at 1. + + + + diff --git a/base_classes/NXcs_profiling_event.nxdl.xml b/base_classes/NXcs_profiling_event.nxdl.xml new file mode 100644 index 0000000000..efcdb60e01 --- /dev/null +++ b/base_classes/NXcs_profiling_event.nxdl.xml @@ -0,0 +1,110 @@ + + + + + + + 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. + + + + + The number of nominal processes that the app invoked during the execution of this event. + + 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 one. If the app exclusively uses GPU parallelization, number_of_gpus + can be larger than one. If no GPU is used, number_of_gpus is zero, + even though the hardware may have GPUs installed. + + + + + The number of nominal threads that the app invoked at during the execution of this event. + Specifically here the maximum number of threads used for the + high-level threading library used (e.g. OMP_NUM_THREADS), posix. + + + + + The number of nominal GPUs that the app invoked 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/base_classes/NXcs_storage.nxdl.xml b/base_classes/NXcs_storage.nxdl.xml new file mode 100644 index 0000000000..d4c0a3570b --- /dev/null +++ b/base_classes/NXcs_storage.nxdl.xml @@ -0,0 +1,56 @@ + + + + + + Base class for reporting the description of the I/O of a computer. + + + + + Qualifier for the type of storage medium used. + + + + + + + + + + + Total amount of data which the medium can hold. + + + + + Maximum read rate of the storage medium. + + + + + Maximum write rate of the storage medium. + + + + diff --git a/base_classes/NXentry.nxdl.xml b/base_classes/NXentry.nxdl.xml old mode 100755 new mode 100644 diff --git a/base_classes/NXevent_data_apm.nxdl.xml b/base_classes/NXevent_data_apm.nxdl.xml new file mode 100644 index 0000000000..820f061d95 --- /dev/null +++ b/base_classes/NXevent_data_apm.nxdl.xml @@ -0,0 +1,119 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of pulses collected in between start_time and end_time. + + + + + Base class to store state and (meta)data of events over the course of an atom probe experiment. + + Having at least one instance for an instance of NXapm is recommended. + + This base class applies the concept of the :ref:`NXevent_data_em` base class to the specific needs + of atom probe research. Again static and dynamic quantities are split to avoid a duplication + of information. Specifically, the time interval considered is the entire time + starting at start_time until end_time during which we assume the pulser triggered pulses. + These pulses are identified via the pulse_id field. The point in time when each pulse was + fired can be recovered from analyzing start_time and delta_time. + + 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 atom probe experiments or simulation. To monitor the course of an ion extraction experiment + (or simulation) it makes sense to track time explicitly via time stamps or implicitly + via e.g. a clock inside the instrument, such as the clock of the pulser and respective pulse_id. + + + + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval started. + + If users wish 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, the left bound of the time interval, while + the end_time specifies the end, the right bound of the time interval. + + + + + ISO 8601 time code with local time zone offset to UTC information included + when the snapshot time interval ended. + + + + + Delta time array which resolves for each pulse_id the time difference + between when that pulse was fired and start_time. + + In summary, using start_time, end_time, delta_time, pulse_id_offset, + and pulse_id provides temporal context information when a pulse was + fired relative to start_time and when it is relevant to translate this into + coordinated world time UTC. + + Note that pulses in reality have a shape and thus additional documentation + is required to assure that the entries in delta_time are always taken at + at points in time that, relative to the triggering of the pulse, represent an + as close as possible state of the pulse. + + + + + + + + Integer which defines the first pulse_id. + Typically, this is either zero or one. + + + + + An integer to identify a specific pulse in a sequence. + + There are two possibilities to report pulse_id values: + If pulse_id_offset is provided, the pulse_id values are defined + by the sequence :math:`[pulse\_id\_offset, pulse\_id\_offset + p]` + with :math:`p` the number of pulses collected in between + start_time and end_time. + + Alternatively, pulse_id_offset is not provided but instead + a sequence of :math:`p` values is defined. + These integer values do not need to be sorted. + + + + + + + + Place to store dynamic metadata of the instrument to document as close as possible + the state of the instrument during the event, i.e. in between start_time and end_time. + + + diff --git a/base_classes/NXimage.nxdl.xml b/base_classes/NXimage.nxdl.xml new file mode 100644 index 0000000000..8859586bc5 --- /dev/null +++ b/base_classes/NXimage.nxdl.xml @@ -0,0 +1,628 @@ + + + + + + + + + Number of images in the stack, for stacks the slowest dimension. + + + + + Number of image points along the slow dimension (k equivalent to z). + + + + + Number of image points along the fast dimension (j equivalent to y). + + + + + Number of image points along the fastest dimension (i equivalent to x). + + + + + Base class for reporting a set of images representing specializations of NXdata. + + The most commonly used scanning methods are supported. That is one-, + two-, three-dimensional ROIs discretized using regular Euclidean tilings. + + Colloquially, an image is understood as a discretized representation of intensity distribution + detected or simulated for some ROI. When discretized with regular Euclidean tilings, the terms + pixel and voxel identify the smallest discretization unit. In this case, pixel and voxel are polygonal + or polyhedral unit cells respectively of the underlying tiling of the ROI within the reference space. + For all other tilings e.g. non-equispaced, the shape and size of pixel and voxel differs. Using the term + image point is eventually more appropriate when working with such tilings. + + Therefore, all docstrings in this base class refer to points. Points are considered + exact synonyms for pixel and voxel, which are terms used for regular tilings. + + Point coordinates identify the location of the barycenter. + + For 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 images. + Details can be found in the respective sections of the typical FFT libraries documentations: + + * `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/2024-2/fourier-transform-functions.html>`_ + * `cuFFT by the NVidia Co. <https://docs.nvidia.com/cuda/cufft/index.html>`_ + * `NFFT by the TU Chemnitz group <https://www-user.tu-chemnitz.de/~potts/nfft/>`_ for non-equispaced computations + + Users are strongly advised to inspect carefully which specific conventions their library uses + to enable storing and modifying the implementation of their code such that the serialized + representations as they are detailed here for NeXus match. + + It is often the case that several images are combined using processing. In this case, + the number of images which are combined into collections is not necessarily the same + for each collection. The NXimage base class addresses this logical distinction + through the notation of indices_image and indices_group concepts. + That is indices_image are always counting from offset in increments of one + as each image is its own entity. By contrast, a group may contain no, or several images. + Consequently, indices_group are not required to be contiguous. + + + + Details how NXdata instance were processed from detector readings/raw data. + + + + Resolvable data artifact (e.g. file) from which all values in the :ref:`NXdata` + instances in this :ref:`NXimage` were loaded during parsing. + + Possibility to document from which specific other serialized resource as the source + pieces of information were processed when using NeXus as a semantic file format + to serialize that information differently. + + The group in combination with an added field *context* therein adds context. + + + + Reference to a location inside the artifact that points to the specific group of values + that were processed if the artifacts contains several groups of values and thus + further resolving of ambiguities is required. + + + + + + Link or name of an :ref:`NXdetector` instance with which the data were + collected. + + + + + Program used for processing. + + + + + + One-dimensional image. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + Real part of the image intensity per point. + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Two-dimensional image. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + + Real part of the image intensity per point. + + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + + Point coordinate along the fast dimension. + + + + + + + Point coordinate along the fast dimension. + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Three-dimensional image. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + + + Real part of the image intensity per point. + + + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + + + Point coordinate along the slow dimension. + + + + + + + Point coordinate along the slow dimension. + + + + + + Point coordinate along the fast dimension. + + + + + + + Point coordinate along the fast dimension. + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Collection of one-dimensional images. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + + Real part of the image intensity per point. + + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Image identifier + + + + + + + Image identifier + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Collection of two-dimensional images. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + + + Real part of the image intensity per point. + + + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + Point coordinate along the fast dimension. + + + + + + + Point coordinate along the fast dimension. + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + + + Collection of three-dimensional images. + + + + Intensity for real-valued images as an alternative for real. + Magnitude of the image intensity for complex-valued data. + + + + + + + + + + + Real part of the image intensity per point. + + + + + + + + + + + Imaginary part of the image intensity per point. + + + + + + + + + + + Image intensity as a complex number as an alternative to real and + imag fields if values are stored as interleaved complex numbers. + + + + + + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Image identifier + + + + + + + Image identifier + + + + + + Point coordinate along the slow dimension. + + + + + + + Point coordinate along the slow dimension. + + + + + + Point coordinate along the fast dimension. + + + + + + + Point coordinate along the fast dimension. + + + + + + Point coordinate along the fastest dimension. + + + + + + + Point coordinate along the fastest dimension. + + + + + diff --git a/base_classes/NXinstrument_apm.nxdl.xml b/base_classes/NXinstrument_apm.nxdl.xml new file mode 100644 index 0000000000..cd4bd92a51 --- /dev/null +++ b/base_classes/NXinstrument_apm.nxdl.xml @@ -0,0 +1,388 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Number of pulses collected in between start_time and end_time + inside a parent instance of :ref:`NXevent_data_apm`. + + + + + Base class for instrument-related details of a real or simulated + atom probe tomograph or field-ion microscope. + + For collecting data and experiments which are simulations of an atom probe + microscope or a session with such instrument use the :ref:`NXapm` application definition + and the :ref:`NXevent_data_apm` groups it provides. + + This base class implements the concept of :ref:`NXapm` whereby (meta)data are distinguished + whether these typically change during a session, so-called dynamic, or not, so-called static metadata. + This design allows to store e.g. hardware related concepts only once instead of demanding + that each image or spectrum from the session needs to be stored also with the static metadata. + + + + Which type of instrument. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Location of the lab or place where the instrument is installed. Using GEOREF is + preferred. + + + + + Nominal flight path + + The value can be extracted from the CAnalysis.CSpatial.fFlightPath + field of a CamecaRoot ROOT file. + + + + + Device which reduces ToF differences of ions in ToF experiments. + + For atom probe the reflectron can be considered an energy compensation device. + Such a device can be realized technically e.g. with a Poschenrieder lens. + + Consult the following U.S. patents for further details: + + * 3863068 and 6740872 for the reflectron + * 8134119 for the curved reflectron + + + + Was the reflectron used? + + + + + The maximum voltage applied to the reflectron, relative to system ground. + + + + + + A counter electrode of the LEAP 6000 series atom probes. + + + + + + A local electrode guiding the ion flight path. + Also called counter or extraction electrode. + + + + Acceleration voltage + + + + + The type of aperture used when the local_electrode has an aperture or acts as an aperture + in addition to acting as an extraction electrode. + + The local electrode is a component which combines functionalities of :ref:`NXlens_em`, + :ref:`NXaperture`, if not even :ref:`NXdeflector`: + + * "n/a", use when no aperture is present in the experiment + * "conical", conical aperture with a circular hole + * "feedthrough", an aperture where the specimen protrudes through a circular hole + * "custom", a user modified aperture, which is otherwise non-standard + + + + + + + + + + + + Detector for taking raw time-of-flight and ion/hit impact positions data. + + + + 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 when the detector was an MCP. + + The ATO file format is used primarily by the atom probe group of the + GPM in Rouen, France. + + + + + + + + The value can be extracted from the CRunHeader.fMcpEfficiency + field of a CamecaRoot RHIT file. + + + + + The value can be extracted from the CRunHeader.fMeshEfficiency + field of a CamecaRoot RHIT file. + + + + + + + Laser- and/or voltage-pulsing device to trigger ion removal. + + When the base class NXinstrument_apm is used in the NXapm + application definition, the values for the following fields: + + * pulse_frequency + * pulse_fraction + * pulse_voltage + * pulse_number + * standing_voltage + * pulse_energy + * incidence_vector + * pinhole_position + * spot_position + + should be recorded in the order of, and assumed associated, + with the pulse_id in an instance of :ref:`NXevent_data_apm`. + + + + + + Detail whereby ion extraction is triggered methodologically. + + + + + + + + + + Frequency with which the pulser fire(s). + + + + + 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. + + + + + + Pulsed voltage, in laser pulsing mode this field can be omitted. + + + + + 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. Otherwise, the + standing voltage applied to the sample, relative to system ground. + + + + + Group to store details about components that enable laser pulsing strategies. + + When multiple sources are available, these should be named source1, source2; + the LEAP 6000 series instruments have two sources. The majority of instruments + still has one source. In this case the variable part "ID" can be omitted. + Consequently the group should be named "source" when writing instance data. + + Atom probe microscopes use controlled laser, voltage, or a combination of pulsing + strategies to trigger ion extraction via exciting and eventual field evaporation + field emission of ion at the specimen surface. + + + + The wavelength of the radiation emitted by the source. + + + + + Nominal power of the laser source while illuminating the specimen. + + + + + Average energy of the laser at peak of each pulse. + + + + Path to pulse_id + + + + + + Details about specific positions along the laser beam + which illuminates the (atom probe) specimen. + + + + Track time-dependent settings over the course of the measurement + how the laser beam shines on the specimen, 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. + + + + + + + + + The value can be extracted from the CRunHeader.CAnalysis.fSpecimenTemperature + field of a CamecaRoot RHIT file. + + + + + + + + + The space inside the atom probe along which ions pass nominally + when they leave the specimen and travel to the detector. + + + + + + + + + + + The value can be extracted from the CRunHeader.CLasHeader.fAnalysisPressure + field of a CamecaRoot RHIT file. + + + + + + + + + + + + Free-text field for additional comments. + + + + + Relevant quantities during a measurement with a LEAP system as were + suggested by `T. Blum et al. <https://doi.org/10.1002/9781119227250.ch18>`_. + + + + Parameter that defines the rules and control loops whereby the pulser and + other components of the instrument are controlled during evaporation. + + + + + Parameter that assure maintenance of a significant yet not too high + ion influx on the detector to avoid detection losses. + + + + diff --git a/base_classes/NXlens_em.nxdl.xml b/base_classes/NXlens_em.nxdl.xml index b1339189f4..340b92cebc 100644 --- a/base_classes/NXlens_em.nxdl.xml +++ b/base_classes/NXlens_em.nxdl.xml @@ -3,7 +3,7 @@ - - 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. + 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: Scanning Electron Microscopy <https://doi.org/10.1007/978-3-540-38967-5>`_ * `P. Hawkes: Magnetic Electron Lenses <https://link.springer.com/book/10.1007/978-3-642-81516-4>`_ * `Y. Liao: Practical Electron Microscopy and Database <https://www.globalsino.com/EM/>`_ - @@ -51,7 +45,7 @@ with other research fields (MPES, XPS, OPT) could be useful--> Ideally, use instances of ``identifierNAME`` to point to a resource that provides further details. - + If such a resource does not exist or should not be used, use this free text, although it is not recommended. @@ -61,8 +55,8 @@ with other research fields (MPES, XPS, OPT) could be useful--> Descriptor for the lens excitation when the exact technical details are unknown or not directly controllable as the control software of the microscope does not enable or was not configured to display these - values (for end users). - + values for users. + Although this value does not document the exact physical voltage or excitation, it can still give useful context to reproduce the lens setting, provided a properly working instrument and software sets the lens @@ -75,7 +69,7 @@ with other research fields (MPES, XPS, OPT) could be useful--> Descriptor for the operation mode of the lens when other details are not directly controllable as the control software of the microscope does not enable or is not configured to display these values. - + Like value, the mode can only be interpreted for a specific microscope but can still be useful to guide users as to how to repeat the measurement. @@ -84,7 +78,7 @@ with other research fields (MPES, XPS, OPT) could be useful--> Excitation voltage of the lens. - + For dipoles it is a single number. For higher order multipoles, it is an array. @@ -92,7 +86,7 @@ with other research fields (MPES, XPS, OPT) could be useful--> Excitation current of the lens. - + For dipoles it is a single number. For higher-order multipoles, it is an array. @@ -111,4 +105,9 @@ with other research fields (MPES, XPS, OPT) could be useful--> + + + Qualitative description of the lens based on the number of pole pieces. + + diff --git a/base_classes/NXpeak.nxdl.xml b/base_classes/NXpeak.nxdl.xml index 1fe7e814ce..e23b87ca65 100644 --- a/base_classes/NXpeak.nxdl.xml +++ b/base_classes/NXpeak.nxdl.xml @@ -28,14 +28,14 @@ - Rank of the dependent and independent data arrays (for - multivariate scalar-valued fit.) + Rank of the dependent and independent data arrays + (for multivariate scalar-valued fit). Base class for describing a peak, its functional form, and support values - (i.e., the discretization (points) at which the function has been evaluated). + i.e., the discretization points at which the function has been evaluated. @@ -51,7 +51,7 @@ - The ``position`` field must have the same rank (``dimRank``) + The ``position`` field must have the same rank ``dimRank`` as the ``intensity`` field. Each individual dimension of ``position`` must have the same number of points as the corresponding dimension in the ``intensity`` field. @@ -64,7 +64,7 @@ - The ``intensity`` field must have the same rank (``dimRank``) + The ``intensity`` field must have the same rank ``dimRank`` as the ``intensity`` field. Each individual dimension of ``position`` must have the same number of points as the corresponding dimension in the ``position`` field. @@ -74,8 +74,8 @@ - The functional form of the peak. This could be a Gaussian, Lorentzian, - Voigt, etc. + The functional form of the peak. This could be a Gaussian, Lorentzian, Voigt, + etc. diff --git a/base_classes/NXprocess.nxdl.xml b/base_classes/NXprocess.nxdl.xml index df833f4e34..8686b8890a 100644 --- a/base_classes/NXprocess.nxdl.xml +++ b/base_classes/NXprocess.nxdl.xml @@ -1,5 +1,5 @@ - + - + - Device to reduce an atmosphere to a controlled remaining pressure level. + Device to reduce an atmosphere to a controlled pressure. - + - Principle type of the pump. + Principle type of the pump. - + + + + + + + + + + The minimum pressure achievable in a chamber after + it has been pumped down for an extended period. + + + + + The material being moved by the pump. + + Pumps intending to create a vacuum should state "vacuum" as the medium, + while pumps having the primary purpose of creating a flow or pressure + of gas should state "gas" as the medium. + + + + + + + + + + Base class to report on the characterization of an area or volume of material. + + This area or volume of material is considered a region-of-interest (ROI). + + This base class should be used when the characterization was achieved by + processing data from experiment or computer simulations into models of + the microstructure of the material and the properties of the material or its + crystal defects within this ROI. Microstructural features is a narrow synonym + for these crystal defects. + + This base class can also be used to store data and metadata of the + representation of the ROI, i.e. its discretization and shape. + + Methods from computational geometry are typically used for + defining a discretization of the area and volume. + + Do not confuse this base class with :ref:`NXregion`. The purpose + of the :ref:`NXregion` base class is to document data access i.e. + I/O pattern on arrays. Therefore, concepts from :ref:`NXregion` operate + in data space rather than in real or simulated real space. + + + diff --git a/base_classes/NXspectrum.nxdl.xml b/base_classes/NXspectrum.nxdl.xml new file mode 100644 index 0000000000..ac42594101 --- /dev/null +++ b/base_classes/NXspectrum.nxdl.xml @@ -0,0 +1,550 @@ + + + + + + + + + Number of spectra in the stack, for stacks the slowest dimension. + + + + + Number of image points along the slower dimension (k equivalent to z). + + + + + Number of image points along the slow dimension (j equivalent to y). + + + + + Number of image points along the fast dimension (i equivalent to x). + + + + + Number of energy bins (always the fastest dimension). + + + + + Base class container for reporting a set of spectra. + + The mostly commonly used scanning methods are supported. That is one-, + two-, three-dimensional ROIs discretized using regular Euclidean tilings. + + Use stack for all other tilings. + + + + Details how spectra were processed from the detector readings. + + + + Resolvable data artifact (e.g. filename) from which all values in the :ref:`NXdata` + instances in this :ref:`NXspectrum` were loaded during parsing. + + Possibility to document from which specific other serialized resource as the source + pieces of information were processed when using NeXus as a semantic file format + to serialize that information differently. + + The group in combination with an added field *context* therein adds context. + + + + Reference to a location inside the artifact that points to the specific group of values + that were processed if the artifacts contains several groups of values and thus + further resolving of ambiguities is required. + + + + + + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXspectrum` instance. + + + + + Link or name of an :ref:`NXdetector` instance with which the data were + collected. + + + + + + + One spectrum for a point of a 0d ROI. Also known as spot measurement. + + + + Counts + + + + + + + Counts + + + + + + Energy axis + + + + + + + Energy + + + + + + + One spectrum for each point of a 1d ROI. + + + + Counts + + + + + + + + Counts + + + + + + Point coordinate along the fast dimension + + + + + + + Point coordinate along the fast dimension + + + + + + Energy axis + + + + + + + Energy + + + + + + + One spectrum for each scan point of 2d ROI. + + + + Counts + + + + + + + + + Counts + + + + + + Point coordinate along the slow dimension + + + + + + + Point coordinate along the slow dimension + + + + + + Point coordinate along the fast dimension + + + + + + + Point coordinate along the fast dimension + + + + + + Energy axis + + + + + + + Energy + + + + + + + One spectrum for point of a 3d ROI. + + + + Counts + + + + + + + + + + Counts + + + + + + Point coordinate along the slower dimension + + + + + + + Point coordinate along the slower dimension + + + + + + Point coordinate along the slow dimension + + + + + + + Point coordinate along the slow dimension + + + + + + Point coordinate along the fast dimension + + + + + + + Point coordinate along the fast dimension + + + + + + Energy axis + + + + + + + Energy + + + + + + + Multiple instances of spectrum_0d. + + + + Counts + + + + + + + + Counts + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Spectrum identifier + + + + + + + Spectrum identifier + + + + + + Energy axis + + + + + + + Energy + + + + + + + Multiple instances of spectrum_2d. + + + + Counts + + + + + + + + + + Counts + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Spectrum identifier + + + + + + + Spectrum identifier + + + + + + Point coordinate along the slow dimension + + + + + + + Point coordinate along the slow dimension + + + + + + Point coordinate along the fast dimension + + + + + + + Point coordinate along the fast dimension + + + + + + Energy axis + + + + + + + Energy + + + + + + + Multiple instances of spectrum_3d. + + + + Counts + + + + + + + + + + + Counts + + + + + + Group identifier + + + + + + + Group identifier + + + + + + Spectrum identifier + + + + + + + Spectrum identifier + + + + + + Point coordinate along the slower dimension + + + + + + + Point coordinate along the slower dimension + + + + + + Point coordinate along the slow dimension + + + + + + + Point coordinate along the slow dimension + + + + + + Point coordinate along the fast dimension + + + + + + + Point coordinate along the fast dimension + + + + + + Energy axis + + + + + + + Energy + + + + + diff --git a/base_classes/NXunit_cell.nxdl.xml b/base_classes/NXunit_cell.nxdl.xml new file mode 100644 index 0000000000..f09d55aae9 --- /dev/null +++ b/base_classes/NXunit_cell.nxdl.xml @@ -0,0 +1,163 @@ + + + + + + + + Dimensionality of the lattice. + + + + + Base class to describe structural aspects of an arrangement of + atoms or ions including a crystallographic unit cell. + + Following recommendations of `CIF <https://www.iucr.org/resources/cif/spec/version1.1>`_ and `International Tables of Crystallography <https://it.iucr.org/>`_. + + + + Path to a reference frame in which the unit cell is defined + to resolve ambiguity in cases when e.g. a different reference frame + than the NeXus default reference frame (McStas) was chosen. + + + + + Dimensionality of the structure. + + + + + + + + + + Geometry of the unit cell quantified via parameters a, b, and c. + + + + + + + + Geometry of the unit cell quantified individually via parameter a. + + + + + Geometry of the unit cell quantified individually via parameter b. + + + + + Geometry of the unit cell quantified individually via parameter c. + + + + + Geometry of the unit cell quantified via parameters alpha, beta, and gamma. + + + + + + + + Geometry of the unit cell quantified individually via parameter alpha. + + + + + Geometry of the unit cell quantified individually via parameter beta. + + + + + Geometry of the unit cell quantified individually via parameter gamma. + + + + + Crystal system. + + For a crystal system in 2D space monoclinic is an exact synonym for oblique. + For a crystal system in 2D space orthorhombic is an exact synonym for rectangular. + For a crystal system in 2D space tetragonal is an exact synonym for square. + + + + + + + + + + + + + + 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. + + + + + Area of the unit cell if dimensionality is 2. + + + + + Volume of the unit cell if dimensionality is 3. + + + + diff --git a/contributed_definitions/NXapm.nxdl.xml b/contributed_definitions/NXapm.nxdl.xml deleted file mode 100644 index 6f02ae1809..0000000000 --- a/contributed_definitions/NXapm.nxdl.xml +++ /dev/null @@ -1,1696 +0,0 @@ - - - - - - - - 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 spatio-temporally 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/NXchemical_composition.nxdl.xml b/contributed_definitions/NXchemical_composition.nxdl.xml deleted file mode 100644 index 0625ccf289..0000000000 --- a/contributed_definitions/NXchemical_composition.nxdl.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - - 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/NXcoordinate_system_set.nxdl.xml b/contributed_definitions/NXcoordinate_system_set.nxdl.xml index c2276f3a93..120caa7390 100644 --- a/contributed_definitions/NXcoordinate_system_set.nxdl.xml +++ b/contributed_definitions/NXcoordinate_system_set.nxdl.xml @@ -2,9 +2,9 @@ - + + - 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 application definition? + + * 0; if there is no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across + the application definition, 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 define at least one NXcoordinate_system + instance. This shall be named such that it is clear how this coordinate system is + typically referred to in a community. For the NeXus `McStas coordinate system, it is + advised to call it mcstas for the sake of improved clarity. + 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 the case + of two or more instances of NXcoordinate_system in one :ref:`NXcoordinate_system_set`, + it is also advised to specify the relationship between the two coordinate systems by + using the (NXtransformations) group within NXcoordinate_system. + + 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. - - + + + 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) + 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. Apart from undefined, proper Euler angles + are distinguished from (improper) Tait-Bryan angles. + + + + + + + + + + + + + + + + + + + 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 mechanical processing where one has to specify which directions + (e.g. rolling, transverse, and normal direction) align how with the direction of the base + vectors of the sample_reference_frame. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xp, Yp, Zp. + + + + + Details about the sample_reference_frame that is typically overlaid onto the surface of the sample. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xs, Ys, Zs. + + + - 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. + Details about the detector_reference_frame for a specific detector. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xd, Yd, Zd. + + It is assumed that the configuration is inspected by looking towards the sample surface + from a position that is located behind the detector. + + If any of these assumptions is not met, the user is required to explicitly state this. - - - - diff --git a/contributed_definitions/NXcs_computer.nxdl.xml b/contributed_definitions/NXcs_computer.nxdl.xml deleted file mode 100644 index b6cd467a2b..0000000000 --- a/contributed_definitions/NXcs_computer.nxdl.xml +++ /dev/null @@ -1,80 +0,0 @@ - - - - - - - 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. - - - - - - A list of physical processing units (can be multi-core chips). - - - - - A list of physical coprocessor/graphic cards/accelerator units. - - - - - Details about the memory sub-system. - - - - - Details about the I/O sub-system. - - - diff --git a/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml b/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml deleted file mode 100644 index fe1707aa14..0000000000 --- a/contributed_definitions/NXcs_filter_boolean_mask.nxdl.xml +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - - 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. - - One use case is processing of object sets (like 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, it is useful to document which points were - taken. One can store this information in a compact manner with an array of - boolean values. If the value is True the point is taken, else it is not. - - If the points are identified by an array of integer identifiers and an - arbitrary spatial filtering, the boolean array will be filled with True and False - values in an arbitrary manner. Especially when the number of points is large, - for instance several thousands and 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 instance 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 that taken point. 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 compact descriptions - to store information about set memberships in a compact manner. - In general it is true, though, that which representation is best, i.e. - most compact (especially when compressed) depends strongly on occupation of - the array. - - This base class just bookkeeps metadata to inform software about necessary - modulo operations to decode the set membership of each object. This is useful - because the number of objects not necessarily is an integer multiple of the bit depth. - - - - 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 unsigned integer array representing the content of the mask. - If padding is used the padded 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. - - - - - - diff --git a/contributed_definitions/NXcs_prng.nxdl.xml b/contributed_definitions/NXcs_prng.nxdl.xml deleted file mode 100644 index 16d192c4c3..0000000000 --- a/contributed_definitions/NXcs_prng.nxdl.xml +++ /dev/null @@ -1,85 +0,0 @@ - - - - - - - The symbols used in the schema to specify e.g. dimensions of arrays. - - - - Computer science description of pseudo-random number generator. - - The purpose of such metadata is to identify if exactly the same sequence - can be reproduced, like for a PRNG or not (for a true physically random source). - - - - Different approaches for generating random numbers with a computer exists. - Some use a dedicated physical device where the state is unpredictable (physically). - Some use a mangling of the system clock (system_clock), where also without - additional pieces of information the sequence is not reproducible. - Some use so-called pseudo-random number generator (PRNG) are used. - These are algorithms which yield a deterministic sequence of practically - randomly appearing numbers. These algorithms different in their quality in - how close the resulting sequences are random. - 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. - - - - Version and build number, or commit hash. - - - - - - Parameter of the PRNG controlling its initialization and thus the specific - sequence of numbers it generates. - - - - - - Number of initial draws from the PRNG which are discarded in an effort - to equilibrate the sequence and make it thus to statistically more random. - 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 deleted file mode 100644 index 97105a1b25..0000000000 --- a/contributed_definitions/NXcs_profiling.nxdl.xml +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - The symbols used in the schema to specify e.g. dimensions of arrays. - - - - Computer science description for summary performance/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. - - At the most basic level users may wish to document how long e.g. a data - analysis with a scientific software (app). - A frequent idea is here to judge how critical the effect is 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. In this case, - mainly the order of magnitude is relevant, as well as how this can be achieved - with using parallelization (i.e. reporting the number of CPU and GPU resources - used, the number of processes and/or threads, and basic details about the - computing node/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 as well as for tracking bugs and other development purposes. - 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. - 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 demand 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, for instance for app using a - 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 with how many nominal threads were accessible to the app 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 deleted file mode 100644 index 195dee88c6..0000000000 --- a/contributed_definitions/NXcs_profiling_event.nxdl.xml +++ /dev/null @@ -1,95 +0,0 @@ - - - - - - - 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 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/NXebeam_column.nxdl.xml b/contributed_definitions/NXebeam_column.nxdl.xml index 3edca25f0d..665c535aed 100644 --- a/contributed_definitions/NXebeam_column.nxdl.xml +++ b/contributed_definitions/NXebeam_column.nxdl.xml @@ -85,7 +85,7 @@ relevant from maintenance point of view--> - + A sensor used to monitor an external or internal condition. diff --git a/contributed_definitions/NXem.nxdl.xml b/contributed_definitions/NXem.nxdl.xml index ad33f94aab..745fdb165b 100644 --- a/contributed_definitions/NXem.nxdl.xml +++ b/contributed_definitions/NXem.nxdl.xml @@ -317,7 +317,7 @@ that it is required--> **There are a few design choices to consider with sub-ordinate groups:** - * Images and spectra should be stored as :ref:`NXimage_set` and :ref:`NXspectrum_set` + * Images and spectra should be stored as :ref:`NXimage` and :ref:`NXspectrum_set` instances to hold data at the earliest possible step in the computational processing (which is usually performed with the microscope control and or integrated analysis software). The formatting of the NXdata groups enables the @@ -698,7 +698,7 @@ making up the instrument follows at this level of the hierarchy--> * 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 + * NXmanipulator: 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, @@ -722,14 +722,14 @@ making up the instrument follows at this level of the hierarchy--> - + - + @@ -1045,7 +1045,7 @@ making up the instrument follows at this level of the hierarchy--> - + @@ -1136,7 +1136,7 @@ we should give better guidance which option to use--> - + @@ -1201,7 +1201,7 @@ system like offer through ELNs/or LIMS--> Post-processing is performed with commercial software or various types and scripts. - Currently, several specializations of NXimage_set and Nspectrum_set + Currently, several specializations of NXimage and Nspectrum_set are used which store some details of this processing. However, as post- processing tasks can be substantially more advanced and involved it is clear that data artifacts from the measurement and data artifacts @@ -1264,7 +1264,7 @@ system like offer through ELNs/or LIMS--> and thus mappable on a common schema using a controlled common vocabulary. - Therefore we encourage user for now to store for each NXimage_set + Therefore we encourage user for now to store for each NXimage or NXspectra_set instance to supply the so-called source of the data. This can for instance be the name and hashvalue of the original file which was acquired during the microscope session and from which then @@ -1302,7 +1302,7 @@ system like offer through ELNs/or LIMS--> - + @@ -1410,7 +1410,7 @@ NEW ISSUE: should this only be one instance for a given event?--> - + @@ -1624,9 +1624,9 @@ NEW ISSUE: all of this should be offloaded to NXem_edx -\->--> - + @@ -1699,9 +1699,9 @@ no summary because this will be handled by EBSD--> exists: optional a collection of specific details about state of the microscope--> - + - + @@ -1982,7 +1982,7 @@ a collection of specific details about state of the microscope--> - + @@ -2018,7 +2018,7 @@ a collection of specific details about state of the microscope--> - + diff --git a/contributed_definitions/NXevent_data_em.nxdl.xml b/contributed_definitions/NXevent_data_em.nxdl.xml index 4192c48798..ad2f57b107 100644 --- a/contributed_definitions/NXevent_data_em.nxdl.xml +++ b/contributed_definitions/NXevent_data_em.nxdl.xml @@ -201,26 +201,26 @@ This field may also be used for storing additional information about the event. - + diff --git a/contributed_definitions/NXimage_set.nxdl.xml b/contributed_definitions/NXimage_set.nxdl.xml deleted file mode 100644 index a482480c85..0000000000 --- a/contributed_definitions/NXimage_set.nxdl.xml +++ /dev/null @@ -1,128 +0,0 @@ - - - - - - - - Number of images in the stack. - - - - - Number of pixel per image in the slow direction. - - - - - Number of pixel per image in the fast direction. - - - - - Container for reporting a set of images taken. - - - - Details how images were processed from the detector readings. - - - - Resolvable data artifact (e.g. filename) from which the all values in - the NXdata instances in this NXimage_set were loaded during parsing. - - - - An at least as strong as SHA256 hashvalue of the data artifact which - source represents digitally to support provenance tracking. - - - - - - Imaging (data collection) mode of the instrument during acquisition - of the data in this NXimage_set instance. - - - - - Link or name of an NXdetector instance with which the data were collected. - - - - - - - Image (stack). - - - - Image intensity values. - - - - - - - - - - Image identifier - - - - - - - Image identifier. - - - - - - Pixel coordinate center of mass along y direction. - - - - - - - Coordinate along y direction. - - - - - - Pixel coordinate center of mass along x direction. - - - - - - - Coordinate along x direction. - - - - - diff --git a/contributed_definitions/NXpulser_apm.nxdl.xml b/contributed_definitions/NXpulser_apm.nxdl.xml deleted file mode 100644 index f2a6edaf02..0000000000 --- a/contributed_definitions/NXpulser_apm.nxdl.xml +++ /dev/null @@ -1,165 +0,0 @@ - - - - - - - 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/NXreflectron.nxdl.xml b/contributed_definitions/NXreflectron.nxdl.xml deleted file mode 100644 index e70e5481ed..0000000000 --- a/contributed_definitions/NXreflectron.nxdl.xml +++ /dev/null @@ -1,44 +0,0 @@ - - - - - - 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). - - - - - 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/NXstage_lab.nxdl.xml b/contributed_definitions/NXstage_lab.nxdl.xml deleted file mode 100644 index dca422c57d..0000000000 --- a/contributed_definitions/NXstage_lab.nxdl.xml +++ /dev/null @@ -1,154 +0,0 @@ - - - - - - A stage lab can be used to hold, align, 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. - - With such stages comes the need for storing various (meta)data - that are generated while manipulating 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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/>`_ - * `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) - * `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>`_ - - - - 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 - - - - - Should be defined by the application definition. - - - - - Should be defined by the application definition. - - - - - Should be defined by the application definition. - - - - - Should be defined by the application definition. - - - - - - - - Voltage applied to the stage to decelerate electrons. - - - - - - diff --git a/manual/source/classes/contributed_definitions/apm-structure.rst b/manual/source/classes/contributed_definitions/apm-structure.rst index 10e2c77c36..c3560b1303 100644 --- a/manual/source/classes/contributed_definitions/apm-structure.rst +++ b/manual/source/classes/contributed_definitions/apm-structure.rst @@ -8,12 +8,6 @@ Atom-probe tomography IntroductionApm ApmAppDef ApmBC - WhatHasBeenAchieved - ApmParaprobeAppDef - ApmParaprobeNewBC - NextStep - - .. _IntroductionApm: @@ -41,22 +35,40 @@ 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` + :ref:`NXcoordinate_system`: 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 charged 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:`NXatom`: + Base class to describe groups of atoms and charged 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:`NXchemical_composition`: + Base class to report the chemical composition of a sample or its parts. + + :ref:`NXcircuit`: + Base class to describe electronic circuits. - :ref:`NXfabrication`: - A base class to bundle manufacturer/technology-partner-specific details about a - component or device of an instrument. + :ref:`NXinstrument_apm`: + A base class which defines all modular parts that make up an instrument (real or simulated) for studying + ion extraction as performed in atom probe and related field-ion microscopy. This base class is used in NXapm in two places: + One that is placed inside an ENTRY.measurement.instrument + group. This group holds all those (meta)data which do not change during a session, i.e. instrument name, typically identifier of + hardware components or version of control software. Another one that is placed inside an ENTRY.measurements.eventID group. + This group holds all those (meta)data data change when collecting data during a session. + + :ref:`NXevent_data_apm`: + A base class representing a container to hold time-stamped and instrument-specific-state- + annotated data during a session at an electron microscope. + + :ref:`NXroi_process`: + Base class to report details about results obtained for a specific region of a sample a region-of-interest. + + :ref:`NXcomponent` and :ref:`NXfabrication`: + Base classes to group frequently used descriptions such as physical parts an is constructed from instrument and + manufacturing details of it bundling manufacturer/technology-partner-specific details. :ref:`NXpeak`: A base class to describe peaks mathematically to detail how peaks in @@ -66,261 +78,10 @@ The following base classes are proposed to support modularizing the storage of p :ref:`NXpump`: A base class to describe details about pump(s) of an instrument. - :ref:`NXpulser_apm`: - A base class to describe the high-voltage and/or laser pulsing capabilities of - an atom probe microscope. - - :ref:`NXreflectron`: - A base class to describe a kinetic-energy-sensitive filtering device - for time of flight (ToF) mass spectrometry. - - :ref:`NXstage_lab`: + :ref:`NXmanipulator`: A base class to describe the specimen fixture including the cryo-head. Nowadays, these stages 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 the user usually 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. - - -Like every research community data processing steps are essential to transform measurements -into knowledge. These processing steps should be documented to enable reproducible research -and learn how pieces of information were 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 `_ - -.. _IntroductionApmParaprobe: - -apmtools -######## - -One tool is the paraprobe-toolbox software package in the the apmtools container. -The software is developed by `M. Kühbach et al. `_. - -Here we show how NeXus is used to consistently define application definitions for scientific software -in the field of atom probe. In this community 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 -which describe the micro- and nanostructure of materials that are studied with -atom probe microscopy. - -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 their analyses quantitatively. - -Second, scientific software like the tools in the paraprobe-toolbox implement a -numerical/algorithmical (computational) workflow whereby data from multiple input sources -(like previous analysis results) are processed and carried through more involved analysis -within several steps inside the tool. The tool then creates output as files. - -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 thereby empower scientists -to fulfill better the "R", i.e. reproducibility of their daily FAIR research practices. - -The paraprobe-toolbox is one example of a software which implements a workflow -via a sequence of operations executed within a jupyter notebook -(or Python script respectively). Specifically, individual tools are chained. -Convenience functions are available to create well-defined input/configuration -files for each tool. These config files instruct the tool upon processing. - -In this design, each workflow step (with a tool) is in fact a pair (or triple) of -at least two sub-steps: i) the creation of a configuration file, -ii) the actual analysis using the Python/or C/C++ tools, -iii) the optional post-processing/visualizing of the results inside the NeXus/HDF5 -files generated from each tool run using other software. - - -.. _WhatHasBeenAchieved: - -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 aimed at a change of the paraprobe-toolbox -and its interaction with files for all tools so that only well-defined configuration files -are accepted as input and results end up as specifically formatted output. For this -NeXus application definitions are used. - -Data and metadata between the tools are exchanged with NeXus/HDF5 files. -Specifically, we created for each tool an application definition (see below) -which details all possible settings and options for the configuration as to -guide users. The config(uration) files are currently implemented as HDF5 files, -whose content matches to the naming conventions of the respective `config` application -definition for each tool. As an example NXapm_paraprobe_config_surfacer specifies -how a configuration file for the paraprobe-surfacer tool should be formatted -and which parameter it should and/or may contain. - -That is 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 -processing chain/workflow. - -As an example, a user may first range their reconstruction and then compute -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 ion type labels stored. -This results file is formatted according to the tool-specific `results` -application definition. This results file and the reconstruction is -imported by the spatial statistics tool which again keeps track of all files. - -This design makes it possible to rigorously trace which numerical results -were achieved with a specific input and settings using specifically-versioned tools. - -We understand that this additional handling of metadata and provenance tracking -may not be at first glance super relevant for scientists or appears to be an -unnecessarily complex feature. There is indeed an additional layer of work which -came with the development and maintenance of this functionality. - -However, we are convinced that this is the preferred way of performing software -development and data analyses as it enables users to take advantage of a completely -automated provenance tracking which happens silently in the background. - -.. _ApmParaprobeAppDef: - -Application Definitions -####################### - -Application definitions for the input side (configuration) of each tool were defined. - - :ref:`NXapm_paraprobe_config_transcoder`: - Configuration of paraprobe-transcoder - Load POS, ePOS, APSuite APT, RRNG, RNG, and NXapm HDF5 files. - - :ref:`NXapm_paraprobe_config_ranger`: - Configuration of paraprobe-ranger - Apply ranging definitions and explore possible molecular ions. - - :ref:`NXapm_paraprobe_config_selector`: - Configuration of paraprobe-selector - Defining complex spatial regions-of-interest to filter reconstructed datasets. - - :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_config_distancer`: - Configuration of paraprobe-distancer - Compute 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_config_nanochem`: - Configuration of paraprobe-nanochem - Compute delocalization, iso-surfaces, analyze 3D objects, and composition profiles. - - :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_config_spatstat`: - Configuration of paraprobe-spatstat - Spatial statistics on the entire or selected regions of the reconstructed dataset. - - :ref:`NXapm_paraprobe_config_clusterer`: - Configuration of paraprobe-clusterer - Import cluster analysis results of IVAS/APSuite and perform clustering - analyses in a Python ecosystem. - -Application definitions for the output side (results) of each tool were defined. - - :ref:`NXapm_paraprobe_results_transcoder`: - Results of paraprobe-transcoder - Store reconstructed positions, ions, and charge states. - - :ref:`NXapm_paraprobe_results_ranger`: - Results of paraprobe-ranger - Store applied ranging definitions and combinatorial analyses of all possible iontypes. - - :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_results_surfacer`: - Results of paraprobe-surfacer - Store triangulated surface meshes of models for the edge of a dataset. - - :ref:`NXapm_paraprobe_results_distancer`: - Results of paraprobe-distancer - Store analytical distances between ions to a set of triangles. - - :ref:`NXapm_paraprobe_results_tessellator`: - Results of paraprobe-tessellator - Store volume of all Voronoi cells about each ion in the dataset. - - :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_results_intersector`: - Results of paraprobe-intersector - Store graph of microstructural features and relations/link identified between them. - - :ref:`NXapm_paraprobe_results_spatstat`: - Results of paraprobe-spatstat - Store spatial correlation functions. - - :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. -Therefore, we are happy for comments and suggestions. - -The majority of data analyses in atom probe use a common set of operations and -conditions on the input data even though this might not be immediately evident -or might not have been so explicitly communicated in the literature. -Some tools have a specific scope because of which algorithms are hardcoded -to work for specific material systems. A typical example is a ranging tool -which exploits that all the examples it is used for apply to a specific material -and thus specific iontypes can be hardcoded. - -Instead, we are convinced it is better to follow a more generalized approach. -The following base classes and the above application definitions present examples -how one can use NeXus for this. - - :ref:`NXapm_input_reconstruction`: - A description from which file the reconstructed ion positions are imported. - - :ref:`NXapm_input_ranging`: - A description from which file the ranging definitions are imported. - The design of the ranging definitions is, thanks to :ref:`NXion`, so - general that all possible nuclids can be considered, be they observationally - stable, be they radioactive or transuranium nuclids. - -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, -i.e. more general filters: - - :ref:`NXspatial_filter`: - A proposal 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 all of the most commonly used - geometric primitives in atom probe. - - :ref:`NXsubsampling_filter`: - A proposal for a filter that can also be used for specifying how entries - like ions can be filtered via sub-sampling. - - :ref:`NXmatch_filter`: - A proposal for a filter that can also be used for specifying how entries - like ions can be filtered based on their type (ion species) - or hit multiplicity. + 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. diff --git a/manual/source/classes/contributed_definitions/em-structure.rst b/manual/source/classes/contributed_definitions/em-structure.rst index 6f011c62fa..66eedc8a41 100644 --- a/manual/source/classes/contributed_definitions/em-structure.rst +++ b/manual/source/classes/contributed_definitions/em-structure.rst @@ -41,19 +41,12 @@ A microscope session ends with the scientist removing the specimen from the inst Base Classes ############ -The following base classes are proposed to support modularizing the storage of pieces of information: +The following base classes are proposed to support modularizing the storage of pieces of information with a focus on EM: - :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 either CEOS or Nion. + :ref:`NXaberration` and :ref:NXcorrector_cs`: + Base class to describe procedures and values for the calibration of (spherical) aberrations and the devices for achieving this technically. - :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`: + :ref:`NXcoordinate_system`: A base class to describe different coordinate systems used and/or to be harmonized or transformed into one another when interpreting the dataset. @@ -69,20 +62,14 @@ The following base classes are proposed to support modularizing the storage of p 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 and use 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:`NXimage`: + Base class for storing acquisition details for individual images or stacks of images. Specialized versions can be defined and use 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 simulated or known volume of interaction of the electrons with the specimen. - - :ref:`NXion`: + :ref:`NXatom` and :ref:`NXion`: A base class to describe charged 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`: @@ -106,26 +93,5 @@ The following base classes are proposed to support modularizing the storage of p :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 can be used to document the scan pattern. - :ref:`NXspectrum_set`: - Base class and specializations comparable to NXimage_set but for storing spectra. Specialized base classes should use 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`: - As it was mentioned for atom probe microscopy, this is 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 frequently offer. - -Method-specific concepts and their usage in application definitions -################################################################### - -It became clear during the design of the electron-microscopy-specific additions to NeXus that there are sets of pieces of information (data and metadata) which are relevant for a given experiment but have usually only few connections to the detailed description of the workflow of processing these data into knowledge, motivating the granularization of these pieces of information in their own application definition. In fact, one limitation of application definitions in NeXus is 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 but all scientifically relevant conclusions are drawn later, i.e. through post-processing these data. These numerical and algorithmic steps define computational workflows where data from the application definitions such as NXem are used as input but many additional concepts and constraints may apply without any need for changing constraints on fields or groups of NXem. If we were to modify NXem for these cases, NXem would likely combinatorially diverge as every different combination of required constraints would demand having their own but almost similar application definition. For this reason, we propose to define the following base classes: - -More consolidation through the use of NXsubentry classes should be considered in the future. - - :ref:`NXem_ebsd`: - Application definition for collecting and indexing Kikuchi pattern into orientation maps for the two-dimensional, three- and four-dimensional case. - -Several new base classes are used by this application definition. - - :ref:`NXem_ebsd_conventions`: - A collection of reference frames and rotation conventions necessary to interpret the alignment and orientation data. - - :ref:`NXem_ebsd_crystal_structure_model`: - A description of a crystalline phase/structure used for a forward simulation using kinetic or dynamic diffraction theory to generate simulated diffraction pattern against which measured pattern can be indexed. + :ref:`NXspectrum`: + Base class and specializations comparable to NXimage but for storing spectra. Specialized base classes should use 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. diff --git a/requirements.txt b/requirements.txt index 16daca1605..2f925cc845 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,7 @@ # Prepare for Documentation lxml pyyaml -nyaml +nyaml>=0.2.2 # Documentation building sphinx>=5