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/applications/nyaml/NXapm.yaml b/applications/nyaml/NXapm.yaml new file mode 100644 index 0000000000..5372f6bf3f --- /dev/null +++ b/applications/nyaml/NXapm.yaml @@ -0,0 +1,3131 @@ +category: application +doc: | + 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_ht: | + Number of hit qualities, the so-called hit types, distinguished. + n_dld: | + Number of delay-line-detector (DLD) wires of the detector. + n_bins: | + Number of bins used in the mass-to-charge-state-ratio spectrum. + p: | + 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. + p_out: | + Number of pulses returned by the hit_finding algorithm. + Neither necessarily equal to p nor to n. + 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. + m_r: | + Number of mass resolution values. +type: group +NXapm(NXobject): + (NXentry): + exists: ['min', '1', 'max', 'unbounded'] + definition(NX_CHAR): + \@version(NX_CHAR): + exists: optional + enumeration: [NXapm] + profiling(NXcs_profiling): + exists: optional + doc: | + The configuration of the software that was used to generate this NeXus file. + programID(NXprogram): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + doc: | + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software which writes these NXprogram instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library `_ + which is used by the `NOMAD `_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + program(NX_CHAR): + \@version(NX_CHAR): + environment(NXcollection): + exists: recommended + doc: | + Programs and libraries representing the computational environment + (NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + program(NX_CHAR): + \@version(NX_CHAR): + run_number(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + 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. + experiment_alias(NX_CHAR): + exists: optional + doc: | + Alias or short name which scientists can use to refer to this experiment. + experiment_description(NX_CHAR): + exists: optional + doc: | + 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. + start_time(NX_DATE_TIME): + doc: | + 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. + end_time(NX_DATE_TIME): + exists: recommended + doc: | + 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. + elapsed_time(NX_FLOAT): + exists: recommended + unit: NX_TIME + doc: | + How long did the measurement take e.g. use CRunHeader.CAnalysis.fElapsedTime + citeID(NXcite): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + doi(NX_CHAR): + noteID(NXnote): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + operation_mode(NX_CHAR): + doc: | + 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. `_). + enumeration: + open_enum: true + items: [apt, fim, apt_fim] + userID(NXuser): + exists: recommended + nameType: partial + identifierNAME(NX_CHAR): + nameType: partial + exists: recommended + \@type(NX_CHAR): + name(NX_CHAR): + exists: optional + sample(NXsample): + exists: recommended + doc: | + Description of the sample from which the specimen was prepared or + site-specifically cut out using e.g. a focused-ion beam instrument. + + 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. + identifierNAME(NX_CHAR): + nameType: partial + exists: recommended + is_simulation(NX_BOOLEAN): + doc: | + False, if the sample is a real one. + True, if the sample is a virtual one. + alias(NX_CHAR): + doc: | + Given name/alias for the sample. + grain_diameter(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Qualitative information about the grain size, here specifically + described as the equivalent spherical diameter of an assumed + average grain size for the crystal ensemble. + + 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. + grain_diameter_errors(NX_FLOAT): + exists: optional + unit: NX_LENGTH + doc: | + Magnitude of the standard deviation of the grain_diameter. + heat_treatment_time(NX_FLOAT): + exists: optional + unit: NX_TIME + doc: | + 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. + heat_treatment_temperature(NX_FLOAT): + exists: optional + unit: NX_TEMPERATURE + doc: | + 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. + heat_treatment_temperature_errors(NX_FLOAT): + exists: optional + unit: NX_TEMPERATURE + doc: | + 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. + heat_treatment_quenching_rate(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + 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. + heat_treatment_quenching_rate_errors(NX_FLOAT): + exists: optional + unit: NX_ANY + doc: | + 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. + description(NX_CHAR): + exists: optional + chemical_composition(NXchemical_composition): + exists: recommended + doc: | + The chemical composition of the sample. + + Typically, it is assumed that this more macroscopic composition is representative + for the material so that the composition of the typically substantially less + voluminous specimen probes from the more voluminous sample. + normalization(NX_CHAR): + ELEMENT(NXatom): + exists: ['min', '1', 'max', '118'] + nameType: any + chemical_symbol(NX_CHAR): + composition(NX_FLOAT): + composition_errors(NX_FLOAT): + exists: recommended + specimen(NXsample): + doc: | + Description of the specimen that was cut off from the sample. + + In atom probe jargon this is typically referred to as the tip. + identifierNAME(NX_CHAR): + nameType: partial + exists: recommended + is_simulation(NX_BOOLEAN): + doc: | + False, if the specimen is a real one. + True, if the specimen is a virtual one. + alias(NX_CHAR): + exists: recommended + doc: | + 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_parent(NX_CHAR): + exists: recommended + doc: | + 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. + preparation_date(NX_DATE_TIME): + exists: recommended + doc: | + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. 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. + atom_types(NX_CHAR): + doc: | + 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. + description(NX_CHAR): + exists: optional + doc: | + Discouraged free-text field. + is_polycrystalline(NX_BOOLEAN): + exists: recommended + doc: | + True, if the specimen contains a grain or phase boundary. + False, if the specimen is a single crystal. + is_amorphous(NX_BOOLEAN): + exists: recommended + doc: | + True, if the specimen is amorphous. + False, if the specimen is not. + initial_radius(NX_FLOAT): + exists: recommended + unit: NX_LENGTH + doc: | + Ideally measured otherwise best elaborated guess of the initial radius of the + specimen. + shank_angle(NX_FLOAT): + exists: recommended + unit: NX_ANGLE + doc: | + 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. + consistent_rotations(NXparameters): + exists: recommended + doc: | + The conventions used when reporting crystal orientations. + We follow the best practices of the Material Science community + that are defined in reference ``_. + rotation_handedness(NX_CHAR): + doc: | + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin. + This is in accordance with convention 2 of reference ``_. + + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + enumeration: [counter_clockwise, clockwise] + rotation_convention(NX_CHAR): + doc: | + How are rotations interpreted into an orientation according to convention 3 + of reference ``_. + enumeration: [passive, active] + euler_angle_convention(NX_CHAR): + doc: | + How are Euler angles interpreted given that there are several choices e.g. zxz, xyz + according to convention 4 of reference ``_. + + 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. + enumeration: [zxz, xyx, yzy, zyz, xzx, yxy, xyz, yzx, zxy, xzy, zyx, yxz] + axis_angle_convention(NX_CHAR): + doc: | + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of reference ``_. + enumeration: [rotation_angle_on_interval_zero_to_pi] + sign_convention(NX_CHAR): + doc: | + Which sign convention is followed when converting orientations + between different parametrizations/representations according + to convention 6 of reference ``_. + enumeration: [p_plus_one, p_minus_one] + NAMED_reference_frame(NXcoordinate_system): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + doc: | + 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. + alias(NX_CHAR): + exists: optional + type(NX_CHAR): + origin(NX_CHAR): + exists: recommended + x(NX_NUMBER): + x_direction(NX_CHAR): + exists: recommended + y(NX_NUMBER): + y_direction(NX_CHAR): + exists: recommended + z(NX_NUMBER): + z_direction(NX_CHAR): + exists: recommended + measurement(NXapm_measurement): + exists: optional + status(NX_CHAR): + exists: recommended + quality(NX_CHAR): + exists: recommended + instrument(NXinstrument_apm): + type(NX_CHAR): + exists: recommended + location(NX_CHAR): + exists: recommended + flight_path(NX_FLOAT): + exists: recommended + fabrication(NXfabrication): + exists: recommended + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + reflectron(NXcomponent): + exists: optional + applied(NX_BOOLEAN): + local_electrode(NXlens_em): + exists: recommended + name(NX_CHAR): + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + aperture_type(NX_CHAR): + exists: recommended + ion_detector(NXdetector): + exists: recommended + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + pulser(NXcomponent): + exists: recommended + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + sourceID(NXsource): + exists: ['min', '0', 'max', '2'] + nameType: partial + fabrication(NXfabrication): + exists: recommended + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + stage(NXmanipulator): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + analysis_chamber(NXcomponent): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + buffer_chamber(NXcomponent): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + load_lock_chamber(NXcomponent): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + getter_pump(NXpump): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + roughening_pump(NXpump): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + turbomolecular_pump(NXpump): + exists: optional + fabrication(NXfabrication): + exists: optional + vendor(NX_CHAR): + model(NX_CHAR): + serial_number(NX_CHAR): + exists: recommended + eventID(NXevent_data_apm): + nameType: partial + exists: ['min', '0', 'max', 'unbounded'] + start_time(NX_DATE_TIME): + exists: recommended + end_time(NX_DATE_TIME): + exists: recommended + instrument(NXinstrument_apm): + exists: recommended + reflectron(NXcomponent): + exists: recommended + voltage(NX_FLOAT): + local_electrode(NXlens_em): + exists: recommended + voltage(NX_FLOAT): + pulser(NXcomponent): + exists: recommended + pulse_mode(NX_CHAR): + pulse_frequency(NX_FLOAT): + pulse_fraction(NX_FLOAT): + pulse_voltage(NX_FLOAT): + exists: optional + dimensions: + rank: 1 + dim: (n,) + pulse_number(NX_UINT): + exists: optional + dimensions: + rank: 1 + dim: (n,) + standing_voltage(NX_FLOAT): + exists: optional + dimensions: + rank: 1 + dim: (n,) + sourceID(NXsource): + exists: ['min', '0', 'max', '2'] + nameType: partial + wavelength(NX_FLOAT): + exists: recommended + unit: NX_WAVELENGTH + power(NX_FLOAT): + unit: NX_POWER + pulse_energy(NX_FLOAT): + dimensions: + rank: 1 + dim: (n,) + stage(NXmanipulator): + temperature_sensor(NXsensor): + measurement(NX_CHAR): + value(NX_FLOAT): + analysis_chamber(NXcomponent): + pressure_sensor(NXsensor): + measurement(NX_CHAR): + value(NX_FLOAT): + control(NXparameters): + exists: recommended + evaporation_control(NX_CHAR): + target_detection_rate(NX_NUMBER): + simulation(NXapm_simulation): + exists: optional + atom_probeID(NXroi_process): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + doc: | + A region-of-interest analyzed either during or after the session for which + specific processed data of the measured or simulated data are available. + + 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. + initial_specimen(NXimage): + exists: recommended + doc: | + SEM or TEM image of the initial specimen taken before the measurement. + image_2d(NXdata): + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_UINT): + nameType: partial + real(NX_NUMBER): + axis_j(NX_NUMBER): + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + axis_i(NX_NUMBER): + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + final_specimen(NXimage): + exists: recommended + doc: | + SEM or TEM image of the final specimen taken after completion of the + measurement. + image_2d(NXdata): + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_UINT): + nameType: partial + real(NX_NUMBER): + axis_j(NX_NUMBER): + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + axis_i(NX_NUMBER): + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + raw_data(NXprocess): + exists: optional + doc: | + 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. + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + doc: | + 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 `_. + Further instances (program2, ...) can be used to list the dependencies, the + python virtual environment. + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: recommended + doc: | + 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. + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + number_of_dld_wires(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + The number of delay-line-detector (DLD) wires present. + enumeration: [1, 2, 3] + dld_wire_names(NX_CHAR): + exists: optional + doc: | + 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. + dimensions: + rank: 2 + dim: (n_dld, 2) + arrival_time_pairs(NX_NUMBER): + exists: optional + unit: NX_TIME + doc: | + Raw readings from the analog-to-digital-converter + timing circuits of the detector wires. + dimensions: + rank: 3 + dim: (p, n_dld, 2) + hit_finding(NXprocess): + exists: recommended + doc: | + 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. + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + config(NXnote): + exists: recommended + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + hit_positions(NX_NUMBER): + exists: recommended + unit: NX_LENGTH + doc: | + Evaluated ion impact coordinates on the detector. + Use the depends_on field to specify which reference + frame the positions are defined in. + dimensions: + rank: 2 + dim: (p_out, 2) + \@depends_on(NX_CHAR): + doc: | + Contains the path to an instance of NX_coordinate_system + in which the positions are defined. + total_event_golden(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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. + total_event_incomplete(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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. + total_event_multiple(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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. + total_event_partials(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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. + total_event_record(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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_type(NX_CHAR): + exists: optional + doc: | + 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". + dimensions: + rank: 1 + dim: (n_ht,) + hit_quality(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + Hit quality identifier for each pulse. + Identifier has to be within hit_quality_type. + dimensions: + rank: 1 + dim: (p_out,) + hit_multiplicity(NX_UINT): + exists: optional + unit: NX_UNITLESS + doc: | + 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. + dimensions: + rank: 1 + dim: (p_out,) + hit_spatial_filtering(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: optional + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + evaporation_id_offset(NX_INT): + unit: NX_UNITLESS + doc: | + Integer which defines the first evaporation_id. + Typically, this is either zero or one. + evaporation_id(NX_INT): + unit: NX_UNITLESS + doc: | + 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. + dimensions: + rank: 1 + dim: (n,) + hit_filter(NXcs_filter_boolean_mask): + exists: recommended + number_of_objects(NX_UINT): + bitdepth(NX_UINT): + mask(NX_UINT): + + # at this point the set of events p_out has been filtered down to n + voltage_and_bowl(NXprocess): + exists: recommended + doc: | + 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. + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: optional + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + config(NXparameters): + correction_peak(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + Reference mass-to-charge state ratio value + + For example 16 Da as mentioned by `T. Blum et al. `_ (page 371). + raw_tof(NX_FLOAT): + exists: recommended + doc: | + Raw time-of-flight data without corrections. + dimensions: + rank: 1 + dim: (n,) + tof_zero_estimate(NX_FLOAT): + exists: optional + unit: NX_TIME + doc: | + The parameter :math:`t_0`, CAnalysis.CCalibMass.fT0Estimate + calibrated_tof(NX_FLOAT): + exists: recommended + doc: | + Calibrated time-of-flight. + dimensions: + rank: 1 + dim: (n,) + mass_to_charge_conversion(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: recommended + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + config(NXparameters): + mass_calibration(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + Mass calibration with unit peaks/interp. as mentioned by `T. Blum et al. + `_ (page 371). + mass_resolution(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + Inverse of the mass resolution :math:`\frac{M}{\Delta M}` as mentioned by `T. Blum et al. `_ (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. + dimensions: + rank: 1 + dim: (m_r,) + mass_resolution_fw(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + 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. + dimensions: + rank: 1 + dim: (m_r,) + mass_resolutionION(NXatom): + nameType: partial + exists: recommended + doc: | + 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. + nuclide_hash(NX_UINT): + exists: recommended + name(NX_CHAR): + mass_to_charge(NX_FLOAT): + dimensions: + rank: 1 + dim: (n,) + reconstruction(NXapm_reconstruction): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: recommended + doc: | + 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. + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + results(NXnote): + exists: recommended + doc: | + 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. + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + config(NXparameters): + exists: recommended + voltage_filter_initial(NX_FLOAT): + exists: recommended + voltage_filter_final(NX_FLOAT): + exists: recommended + protocol_name(NX_CHAR): + exists: recommended + primary_element(NX_CHAR): + exists: recommended + efficiency(NX_FLOAT): + exists: recommended + flight_path(NX_FLOAT): + exists: recommended + evaporation_field(NX_CHAR): + exists: recommended + image_compression(NX_FLOAT): + exists: recommended + kfactor(NX_FLOAT): + exists: recommended + shank_angle(NX_FLOAT): + exists: recommended + ion_volume(NX_FLOAT): + exists: recommended + crystallographic_calibration(NX_CHAR): + exists: recommended + comment(NX_CHAR): + exists: recommended + reconstructed_positions(NX_FLOAT): + dimensions: + rank: 2 + dim: (n, 3) + naive_discretization(NXprocess): + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + (NXdata): + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_UINT): + nameType: partial + title(NX_CHAR): + exists: recommended + intensity(NX_NUMBER): + dimensions: + rank: 3 + dim: (n_z, n_y, n_x) + axis_z(NX_FLOAT): + dimensions: + rank: 1 + dim: (n_z,) + \@long_name(NX_CHAR): + axis_y(NX_FLOAT): + dimensions: + rank: 1 + dim: (n_y,) + \@long_name(NX_CHAR): + axis_x(NX_FLOAT): + dimensions: + rank: 1 + dim: (n_x,) + \@long_name(NX_CHAR): + volume(NX_FLOAT): + exists: recommended + field_of_view(NX_FLOAT): + exists: recommended + ranging(NXapm_ranging): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + source(NXnote): + exists: recommended + doc: | + The respective ranging definitions file RNG/RRNG/ENV/HDF5. + type(NX_CHAR): + exists: recommended + file_name(NX_CHAR): + checksum(NX_CHAR): + exists: recommended + algorithm(NX_CHAR): + exists: recommended + mass_to_charge_distribution(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + min_mass_to_charge(NX_FLOAT): + max_mass_to_charge(NX_FLOAT): + n_mass_to_charge(NX_POSINT): + mass_spectrum(NXdata): + \@signal(NX_CHAR): + \@axes(NX_CHAR): + \@AXISNAME_indices(NX_UINT): + nameType: partial + title(NX_CHAR): + exists: recommended + intensity(NX_NUMBER): + dimensions: + rank: 1 + dim: (n_bins,) + \@long_name(NX_CHAR): + axis_mass_to_charge(NX_FLOAT): + dimensions: + rank: 1 + dim: (n_bins,) + \@long_name(NX_CHAR): + background_quantification(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + background(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + (Out-of-sync, time-independent) background levels in ppm/ns + reported by e.g. APSuite/IVAS for LEAP systems. + mrp_value(NX_FLOAT): + exists: recommended + unit: NX_DIMENSIONLESS + doc: | + The mass-resolving power (MRP) value + + `D. Larson et al. `_ 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. + mrp_mass_to_charge(NX_FLOAT): + exists: recommended + unit: NX_ANY + doc: | + Mass-to-charge state ratio :math:`\frac{m}{n}` at which mrp_value was specified. + mrp_voltage(NX_FLOAT): + exists: recommended + unit: NX_VOLTAGE + doc: | + Potential difference :math:`V` at which mrp_value was specified. + mrp_flight_path_length(NX_FLOAT): + exists: recommended + unit: NX_LENGTH + doc: | + Flight path length :math:`L` at which mrp_value was specified. + peak_search(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + peakID(NXpeak): + exists: ['min', '0', 'max', 'unbounded'] + nameType: partial + label(NX_CHAR): + exists: recommended + description(NX_CHAR): + exists: recommended + category(NX_CHAR): + exists: recommended + doc: | + 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) `_ + 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+}` + enumeration: [0, 1, 2, 3, 4, 5] + position(NX_NUMBER): + + # peak deconvolution(NXprocess): + peak_identification(NXprocess): + exists: recommended + sequence_index(NX_POSINT): + exists: recommended + programID(NXprogram): + exists: ['min', '1', 'max', 'unbounded'] + nameType: partial + program(NX_CHAR): + \@version(NX_CHAR): + number_of_ion_types(NX_UINT): + maximum_number_of_atoms_per_molecular_ion(NX_UINT): + ionID(NXatom): + nameType: partial + exists: ['min', '1', 'max', '256'] + doc: | + 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. + nuclide_hash(NX_UINT): + charge_state(NX_INT): + charge_state_analysis(NXapm_charge_state_analysis): + exists: optional + config(NXparameters): + nuclides(NX_UINT): + mass_to_charge_range(NX_FLOAT): + min_half_life(NX_FLOAT): + min_abundance(NX_FLOAT): + sacrifice_isotopic_uniqueness(NX_BOOLEAN): + charge_state(NX_INT): + nuclide_hash(NX_UINT): + mass(NX_FLOAT): + natural_abundance_product(NX_FLOAT): + shortest_half_life(NX_FLOAT): + mass_to_charge_range(NX_FLOAT): + nuclide_list(NX_UINT): + exists: recommended + name(NX_CHAR): + exists: recommended + iontypes(NX_UINT): + exists: recommended + unit: NX_UNITLESS + doc: | + 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. + dimensions: + rank: 1 + dim: (n,) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 7dc62384d7e42be7e77a61245f222c63c94a65b9e296fd90898b192b722152d0 +# +# +# +# +# +# +# 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/NXactuator.nxdl.xml b/base_classes/NXactuator.nxdl.xml index e0b8907b34..68c87a0e66 100644 --- a/base_classes/NXactuator.nxdl.xml +++ b/base_classes/NXactuator.nxdl.xml @@ -1,4 +1,4 @@ - + + + + + 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/base_classes/NXapm_simulation.nxdl.xml b/base_classes/NXapm_simulation.nxdl.xml new file mode 100644 index 0000000000..cd726f04c7 --- /dev/null +++ b/base_classes/NXapm_simulation.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + Base class for simulation of ion extraction from matter via laser and/or voltage + pulsing. + + + + + + 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/NXcomponent.nxdl.xml b/base_classes/NXcomponent.nxdl.xml index 85ea0f7b81..d94bd41e56 100644 --- a/base_classes/NXcomponent.nxdl.xml +++ b/base_classes/NXcomponent.nxdl.xml @@ -1,4 +1,4 @@ - + + + + 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/NXdata.nxdl.xml b/base_classes/NXdata.nxdl.xml index 826cd29158..8a87f560f3 100644 --- a/base_classes/NXdata.nxdl.xml +++ b/base_classes/NXdata.nxdl.xml @@ -1,4 +1,4 @@ - + + + + + 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/NXfabrication.nxdl.xml b/base_classes/NXfabrication.nxdl.xml index e6a2881e33..d80bfbda1d 100644 --- a/base_classes/NXfabrication.nxdl.xml +++ b/base_classes/NXfabrication.nxdl.xml @@ -1,4 +1,4 @@ - + + + + + + + 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 1cc6c4c5fc..d4c1e2055b 100644 --- a/base_classes/NXlens_em.nxdl.xml +++ b/base_classes/NXlens_em.nxdl.xml @@ -1,4 +1,4 @@ - + + + + Qualitative description of the lens based on the number of pole pieces. + + diff --git a/base_classes/NXprocess.nxdl.xml b/base_classes/NXprocess.nxdl.xml index 39e5da3bf8..8686b8890a 100644 --- a/base_classes/NXprocess.nxdl.xml +++ b/base_classes/NXprocess.nxdl.xml @@ -1,9 +1,9 @@ - + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Base class to describe a software tool or library. + + + + Given name of the program. Program can be a commercial one a script, + or a library or a library component. + + + + Program version plus build number, or commit hash. + + + + + Description of an ideally ever persistent resource where the source code + of the program or this specific compiled version of the program can be + found so that the program yields repeatably exactly the same numerical + and categorical results. + + + + diff --git a/base_classes/NXpump.nxdl.xml b/base_classes/NXpump.nxdl.xml new file mode 100644 index 0000000000..ab79f42be8 --- /dev/null +++ b/base_classes/NXpump.nxdl.xml @@ -0,0 +1,68 @@ + + + + + + Device to reduce an atmosphere to a controlled pressure. + + + + 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. + + + + + + + + + + + diff --git a/base_classes/NXresolution.nxdl.xml b/base_classes/NXresolution.nxdl.xml index e2411b122f..78e0b5490a 100644 --- a/base_classes/NXresolution.nxdl.xml +++ b/base_classes/NXresolution.nxdl.xml @@ -1,4 +1,4 @@ - + + + + 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/NXroot.nxdl.xml b/base_classes/NXroot.nxdl.xml index 3aa87fb025..64e72f055a 100644 --- a/base_classes/NXroot.nxdl.xml +++ b/base_classes/NXroot.nxdl.xml @@ -102,7 +102,7 @@ A list of concepts in an application definition this file describes. This is for partially filling an application definition. If this attribute is not present the application definition is assumed - to be valid, if not only the specified concepts/paths are assumed to be valid. + to be valid, if not only the specified concepts/paths are assumed to be valid. 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/base_classes/nyaml/NXactuator.yaml b/base_classes/nyaml/NXactuator.yaml index bd9f95be57..e587584af8 100644 --- a/base_classes/nyaml/NXactuator.yaml +++ b/base_classes/nyaml/NXactuator.yaml @@ -45,7 +45,7 @@ NXactuator(NXcomponent): # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ # dd10bc8a1c83314427ae289d7c80bc4b53ecfb19d36fc046ef47927b5afa8098 -# +# # # +# +# +# +# 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/nyaml/NXapm_measurement.yaml b/base_classes/nyaml/NXapm_measurement.yaml new file mode 100644 index 0000000000..11f255a755 --- /dev/null +++ b/base_classes/nyaml/NXapm_measurement.yaml @@ -0,0 +1,113 @@ +category: base +doc: | + 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. `_ + * `C. Fleischmann et al. `_ + * `W. Windl et al. `_ + * `C. Freysoldt et al. `_ + * `G. da Costa et al. `_ + + 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. `_ + * `P. Stender et al. `_ + * `I. Dimkou et al. `_ + + to name but a few. +type: group +NXapm_measurement(NXobject): + status(NX_CHAR): + doc: | + A statement whether the measurement completed successfully, or was aborted. + enumeration: [success, aborted] + quality(NX_CHAR): + doc: | + Statement about the quality of the measurement. + + The value can be extracted from the CAnalysis.CResults.fQuality + field of a CamecaRoot ROOT file. + (NXinstrument_apm): + (NXevent_data_apm): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 85fa0cb41b085e4263ca6a0ddab3aff086d8648f508d16664b4ed50d3ac4c93e +# +# +# +# +# +# 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/nyaml/NXapm_ranging.yaml b/base_classes/nyaml/NXapm_ranging.yaml new file mode 100644 index 0000000000..18fd667eef --- /dev/null +++ b/base_classes/nyaml/NXapm_ranging.yaml @@ -0,0 +1,199 @@ +category: base +doc: | + 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 `_ + * `D. Haley et al. `_ + * `M. Kühbach et al. `_ +type: group +NXapm_ranging(NXprocess): + (NXprogram): + (NXnote): + mass_to_charge_distribution(NXprocess): + doc: | + Specifies the mass-to-charge-state ratio histogram. + (NXprogram): + min_mass_to_charge(NX_FLOAT): + unit: NX_ANY + doc: | + 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}]`. + max_mass_to_charge(NX_FLOAT): + unit: NX_ANY + doc: | + 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}]`. + n_mass_to_charge(NX_POSINT): + unit: NX_UNITLESS + doc: | + The number of bins on the interval :math:`[{\frac{m}{q}}_{min}`, + {\frac{m}{q}}_{max}]`. + mass_spectrum(NXdata): + doc: | + A default histogram aka mass spectrum of + the mass-to-charge-state ratio values. + background_quantification(NXprocess): + doc: | + Details of the background model that was used to + correct the total counts per bin into counts. + (NXprogram): + description(NX_CHAR): + doc: | + 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. + peak_search_and_deconvolution(NXprocess): + doc: | + How were peaks in the mass-to-charge-state ratio histogram identified. + (NXprogram): + (NXpeak): + peak_identification(NXprocess): + doc: | + Details about how peaks, with taking into account + error models, were interpreted as ion types or not. + (NXprogram): + number_of_ion_types(NX_UINT): + unit: NX_UNITLESS + doc: | + How many ion types are distinguished. If no ranging was performed, each + ion is of the special unknown type. The iontype ID of this unknown type + is 0 representing a reserved value. + + Consequently, start counting iontypes from 1. + maximum_number_of_atoms_per_molecular_ion(NX_UINT): + unit: NX_UNITLESS + doc: | + Assumed maximum value that suffices to store all relevant molecular ions, + even the most complicated ones that one can typically observe and distinguish + typically. Currently, a value of 32 is used (see M. Kühbach et al. `_). + (NXatom): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# d4359bfc6a6c742eed6c496e3f87022335671b759f6947866bbcc9eda536b579 +# +# +# +# +# +# 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/nyaml/NXapm_reconstruction.yaml b/base_classes/nyaml/NXapm_reconstruction.yaml new file mode 100644 index 0000000000..3472d6d12c --- /dev/null +++ b/base_classes/nyaml/NXapm_reconstruction.yaml @@ -0,0 +1,487 @@ +category: base +doc: | + 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + 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, which must not be confused with the pulse_id! +type: group +NXapm_reconstruction(NXprocess): + (NXprogram): + (NXnote): + + # config + config(NXparameters): + doc: | + 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. + voltage_filter_initial(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Lowest voltage at which an ion that is considered in the reconstructed + volume has been extracted from the specimen. + voltage_filter_final(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Highest voltage at which an ion that is considered in the reconstructed + volume has been extracted from the specimen. + protocol_name(NX_CHAR): + doc: | + Qualitative statement about which reconstruction protocol was used. + + For reconstructions performed with APSuite / IVAS the value "cameca" + should be used. + enumeration: + open_enum: true + items: [bas, geiser, gault, cameca] + primary_element(NX_CHAR): + doc: | + 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. + efficiency(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Assumed detection efficiency + + The value can be extracted from the CAnalysis.CSpatial.fEfficiency + field of a CamecaRoot ROOT file. + flight_path(NX_FLOAT): + unit: NX_LENGTH + doc: | + Nominal flight path + + The value can be extracted from the CAnalysis.CSpatial.fFlightPath + field of a CamecaRoot ROOT file. + evaporation_field(NX_FLOAT): + unit: NX_ANY + doc: | + Assumed evaporation electric field + + The value can be extracted from the CAnalysis.CSpatial.fEvaporationField + field of a CamecaRoot ROOT file. + image_compression(NX_FLOAT): + unit: NX_UNITLESS + doc: | + Image compression factor (ICF) + + The value can be extracted from the CAnalysis.CSpatial.fImageCompression + field of a CamecaRoot ROOT file. + kfactor(NX_FLOAT): + unit: NX_VOLUME + doc: | + Sum of ion volumes + + The value can be extracted from the CAnalysis.CSpatial.fKfactor + field of a CamecaRoot ROOT file. + shank_angle(NX_FLOAT): + unit: NX_ANGLE + doc: | + Shank angle + + The value can be extracted from the CAnalysis.CSpatial.fShankAngle + field of a CamecaRoot ROOT file. + ion_volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Assumed atomic volume + tip_radius(NX_FLOAT): + unit: NX_LENGTH + doc: | + The value can be extracted from the CAnalysis.CSpatial.fTipRadius + field of a CamecaRoot ROOT file. + tip_radius_zero(NX_FLOAT): + unit: NX_LENGTH + doc: | + The value can be extracted from the CAnalysis.CSpatial.fTipRadius0 + field of a CamecaRoot ROOT file. + voltage_zero(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + The value can be extracted from the CAnalysis.CSpatial.fVoltage0 + field of a CamecaRoot ROOT file. + crystallographic_calibration(NX_CHAR): + doc: | + 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. + comment(NX_CHAR): + doc: | + 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. _` + and `T. Blum et al. `_ (page 371). + for best practices on the reporting of metadata in atom probe tomography. + + # results + reconstructed_positions(NX_FLOAT): + unit: NX_LENGTH + doc: | + Three-dimensional positions of the ions in the reconstructed volume. + dimensions: + rank: 2 + dim: (n, 3) + \@depends_on(NX_CHAR): + doc: | + The instance of :ref:`NXcoordinate_system` in which the positions are defined. + + # plots and statistics about the reconstructed volume + naive_discretization(NXprocess): + (NXprogram): + (NXdata): + doc: | + 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. + volume(NX_FLOAT): + unit: NX_VOLUME + doc: | + Sum of ion volumes + + The value can be extracted from the CAnalysis.CSpatial.fRecoVolume + field of a CamecaRoot ROOT file. + field_of_view(NX_FLOAT): + unit: NX_LENGTH + + # typically in nm reconstruction space not detector coordinates + doc: | + 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. + obb(NXcollection): + doc: | + Tight, axis-aligned bounding box about the point cloud of the reconstruction. + xmin(NX_FLOAT): + unit: NX_LENGTH + doc: | + Minimum coordinate value along the x-direction + xmax(NX_FLOAT): + unit: NX_LENGTH + doc: | + Maximum coordinate value along the x-direction + ymin(NX_FLOAT): + unit: NX_LENGTH + doc: | + Minimum coordinate value along the y-direction + ymax(NX_FLOAT): + unit: NX_LENGTH + doc: | + Maximum coordinate value along the y-direction + zmin(NX_FLOAT): + unit: NX_LENGTH + doc: | + Minimum coordinate value along the z-direction + zmax(NX_FLOAT): + unit: NX_LENGTH + doc: | + Maximum coordinate value along the z-direction + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# cb26300799d2708792b9a84040c6b2b80f994eaec0210976a888c5f141df38ff +# +# +# +# +# +# +# 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/base_classes/nyaml/NXapm_simulation.yaml b/base_classes/nyaml/NXapm_simulation.yaml new file mode 100644 index 0000000000..946c069d7d --- /dev/null +++ b/base_classes/nyaml/NXapm_simulation.yaml @@ -0,0 +1,46 @@ +category: base +doc: | + Base class for simulation of ion extraction from matter via laser and/or voltage + pulsing. +type: group +NXapm_simulation(NXobject): + (NXprogram): + (NXparameters): + (NXprocess): + (NXdata): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 091fc2ed9cfe2e0bd98015b42569baa6d6db438f4fafa8fd81cae23cafcbe330 +# +# +# +# +# +# Base class for simulation of ion extraction from matter via laser and/or voltage +# pulsing. +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXatom.yaml b/base_classes/nyaml/NXatom.yaml new file mode 100644 index 0000000000..ce72b8adf8 --- /dev/null +++ b/base_classes/nyaml/NXatom.yaml @@ -0,0 +1,379 @@ +category: base +doc: | + 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_pos: | + Number of atom positions. + d: | + Dimensionality + n_ivec_max: | + Maximum number of atoms/isotopes allowed per ion. + n_ranges: | + Number of mass-to-charge-state-ratio range intervals for ion type. +type: group +NXatom(NXobject): + name(NX_CHAR): + doc: | + 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 +. + id(NX_UINT): + unit: NX_UNITLESS + doc: | + Given numerical identifier for the set. + + The identifier zero is reserved for the special unknown ion type. + identifier_chemical(NX_CHAR): + doc: | + Identifier used to refer to if the set of atoms represents a substance. + enumeration: [inchi] + charge(NX_NUMBER): + unit: NX_CHARGE + doc: | + 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_state(NX_NUMBER): + unit: NX_UNITLESS + doc: | + 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 `_. + volume(NX_NUMBER): + unit: NX_VOLUME + doc: | + 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. + indices(NX_CHAR): + doc: | + Index for each atom at locations as detailed by position. + Indices can be used as identifier and thus names for individual atoms. + dimensions: + rank: 1 + dim: (n_pos,) + type(NX_UINT): + unit: NX_UNITLESS + doc: | + Nuclide information for each atom at locations as detailed by position. + + One `approach `_ for storing nuclide information + efficiently is via individual hash values. + Consult the docstring of ``nuclide_hash`` for further details. + dimensions: + rank: 1 + dim: (n_pos,) + position(NX_NUMBER): + unit: NX_ANY + doc: | + Position of each atom. + dimensions: + rank: 2 + dim: (n_pos, d) + \@reference_frame(NX_CHAR): + doc: | + 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). + occupancy(NX_NUMBER): + unit: NX_DIMENSIONLESS + doc: | + Relative occupancy of the atom position. + + This field is useful for specifying the atomic motif in + instances of :ref:`NXunit_cell`. + dimensions: + rank: 1 + dim: (n_pos,) + nuclide_hash(NX_UINT): + unit: NX_UNITLESS + doc: | + Vector of nuclide hash values. The vector is sorted in decreasing order. + + Individual hash values :math:`H` `encode `_ + 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. + dimensions: + rank: 1 + dim: (n_ivec_max,) + nuclide_list(NX_UINT): + unit: NX_UNITLESS + doc: | + 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. + dimensions: + rank: 2 + dim: (n_ivec_max, 2) + mass_to_charge_range(NX_NUMBER): + unit: NX_ANY + doc: | + 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. + dimensions: + rank: 2 + dim: (n_ranges, 2) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1b11080cf5aae3fd44f2010cbf2e7818a41f9b452dbfcd92396c4ab4fa94ba3d +# +# +# +# +# +# +# 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/nyaml/NXchemical_composition.yaml b/base_classes/nyaml/NXchemical_composition.yaml new file mode 100644 index 0000000000..b2d1882576 --- /dev/null +++ b/base_classes/nyaml/NXchemical_composition.yaml @@ -0,0 +1,153 @@ +category: base +doc: | + Chemical composition of a sample or a set of things. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n: | + The number of samples or things. +type: group +NXchemical_composition(NXobject): + normalization(NX_CHAR): + doc: | + Reporting compositions as atom and weight percent yields both + dimensionless quantities but their conceptual interpretation differs. + A normalization based on atom_percent counts relative to the + total number of atoms 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. + enumeration: [atom_percent, weight_percent] + total(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Total formula mass or number of atoms, depending on the + normalization stated in the normalization field. + dimensions: + rank: 1 + dim: (n,) + ELEMENT(NXatom): + exists: ['min', '1', 'max', 'unbounded'] + nameType: any + doc: | + 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. + amount(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Count or weight which, when divided by total yields the composition + of this element, isotope, molecule, or ion. + dimensions: + rank: 1 + dim: (n,) + composition(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + 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. + composition_errors(NX_FLOAT): + exists: recommended + unit: NX_DIMENSIONLESS + doc: | + Magnitude of the standard deviation of the composition. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 1f60c794061e1a994a90b38b39d3f531a5888cca51f6fc7b7b1ee240e25fc307 +# +# +# +# +# +# +# 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/nyaml/NXcircuit.yaml b/base_classes/nyaml/NXcircuit.yaml new file mode 100644 index 0000000000..edf517d056 --- /dev/null +++ b/base_classes/nyaml/NXcircuit.yaml @@ -0,0 +1,255 @@ +category: base +doc: | + 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. +type: group +NXcircuit(NXcomponent): + hardware(NXfabrication): + doc: | + 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. + components(NX_CHAR): + doc: | + List of components used in the circuit, e.g., resistors, capacitors, transistors or any + other complex components. + connections(NX_CHAR): + doc: | + Description of how components are interconnected, including connection points + and wiring. + power_source(NX_CHAR): + doc: | + Details of the power source for the circuit, including voltage and current + ratings. + signal_type(NX_CHAR): + doc: | + Type of signal (input signal) the circuit is designed to handle, e.g., analog, + digital, mixed-signal. + + # should this be a min / max range? + operating_frequency(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + 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). + bandwidth(NX_NUMBER): + unit: NX_FREQUENCY + doc: | + The bandwidth of the frequency response of the circuit. + + # we may need an NX_RESISTANCE defined + input_impedance(NX_NUMBER): + unit: NX_ANY + doc: | + Input impedance of the circuit. + output_impedance(NX_NUMBER): + unit: NX_ANY + doc: | + Output impedance of the circuit. + gain(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Gain of the circuit, if applicable, usually all instruments have a gain + which might be important or not. + noise_level(NX_NUMBER): + unit: NX_ANY + doc: | + Root-mean-square (RMS) noise level (in current or voltage) + in the circuit in voltage or current. + temperature_range(NX_NUMBER): + unit: NX_ANY + doc: | + Operating temperature range of the circuit. + calibration(NXcalibration): + doc: | + Calibration data for the circuit. + offset(NX_NUMBER): + unit: NX_ANY + doc: | + Offset value for current or voltage. + output_channels(NX_NUMBER): + doc: | + Number of output channels connected to this circuit. Most probably N_channel. + output_signal(NX_NUMBER): + unit: NX_ANY + doc: | + Type of output signal, e.g., voltage, current, digital. + power_consumption(NX_NUMBER): + unit: NX_ANY + doc: | + Power consumption of the circuit per unit time. + status_indicators(NX_CHAR): + doc: | + Status indicators for the circuit, e.g., LEDs, display readouts. + protection_features(NX_CHAR): + doc: | + Protection features built into the circuit, e.g., overvoltage protection, + thermal shutdown. + acquisition_time(NX_NUMBER): + unit: NX_TIME + doc: | + Updated rate for several processes using the input signal, e.g., History Graph, the circuit + uses for any such process. + output_slew_rate(NX_CHAR): + doc: | + The rate at which the signal changes when ramping from the starting + value. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 715173bc6214e78671570370a926d2f7325a8dda2123015cf0d413147e47b417 +# +# +# +# +# +# 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/nyaml/NXcomponent.yaml b/base_classes/nyaml/NXcomponent.yaml index 4738bb9813..d2f635284d 100644 --- a/base_classes/nyaml/NXcomponent.yaml +++ b/base_classes/nyaml/NXcomponent.yaml @@ -55,7 +55,7 @@ NXcomponent(NXobject): # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ # 1e0aeb3958072e69e48c0aaecf3b4867facdf294404855d1568d4eec5ce9e6a7 -# +# # # +# +# +# 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/nyaml/NXcs_filter_boolean_mask.yaml b/base_classes/nyaml/NXcs_filter_boolean_mask.yaml new file mode 100644 index 0000000000..873e3a6f33 --- /dev/null +++ b/base_classes/nyaml/NXcs_filter_boolean_mask.yaml @@ -0,0 +1,136 @@ +category: base +doc: | + 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_objs: | + Number of entries (e.g. number of points or objects). + bitdepth: | + Number of bits assumed for the container datatype used. + n_total: | + Length of mask considering the eventual need for padding. +type: group +NXcs_filter_boolean_mask(NXobject): + depends_on(NX_CHAR): + doc: | + Possibility to refer to which set this mask applies. + + If depends_on is not provided, it is assumed that the mask + applies to its direct parent. + number_of_objects(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of objects represented by the mask. + bitdepth(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of bits assumed matching on a default datatype. + (e.g. 8 bits for a C-style uint8). + mask(NX_UINT): + unit: NX_UNITLESS + doc: | + The content of the mask. If padding is used, + padding bits have to be set to 0. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 3995cd8327636f3badc570bb6935642361b70139dac5f3c16b883e21538a5bc8 +# +# +# +# +# +# +# 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/nyaml/NXcs_memory.yaml b/base_classes/nyaml/NXcs_memory.yaml new file mode 100644 index 0000000000..f4ed105c75 --- /dev/null +++ b/base_classes/nyaml/NXcs_memory.yaml @@ -0,0 +1,68 @@ +category: base +doc: | + Base class for reporting the description of the memory system of a computer. +type: group +NXcs_memory(NXcomponent): + (NXcircuit): + doc: | + Typically, computers have multiple instances of memory. + type(NX_CHAR): + doc: | + Qualifier for the type of random access memory. + enumeration: + open_enum: true + items: [ddr4, ddr5] + max_physical_capacity(NX_POSINT): + unit: NX_ANY + doc: | + Total amount of data which the medium can hold. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 02c8be65151092e9de874ee9a8bc407b53c0f3925f193755b7694d4b3e9934a6 +# +# +# +# +# +# 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/nyaml/NXcs_prng.yaml b/base_classes/nyaml/NXcs_prng.yaml new file mode 100644 index 0000000000..dd10ad12f4 --- /dev/null +++ b/base_classes/nyaml/NXcs_prng.yaml @@ -0,0 +1,134 @@ +category: base +doc: | + Computer science description of pseudo-random number generator. + + The purpose of this base class is to identify if exactly the same sequence can be + reproduced, like for a PRNG or not, like for a true physically random source. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_prng(NXobject): + type(NX_CHAR): + doc: | + Physical approach or algorithm whereby random numbers are generated. + + Different approaches for generating random numbers with a computer exists. + Some use a dedicated physical device whose the state is unpredictable + physically. Some use a strategy of mangling information from the system + clock. Also in this case the sequence is not reproducible without having + additional pieces of information. + + In most cases though so-called pseudo-random number generator (PRNG) + algorithms are used. These yield a deterministic sequence of practically + randomly appearing numbers. These algorithms differ in their quality in + how random the resulting sequences actually are, i.e. sequentially + uncorrelated. Nowadays one of the most commonly used algorithm is the + MersenneTwister (mt19937). + enumeration: [physical, system_clock, mt19937, other] + (NXprogram): + doc: | + Name of the PRNG implementation and version. If such information is not + available or if the PRNG type was set to other the DOI to the publication + or the source code should be given. + seed(NX_INT): + unit: NX_UNITLESS + doc: | + Parameter of the PRNG controlling its initialization + and thus controlling the specific sequence generated. + warmup(NX_UINT): + unit: NX_UNITLESS + doc: | + Number of initial draws from the PRNG after its initialized with the seed. + These initial draws are typically discarded in an effort to equilibrate the + sequence. If no warmup was performed or if warmup procedures are unclear, + users should set the value to zero. + + # one could add spectral properties but this is usually well documented in the PRNG literature + # one could also think about making reference to the NIST PRNG test suite to qualify the PRNG + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 71bcdf7b83514e93216b0edf195944e7a8766346d2d65aac4edd7823439aa944 +# +# +# +# +# +# +# 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/nyaml/NXcs_processor.yaml b/base_classes/nyaml/NXcs_processor.yaml new file mode 100644 index 0000000000..ec982df747 --- /dev/null +++ b/base_classes/nyaml/NXcs_processor.yaml @@ -0,0 +1,97 @@ +category: base +doc: | + 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. +type: group +NXcs_processor(NXcomponent): + (NXcircuit): + doc: | + 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. + type(NX_CHAR): + doc: | + 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 + enumeration: + open_enum: true + items: [pu, cpu, gpu, fpga] + clock_speed(NX_NUMBER): + doc: | + Clock speed of the circuit + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 0c4593244dade75bee8623f85cd3765b001f98d8f35c9f7563f2ad96d615d7b6 +# +# +# +# +# +# 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/nyaml/NXcs_profiling.yaml b/base_classes/nyaml/NXcs_profiling.yaml new file mode 100644 index 0000000000..05e47e8a7c --- /dev/null +++ b/base_classes/nyaml/NXcs_profiling.yaml @@ -0,0 +1,266 @@ +category: base +doc: | + Computer science description for performance and profiling data of an application. + + Performance monitoring and benchmarking of software is a task where questions + can be asked at various levels of detail. In general, there are three main + contributions to performance: + + * Hardware capabilities and configuration + * Software configuration and capabilities + * Dynamic effects of the system in operation and the system working together + with eventually multiple computers, especially when these have to exchange + information across a network and these are used usually by multiple users. + + At the most basic level users may wish to document how long e.g. a data + analysis with a scientific software 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_profiling(NXobject): + + # details about queuing systems etc + current_working_directory(NX_CHAR): + doc: | + Path to the directory from which the tool was called. + command_line_call(NX_CHAR): + doc: | + Command line call with arguments if applicable. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the app was started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the app terminated or crashed. + total_elapsed_time(NX_NUMBER): + unit: NX_TIME + doc: | + Wall-clock time how long the app execution took. This may be in principle + end_time minus start_time; however usage of eventually more precise timers + may warrant to use a finer temporal discretization, + and thus demands a more precise record of the wall-clock time. + max_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + 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. + max_threads(NX_UINT): + unit: NX_UNITLESS + doc: | + 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. + max_gpus(NX_UINT): + unit: NX_UNITLESS + doc: | + The number of nominal GPUs that the app invoked at runtime. + + # there are more complicated usage models, where GPUs are activated in + # between runs etc, but here application definition and base class developers + # should feel free to suggest customizations wrt to if and how such more + # complicated models should be captured. + (NXcs_computer): + doc: | + A collection with one or more computing nodes each with own resources. + This can be as simple as a laptop or the nodes of a cluster computer. + eventID(NXcs_profiling_event): + nameType: partial + doc: | + A collection of individual profiling event data which detail e.g. how + much time the app took for certain computational steps and/or how much + memory was consumed during these operations. + ID is an increasing unsigned integer starting at 1. + + # how to retrieve UUID for cloud computing instances + # https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/identify_ec2_instances.html + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 8f7d0b74d0f964836e56f866e550b56f28e0972dc6914ebec8b7dfe37dd5192f +# +# +# +# +# +# +# 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/nyaml/NXcs_profiling_event.yaml b/base_classes/nyaml/NXcs_profiling_event.yaml new file mode 100644 index 0000000000..33fce1541b --- /dev/null +++ b/base_classes/nyaml/NXcs_profiling_event.yaml @@ -0,0 +1,183 @@ +category: base +doc: | + Computer science description of a profiling event. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + n_processes: | + Number of processes. +type: group +NXcs_profiling_event(NXobject): + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking started. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + included when the event tracking ended. + description(NX_CHAR): + doc: | + Free-text description what was monitored/executed during the event. + elapsed_time(NX_NUMBER): + unit: NX_TIME + doc: | + Wall-clock time how long the event took. + + This may be in principle end_time minus start_time; however usage of + eventually more precise timers may warrant to use a finer temporal + discretization, and thus demand for a more precise record of the + wall-clock time. + + Elapsed time may contain time portions where resources were idling. + max_processes(NX_UINT): + unit: NX_UNITLESS + doc: | + 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. + max_threads(NX_UINT): + unit: NX_UNITLESS + doc: | + 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. + max_gpus(NX_UINT): + unit: NX_UNITLESS + doc: | + The number of nominal GPUs that the app invoked during the execution of this + event. + max_virtual_memory_snapshot(NX_NUMBER): + unit: NX_ANY + doc: | + Maximum amount of virtual memory allocated per process during the event. + dimensions: + rank: 1 + dim: (n_processes,) + max_resident_memory_snapshot(NX_NUMBER): + unit: NX_ANY + doc: | + Maximum amount of resident memory allocated per process during the event. + dimensions: + rank: 1 + dim: (n_processes,) + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 03c76ab650460ab324d251eefa4dfadec0492caba590035735913dfdee451936 +# +# +# +# +# +# +# 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/nyaml/NXcs_storage.yaml b/base_classes/nyaml/NXcs_storage.yaml new file mode 100644 index 0000000000..5de9c67642 --- /dev/null +++ b/base_classes/nyaml/NXcs_storage.yaml @@ -0,0 +1,81 @@ +category: base +doc: | + Base class for reporting the description of the I/O of a computer. +type: group +NXcs_storage(NXcomponent): + (NXcircuit): + type(NX_CHAR): + doc: | + Qualifier for the type of storage medium used. + enumeration: [solid_state_disk, hard_disk, optical, tape] + max_physical_capacity(NX_POSINT): + unit: NX_ANY + doc: | + Total amount of data which the medium can hold. + max_read_rate(NX_NUMBER): + unit: NX_ANY + doc: | + Maximum read rate of the storage medium. + max_write_rate(NX_NUMBER): + unit: NX_ANY + doc: | + Maximum write rate of the storage medium. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 41eb1085ca2b20859fa020679ddb4b6f86456c02e37043c212ce77e036b45c26 +# +# +# +# +# +# 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/nyaml/NXdata.yaml b/base_classes/nyaml/NXdata.yaml index 0af712aa56..e7517d724d 100644 --- a/base_classes/nyaml/NXdata.yaml +++ b/base_classes/nyaml/NXdata.yaml @@ -515,7 +515,7 @@ NXdata(NXobject): # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ # 2aaac78a2fa54b76ecb740cfd6efc667d9c57e9f29428dfb751d195629973972 -# +# # # +# +# +# +# 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/nyaml/NXfabrication.yaml b/base_classes/nyaml/NXfabrication.yaml index 38beefd01e..66519b5986 100644 --- a/base_classes/nyaml/NXfabrication.yaml +++ b/base_classes/nyaml/NXfabrication.yaml @@ -21,14 +21,15 @@ NXfabrication(NXobject): Datetime of component's initial construction. This refers to the date of first measurement after new construction or to the relocation date, if it describes a multicomponent/custom-build setup. - Just the year is often sufficient, but if a full date/time is used, it is recommended to add an explicit time zone. + Just the year is often sufficient, but if a full date/time is used, + it is recommended to add an explicit time zone. capability(NX_CHAR): doc: | Free-text list of functionalities which the component offers. # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ -# 1840d66dce7f8b21036c35ceba7cc1204cef8bd7835d0927187ea9bdf40a1195 -# +# c4957a2c41923bfaf6302a9472209097b8ed7b18531a54c3558c96bb47b24656 +# # # +# +# +# +# +# +# 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/nyaml/NXinstrument_apm.yaml b/base_classes/nyaml/NXinstrument_apm.yaml new file mode 100644 index 0000000000..7142835383 --- /dev/null +++ b/base_classes/nyaml/NXinstrument_apm.yaml @@ -0,0 +1,666 @@ +category: base +doc: | + 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. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + p: | + Number of pulses collected in between start_time and end_time + inside a parent instance of :ref:`NXevent_data_apm`. + +# One could use an NXnote or reference to another NeXus file where these static (meta)data +# are stored but then referencing this in an application definition would demand to make such +# file required, while NXinstrument_apm can be used directly for the static and the dynamic +# or volatile (meta)data. +type: group +NXinstrument_apm(NXinstrument): + type(NX_CHAR): + doc: | + Which type of instrument. + enumeration: + open_enum: true + items: [Inspico, 3DAP, LAWATAP, LEAP 3000 Si, LEAP 3000X Si, LEAP 3000 HR, LEAP 3000X HR, LEAP 4000 Si, LEAP 4000X Si, LEAP 4000 HR, LEAP 4000X HR, LEAP 5000 XS, LEAP 5000 XR, LEAP 5000 R, EIKOS, EIKOS-UV, LEAP 6000 XR, LEAP INVIZO, Photonic AP, TeraSAT, TAPHR, Modular AP, Titanium APT, Extreme UV APT] + fabrication(NXfabrication): + + # (NXcsg): + location(NX_CHAR): + doc: | + Location of the lab or place where the instrument is installed. Using GEOREF is + preferred. + flight_path(NX_FLOAT): + unit: NX_LENGTH + doc: | + Nominal flight path + + The value can be extracted from the CAnalysis.CSpatial.fFlightPath + field of a CamecaRoot ROOT file. + reflectron(NXcomponent): + doc: | + 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 + applied(NX_BOOLEAN): + doc: | + Was the reflectron used? + voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + The maximum voltage applied to the reflectron, relative to system ground. + decelerate_electrode(NXlens_em): + doc: | + A counter electrode of the LEAP 6000 series atom probes. + + # counter_electrodes being optional WO2016171675A1 or Einzel lens + local_electrode(NXlens_em): + doc: | + A local electrode guiding the ion flight path. + Also called counter or extraction electrode. + voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Acceleration voltage + aperture_type(NX_CHAR): + doc: | + 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 + enumeration: [n/a, conical, feedthrough, custom] + ion_detector(NXdetector): + doc: | + Detector for taking raw time-of-flight and ion/hit impact positions data. + signal_amplitude(NX_FLOAT): + unit: NX_CURRENT + doc: | + Amplitude of the signal detected on the multi-channel plate (MCP). + + This field should be used for storing the signal amplitude quantity + within ATO files when the detector was an MCP. + + The ATO file format is used primarily by the atom probe group of the + GPM in Rouen, France. + dimensions: + rank: 1 + dim: (p,) + mcp_efficiency(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + The value can be extracted from the CRunHeader.fMcpEfficiency + field of a CamecaRoot RHIT file. + mesh_efficiency(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + The value can be extracted from the CRunHeader.fMeshEfficiency + field of a CamecaRoot RHIT file. + + # model, serial_number, manufacturer_name all inherited from NXdetector base class + pulser(NXcomponent): + doc: | + 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`. + + # technical design + fabrication(NXfabrication): + pulse_mode(NX_CHAR): + doc: | + Detail whereby ion extraction is triggered methodologically. + enumeration: + open_enum: true + items: [laser, voltage, laser_and_voltage] + pulse_frequency(NX_FLOAT): + unit: NX_FREQUENCY + doc: | + Frequency with which the pulser fire(s). + pulse_fraction(NX_FLOAT): + unit: NX_DIMENSIONLESS + doc: | + Fraction of the pulse_voltage that is applied in addition + to the standing_voltage at peak voltage of a pulse. + + If a standing voltage is applied, this gives nominal pulse fraction + (as a function of standing voltage). Otherwise, this field should + not be present. + + # example of a conditional requirement that can be dealt with rigorously by OWL but not by NeXus! + # as either pulse_voltage is required in an application definition but then that + # existence constraint is independent of other values. + pulse_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Pulsed voltage, in laser pulsing mode this field can be omitted. + pulse_number(NX_UINT): + unit: NX_UNITLESS + doc: | + Absolute number of pulses starting from the beginning of the experiment. + standing_voltage(NX_FLOAT): + unit: NX_VOLTAGE + doc: | + Direct current voltage between the specimen and the (local electrode) in + the case of local electrode atom probe (LEAP) instrument. Otherwise, the + standing voltage applied to the sample, relative to system ground. + sourceID(NXsource): + nameType: partial + doc: | + 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. + wavelength(NX_FLOAT): + unit: NX_WAVELENGTH + doc: | + The wavelength of the radiation emitted by the source. + power(NX_FLOAT): + unit: NX_POWER + doc: | + Nominal power of the laser source while illuminating the specimen. + pulse_energy(NX_FLOAT): + unit: NX_ENERGY + doc: | + Average energy of the laser at peak of each pulse. + \@logged_against(NX_CHAR): + doc: | + Path to pulse_id + beamID(NXbeam): + nameType: partial + doc: | + Details about specific positions along the laser beam + which illuminates the (atom probe) specimen. + incidence_vector(NX_NUMBER): + unit: NX_LENGTH + doc: | + 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. + pinhole_position(NX_NUMBER): + unit: NX_LENGTH + doc: | + Track time-dependent settings over the course of the measurement + where the laser beam exits the focusing optics. + spot_position(NX_NUMBER): + unit: NX_LENGTH + doc: | + Track time-dependent settings over the course of the + measurement where the laser hits the specimen. + (NXtransformations): + doc: | + Affine transformations which describe the geometry how the + laser focusing optics/pinhole-attached coordinate system is + defined, how it has to be transformed so that it aligns with + the specimen coordinate system. + stage(NXmanipulator): + temperature_sensor(NXsensor): + value(NX_FLOAT): + doc: | + The value can be extracted from the CRunHeader.CAnalysis.fSpecimenTemperature + field of a CamecaRoot RHIT file. + + # NEW ISSUE: add NXapm_energy_analyzer, a voltage grid like done in Rouen/GPM + analysis_chamber(NXcomponent): + flight_path(NX_FLOAT): + unit: NX_LENGTH + doc: | + The space inside the atom probe along which ions pass nominally + when they leave the specimen and travel to the detector. + pressure_sensor(NXsensor): + measurement(NX_CHAR): + enumeration: [pressure] + value(NX_FLOAT): + unit: NX_PRESSURE + doc: | + The value can be extracted from the CRunHeader.CLasHeader.fAnalysisPressure + field of a CamecaRoot RHIT file. + buffer_chamber(NXcomponent): + load_lock_chamber(NXcomponent): + getter_pump(NXpump): + roughening_pump(NXpump): + turbomolecular_pump(NXpump): + comment(NX_CHAR): + doc: | + Free-text field for additional comments. + control(NXparameters): + doc: | + Relevant quantities during a measurement with a LEAP system as were + suggested by `T. Blum et al. `_. + evaporation_control(NX_CHAR): + doc: | + Parameter that defines the rules and control loops whereby the pulser and + other components of the instrument are controlled during evaporation. + target_detection_rate(NX_NUMBER): + unit: NX_ANY + doc: | + Parameter that assure maintenance of a significant yet not too high + ion influx on the detector to avoid detection losses. + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# b6183ba0da06e74bcc197f1b73497c25d648d4f7aed36be82e5c2f22f6e4cd26 +# +# +# +# +# +# +# +# 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/nyaml/NXlens_em.yaml b/base_classes/nyaml/NXlens_em.yaml index a28ed94e2b..712c7c01c6 100644 --- a/base_classes/nyaml/NXlens_em.yaml +++ b/base_classes/nyaml/NXlens_em.yaml @@ -73,10 +73,14 @@ NXlens_em(NXcomponent): doc: | Qualitative type of lens with respect to the number of pole pieces. enumeration: [single, double, quadrupole, hexapole, octupole, dodecapole] + number_of_poles(NX_UINT): + unit: NX_UNITLESS + doc: | + Qualitative description of the lens based on the number of pole pieces. # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ -# da0d34149a5d7ee0128593d6cb32345907b6d2d1a556af5dc1c7be7018c7017e -# +# d638ffbb7cda7a9cdc813abe25885bf70722f61be119f8acac32bc9ca9d7d5b9 +# # # +# +# +# +# The symbols used in the schema to specify e.g. dimensions of arrays. +# +# +# +# Base class to describe a software tool or library. +# +# +# +# Given name of the program. Program can be a commercial one a script, +# or a library or a library component. +# +# +# +# Program version plus build number, or commit hash. +# +# +# +# +# Description of an ideally ever persistent resource where the source code +# of the program or this specific compiled version of the program can be +# found so that the program yields repeatably exactly the same numerical +# and categorical results. +# +# +# +# diff --git a/base_classes/nyaml/NXpump.yaml b/base_classes/nyaml/NXpump.yaml new file mode 100644 index 0000000000..44969131bd --- /dev/null +++ b/base_classes/nyaml/NXpump.yaml @@ -0,0 +1,99 @@ +category: base +doc: | + Device to reduce an atmosphere to a controlled pressure. +type: group +NXpump(NXcomponent): + design(NX_CHAR): + doc: | + Principle type of the pump. + enumeration: + open_enum: true + items: [membrane, rotary_vane, roots, turbo_molecular, ion, cryo, diffusion, scroll] + base_pressure(NX_FLOAT): + unit: NX_PRESSURE + doc: | + The minimum pressure achievable in a chamber after + it has been pumped down for an extended period. + medium(NX_CHAR): + doc: | + 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. + enumeration: [vacuum, liquid, gas, slurry, powder] + + # NEW ISSUE: take community input and work further to store what is relevant to report about pumps + # NEW ISSUE: see e.g. https://www.youtube.com/watch?v=Nsr_AdTiIIA for a discussion about + # NEW ISSUE: the role, pros and cons of pump used for atom probe microscopy + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# ce5f2982398390940f305a6ae18a0f5688ea0281f47587d5ba79151460a0d8a4 +# +# +# +# +# +# Device to reduce an atmosphere to a controlled pressure. +# +# +# +# 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. +# +# +# +# +# +# +# +# +# +# +# diff --git a/base_classes/nyaml/NXresolution.yaml b/base_classes/nyaml/NXresolution.yaml index e7a28d4ae6..a2dc0e16db 100644 --- a/base_classes/nyaml/NXresolution.yaml +++ b/base_classes/nyaml/NXresolution.yaml @@ -57,7 +57,7 @@ NXresolution(NXobject): # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ # a8a53adb80c6122d2d1de91a1637430ec6543e9c45319c8edbe931573655e233 -# +# # # +# +# +# 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/nyaml/NXroot.yaml b/base_classes/nyaml/NXroot.yaml index 0dc93b3044..a554d1857b 100644 --- a/base_classes/nyaml/NXroot.yaml +++ b/base_classes/nyaml/NXroot.yaml @@ -205,7 +205,7 @@ NXroot: # A list of concepts in an application definition this file describes. # This is for partially filling an application definition. # If this attribute is not present the application definition is assumed -# to be valid, if not only the specified concepts/paths are assumed to be valid. +# to be valid, if not only the specified concepts/paths are assumed to be valid. # # # diff --git a/base_classes/nyaml/NXspectrum.yaml b/base_classes/nyaml/NXspectrum.yaml new file mode 100644 index 0000000000..78515456a4 --- /dev/null +++ b/base_classes/nyaml/NXspectrum.yaml @@ -0,0 +1,934 @@ +category: base +doc: | + 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. + +# set of frequently made specializations of NXdata instances for spectra +symbols: + n_spc: | + Number of spectra in the stack, for stacks the slowest dimension. + n_k: | + Number of image points along the slower dimension (k equivalent to z). + n_j: | + Number of image points along the slow dimension (j equivalent to y). + n_i: | + Number of image points along the fast dimension (i equivalent to x). + n_energy: | + Number of energy bins (always the fastest dimension). +type: group +NXspectrum(NXobject): + (NXprocess): + doc: | + Details how spectra were processed from the detector readings. + input(NXnote): + doc: | + 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. + context(NX_CHAR): + doc: | + 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. + mode(NX_CHAR): + doc: | + Imaging (data collection) mode of the instrument during acquisition + of the data in this :ref:`NXspectrum` instance. + detector_identifier(NX_CHAR): + doc: | + Link or name of an :ref:`NXdetector` instance with which the data were + collected. + (NXprogram): + spectrum_0d(NXdata): + doc: | + One spectrum for a point of a 0d ROI. Also known as spot measurement. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Counts + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + spectrum_1d(NXdata): + doc: | + One spectrum for each point of a 1d ROI. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 2 + dim: (n_i, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + axis_i(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the fast dimension + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the fast dimension + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + spectrum_2d(NXdata): + doc: | + One spectrum for each scan point of 2d ROI. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 3 + dim: (n_j, n_i, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + axis_j(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slow dimension + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slow dimension + axis_i(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the fast dimension + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the fast dimension + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + spectrum_3d(NXdata): + doc: | + One spectrum for point of a 3d ROI. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 4 + dim: (n_k, n_j, n_i, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + axis_k(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slower dimension + dimensions: + rank: 1 + dim: (n_k,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slower dimension + axis_j(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slow dimension + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slow dimension + axis_i(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the fast dimension + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the fast dimension + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + stack_0d(NXdata): + doc: | + Multiple instances of spectrum_0d. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 2 + dim: (n_spc, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + indices_group(NX_INT): + unit: NX_UNITLESS + doc: | + Group identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Group identifier + indices_spectrum(NX_INT): + unit: NX_UNITLESS + doc: | + Spectrum identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Spectrum identifier + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + stack_2d(NXdata): + doc: | + Multiple instances of spectrum_2d. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 4 + dim: (n_spc, n_j, n_i, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + indices_group(NX_INT): + unit: NX_UNITLESS + doc: | + Group identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Group identifier + indices_spectrum(NX_INT): + unit: NX_UNITLESS + doc: | + Spectrum identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Spectrum identifier + axis_j(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slow dimension + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slow dimension + axis_i(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the fast dimension + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the fast dimension + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + stack_3d(NXdata): + doc: | + Multiple instances of spectrum_3d. + intensity(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Counts + dimensions: + rank: 5 + dim: (n_spc, n_k, n_j, n_i, n_energy) + \@long_name(NX_CHAR): + doc: | + Counts + indices_group(NX_INT): + unit: NX_UNITLESS + doc: | + Group identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Group identifier + indices_spectrum(NX_INT): + unit: NX_UNITLESS + doc: | + Spectrum identifier + dimensions: + rank: 1 + dim: (n_spc,) + \@long_name(NX_CHAR): + doc: | + Spectrum identifier + axis_k(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slower dimension + dimensions: + rank: 1 + dim: (n_k,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slower dimension + axis_j(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the slow dimension + dimensions: + rank: 1 + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the slow dimension + axis_i(NX_NUMBER): + unit: NX_LENGTH + doc: | + Point coordinate along the fast dimension + dimensions: + rank: 1 + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Point coordinate along the fast dimension + axis_energy(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy axis + dimensions: + rank: 1 + dim: (n_energy,) + \@long_name(NX_CHAR): + doc: | + Energy + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 68227c894efa4e970e8826facd84d2676cd89a1a8de369b7af5df2856417c3e6 +# +# +# +# +# +# +# +# +# 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/nyaml/NXunit_cell.yaml b/base_classes/nyaml/NXunit_cell.yaml new file mode 100644 index 0000000000..4fd264906e --- /dev/null +++ b/base_classes/nyaml/NXunit_cell.yaml @@ -0,0 +1,265 @@ +category: base +doc: | + Base class to describe structural aspects of an arrangement of + atoms or ions including a crystallographic unit cell. + + Following recommendations of `CIF `_ and `International Tables of Crystallography `_. +symbols: + d: | + Dimensionality of the lattice. +type: group +NXunit_cell(NXobject): + reference_frame(NX_CHAR): + doc: | + 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(NX_POSINT): + doc: | + Dimensionality of the structure. + enumeration: [1, 2, 3] + a_b_c(NX_NUMBER): + unit: NX_LENGTH + doc: | + Geometry of the unit cell quantified via parameters a, b, and c. + dimensions: + rank: 1 + dim: (d,) + a(NX_NUMBER): + unit: NX_LENGTH + doc: | + Geometry of the unit cell quantified individually via parameter a. + b(NX_NUMBER): + unit: NX_LENGTH + doc: | + Geometry of the unit cell quantified individually via parameter b. + c(NX_NUMBER): + unit: NX_LENGTH + doc: | + Geometry of the unit cell quantified individually via parameter c. + alpha_beta_gamma(NX_NUMBER): + unit: NX_ANGLE + doc: | + Geometry of the unit cell quantified via parameters alpha, beta, and gamma. + dimensions: + rank: 1 + dim: (d,) + alpha(NX_NUMBER): + unit: NX_ANGLE + doc: | + Geometry of the unit cell quantified individually via parameter alpha. + beta(NX_NUMBER): + unit: NX_ANGLE + doc: | + Geometry of the unit cell quantified individually via parameter beta. + gamma(NX_NUMBER): + unit: NX_ANGLE + doc: | + Geometry of the unit cell quantified individually via parameter gamma. + crystal_system(NX_CHAR): + doc: | + 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. + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + laue_group(NX_CHAR): + doc: | + Laue group using International Table of Crystallography notation. + + # add enumeration of all possible ones here to create a closed enum? + point_group(NX_CHAR): + doc: | + Point group using International Table of Crystallography notation. + space_group(NX_CHAR): + doc: | + Space group from the International Table of Crystallography notation. + is_centrosymmetric(NX_BOOLEAN): + doc: | + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + is_chiral(NX_BOOLEAN): + doc: | + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + area(NX_NUMBER): + unit: NX_AREA + doc: | + Area of the unit cell if dimensionality is 2. + volume(NX_NUMBER): + unit: NX_VOLUME + doc: | + Volume of the unit cell if dimensionality is 3. + (NXatom): + +# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ +# 943076968a4dd669b39f03a88e7b9e7e7af13791a6db68f31519a98de9943469 +# +# +# +# +# +# +# +# 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/NXcg_face_list_data_structure.nxdl.xml b/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml index 40c3bdc616..5fcfde6822 100644 --- a/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml +++ b/contributed_definitions/NXcg_face_list_data_structure.nxdl.xml @@ -1,4 +1,4 @@ - +