diff --git a/contributed_definitions/NXcg_primitive_set.nxdl.xml b/contributed_definitions/NXcg_primitive_set.nxdl.xml new file mode 100644 index 0000000000..ac451bdc66 --- /dev/null +++ b/contributed_definitions/NXcg_primitive_set.nxdl.xml @@ -0,0 +1,212 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + The dimensionality of the space. + + + + + The cardinality of the set, i.e. the number of members. + + + + + Computational geometry description of a set of primitives in Euclidean space. + + Primitives must neither be degenerated nor self-intersect. + Individual primitives can differ in their properties (e.g. size, shape, rotation). + + + + + Hint to help resolve in which Euclidean coordinate system field values + like center or orientation are defined. + + + + + The dimensionality of the primitive set. + + + + + + + + + + The cardinality of the primitive set. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + Therefore, implicit identifier are completely defined by the value of + identifier_offset and cardinality. For example if identifier run from + -2 to 3 the value for identifier_offset is -2. + + For explicit indexing the field identifier has to be used. + Fortran-/Matlab- and C-/Python-style indexing have specific implicit + identifier conventions where identifier_offset is 1 and 0 respectively. + + + + + Identifier of each member for explicit indexing. + + + + + + + + The center of mass position of each primitive. + + + + + + + + + + True if the center is a center of mass. + + + + + + + + A qualitative description of the shape of each primitive. + + + + + + + + + Qualifier for the length of characteristic features of the primitive. + + Often the term length is associated with the assumption that one + edge is parallel to an axis of the coordinate system. + + + + + + + + Qualifier often used to describe the length of one characteristic edge + within the coordinate system. + + + + + + + + True if primitive is closed such that it has properties like area or volume. + + + + + + + + Volume of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + + + + + + + + Alias for surface_area of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + + + + + + + + Direction unit vector which points along the + longest principal axis of each primitive. + + Use the depends_on attribute to specify in which coordinate system + these direction unit vectors are defined. + + + + + + + + + + + diff --git a/contributed_definitions/NXcomponent_em.nxdl.xml b/contributed_definitions/NXcomponent_em.nxdl.xml new file mode 100644 index 0000000000..bedba8b6f6 --- /dev/null +++ b/contributed_definitions/NXcomponent_em.nxdl.xml @@ -0,0 +1,69 @@ + + + + + + + Base class for components used in an electron microscope. + + The electron microscope can be a real one or a simulated microscope. + The key motivation behind this generalization is the observation that in all + cases a controlled electron beam is generated in reality or that beam is simulated + and this beam is then used or modified in a controlled manner for the purpose + of studying physical interaction mechanisms of the beam with matter. + Here it does not matter whether one considers a real specimen or a simulated one. + + Using a common description for the real experiment in the lab and - what is + typically a simplification of it - via a computer simulation, has the benefit + that many pieces of information can be stored in the same way. In effect, + users are guided with finding information and unnecessary descriptive + variety for what are exactly the same concept is avoided to work towards + more interoperability. + + Another motivation to make no fundamental distinction between a scanning and + a transmission electron microscope is that both are electron microscopes whose + components are often very similar. + + + + Given name to the component e.g stage, lens C1, etc. + + + + + Ideally, a (globally) unique persistent identifier, link, or text to a + resource which gives further details to this component. + If such resource does not exist, a free-text field to report + further details about the component is possible. + + + + + + + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. + + + diff --git a/contributed_definitions/NXcoordinate_system.nxdl.xml b/contributed_definitions/NXcoordinate_system.nxdl.xml new file mode 100644 index 0000000000..a8dcb83694 --- /dev/null +++ b/contributed_definitions/NXcoordinate_system.nxdl.xml @@ -0,0 +1,143 @@ + + + + + + Base class to detail a coordinate system (CS). + + Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as + a member in an :ref:`NXcoordinate_system_set` and the name of the instance + should be this alias. This may support a process whereby jargon when talking + about coordinate systems and conventions may become cleaner for users + because it is not evident for people outside a lab that terms like e.g. + tip space or specimen space refer to the same coordinate system. + This is an example of jargon used in e.g. the field of atom + probe tomography. + + + + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door-handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. + + + + + + An alternative name given to that coordinate system. + + + + + Coordinate system type. + + + + + + + + Handedness of the coordinate system if it is a Cartesian. + + + + + + + + + Possibility to define an alias for the name of the x-axis. + + + + + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. + + + + + Base unit vector along the first axis which spans the coordinate system. + This axis is frequently referred to as the x-axis in real space and + the i-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the y-axis. + + + + + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the z-axis. + + + + + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. + + + + + + diff --git a/contributed_definitions/NXcrystal_structure.nxdl.xml b/contributed_definitions/NXcrystal_structure.nxdl.xml new file mode 100644 index 0000000000..4baccda138 --- /dev/null +++ b/contributed_definitions/NXcrystal_structure.nxdl.xml @@ -0,0 +1,280 @@ + + + + + + + + + Number of reflectors (Miller crystallographic plane triplets). + + + + + Number of atom positions. + + + + + Dimensionality of the lattice. + + + + + Base class to describe the atomic crystal structure of a phase. + + This base class contains key metadata that are relevant parameter to every + physics-based model to simulate radiation matter interaction. + + Examples where such base class is useful are kinematic or dynamic + diffraction simulations of e.g. (Kikuchi or other type of) patterns. + + + + Detail in which reference frame the unit cell is defined. + + + + + Dimensionality of the lattice. + + + + + + + + + + Reference to another resource that was used for + instantiating this structure model. + + + + + Crystallography unit cell parameters a, b, and c. + + + + + + + + + Crystallography unit cell parameters alpha, beta, and gamma. + + + + + + + + Area of the unit cell considering that d = 2. + + + + + Volume of the unit cell considering that d = 3. + + + + + Crystal system + + + + + + + + + + + + + + + Laue group using International Table of Crystallography Notation. + + + + + + Point group using International Table of Crystallography Notation. + + + + + + Space group from the International Table of Crystallography Notation. + + + + + + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + + + + + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + + + + + Identifier for each phase. + + The value 0 is reserved for the unknown phase that represents the + null-model no sufficiently significant confirmation. In other words, + the phase_name is n/a, notIndexed. + + The phase identifier value has to match with the integer postfix of the + group name which represents that instance in a NeXus/HDF5 file, i.e. + if two phases were used e.g. 0 and 1, two instances of an + :ref:`NXcrystal_structure` named phase0 and phase1 + should be stored in the HDF5 file. + + + + + + Name of the phase/alias. + + If the phase_identifier is 0 and one would like to use the field + phase_name the value should be n/a. + + + + + Label for each atom position. + + + + + + + + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) <https://doi.org/10.1017/S1431927621012241>`_ + + + + + + + + + Atom positions. + + + + + + + + Reference to an instance of :ref:`NXcoordinate_system` + whereby the positions can be resolved. + + + + + + + Relative occupancy of the atom position. + + + + + + + + How many reflectors are distinguished. + + Value has to match value for symbol n_hkl. + + + + + + Miller indices :math:`(hkl)[uvw]` of the planes. + + The first triplet specify :math:`(hkl)` the second triplet :math:`[uvw]`. + Miller indices refer to the Cartesian right-handed coordinate system + of the unit cell. + + + + + + + + + Spacing between crystallographic planes as defined by field miller. + + + + + + + + Relative intensity of the signal for the plane. + + + + + + + + In case the :ref:`NXcrystal_structure` base class is used + with analyzed orientation maps this field stores how many scan points + of the map were identified as that phase. + + + + + + + diff --git a/contributed_definitions/NXcs_cpu_obj.nxdl.xml b/contributed_definitions/NXcs_cpu_obj.nxdl.xml new file mode 100644 index 0000000000..6ce5370a30 --- /dev/null +++ b/contributed_definitions/NXcs_cpu_obj.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a (central) processing unit (C)PU of a computer. + + + + Given name of the CPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_cpu_sys.nxdl.xml b/contributed_definitions/NXcs_cpu_sys.nxdl.xml new file mode 100644 index 0000000000..0de162c661 --- /dev/null +++ b/contributed_definitions/NXcs_cpu_sys.nxdl.xml @@ -0,0 +1,48 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a system of classical central processing units. + + For coprocessor or graphic cards use :ref:`NXcs_gpu_sys` instead. + + + + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single CPU one + could describe using one instance of :ref:`NXcs_cpu_obj` inside one instance of + :ref:`NXcs_cpu_sys`. + A dual-socket server one could describe using two instances of :ref:`NXcs_cpu_obj` + inside one instance of :ref:`NXcs_cpu_sys`. + A server with two dual-socket server nodes one could describe + with the above group of one :ref:`NXcs_cpu_sys` into another :ref:`NXcs_cpu_sys`. + + + diff --git a/contributed_definitions/NXcs_gpu_obj.nxdl.xml b/contributed_definitions/NXcs_gpu_obj.nxdl.xml new file mode 100644 index 0000000000..3c5b6c26ab --- /dev/null +++ b/contributed_definitions/NXcs_gpu_obj.nxdl.xml @@ -0,0 +1,39 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a graphic processing unit (GPU) of a computer. + + + + Given name of the GPU. Users should be as specific as possible. + + + + diff --git a/contributed_definitions/NXcs_gpu_sys.nxdl.xml b/contributed_definitions/NXcs_gpu_sys.nxdl.xml new file mode 100644 index 0000000000..217f1adb2f --- /dev/null +++ b/contributed_definitions/NXcs_gpu_sys.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a system of coprocessor or graphics processors. + + + + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single GPU one + could describe using one instance of :ref:`NXcs_gpu_obj` inside one instance of + :ref:`NXcs_gpu_sys`. + A desktop computer with two GPUs one could describe using two instances + of :ref:`NXcs_gpu_obj` inside one instance of :ref:`NXcs_gpu_sys`. + A GPU server like nowadays used for artificial intelligence + one could describe as a system with n instances of :ref:`NXcs_gpu_obj` + in one :ref:`NXcs_gpu_sys` or :ref:`NXcs_cpu_sys`. + + + diff --git a/contributed_definitions/NXcs_mm_obj.nxdl.xml b/contributed_definitions/NXcs_mm_obj.nxdl.xml new file mode 100644 index 0000000000..e2b247079c --- /dev/null +++ b/contributed_definitions/NXcs_mm_obj.nxdl.xml @@ -0,0 +1,51 @@ + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + Computer science description of a memory in a memory system. + + + + Qualifier for the type of random access memory. + + + + + + Total amount of data which the medium can hold. + + + + + + Given name to the I/O unit. + + + + diff --git a/contributed_definitions/NXem_adf.nxdl.xml b/contributed_definitions/NXem_adf.nxdl.xml new file mode 100644 index 0000000000..64534699cd --- /dev/null +++ b/contributed_definitions/NXem_adf.nxdl.xml @@ -0,0 +1,65 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Base class method-specific for annular dark field imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. + + + + + Annulus inner (first value) and outer (second value) half angle. + + + + + + + + diff --git a/contributed_definitions/NXem_base.nxdl.xml b/contributed_definitions/NXem_base.nxdl.xml new file mode 100644 index 0000000000..479819893b --- /dev/null +++ b/contributed_definitions/NXem_base.nxdl.xml @@ -0,0 +1,389 @@ + + + + + + + + Blue-print of a generic appdef for electron microscopy research formulated as a deep base class. + + This base class combines a method-specific and technical-design-level base class + instance to provide a template for storing parameterized descriptions of + pieces of information collected when performing electron microscopy research. + + The base class here shows all possible branches without making any statements + as to which of these have to be used in an instance. Thereby, the base class + provides a template how to name and structure concepts in a hierarchy + to support finding information and reducing the need for renaming and + restructuring information for a research field where many scientists perform + very specific research but who all also share commonalities like usage of + controlled electron beams, a focus on studies of electron beam matter interaction + to explore physical mechanisms and phenomena, or the desire to characterize materials + using electron microscopy. + + + + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software that writes these :ref:`NXprogram` instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library <https://github.com/FAIRmat-NFDI/pynxtools>`_ + which is used by the `NOMAD <https://nomad-lab.eu/nomad-lab>`_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + + + + + + The configuration of the I/O writer software (e.g. `pynxtools <https://github.com/FAIRmat-NFDI/pynxtools>`_) + which was used to generate this NeXus file instance. + + + + + + An at least as strong as SHA256 hashvalue of the file + which specifies the application definition. + + + + + NeXus NXDL schema to which this file conforms. + + + + + + + + Ideally, a (globally) unique persistent identifier + for referring to this experiment. + + An experiment should be understood in that this can be an experiment + in reality or a computer simulation because also the latter is an + experiment (see the Cambridge Dictionary experiment: + *a test done in order to find out something, eg if an idea is correct*). + + The identifier is usually issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments/simulations to e.g. proposals. + + + + + Free-text description about the experiment. + + Users are strongly advised to parameterize their description of the + experiment by using the respective base classes instead of writing prose + into this field. + + The reason is that such free-text field is difficult to machine-interpret. + The motivation behind keeping this field for now is to learn through + the information entered in this field in how far the current base + classes are incomplete. + + + + + ISO 8601 time code with local time zone offset to UTC information included + when the microscope session started. If the application demands that time + codes in this section of the application definition should only be used + for specifying when the experiment was performed - and the exact + duration is not relevant - this start_time field should be used. + + Often though it is useful to specify a time interval via setting both + a start_time and an end_time because this enables software tools and + users to collect a more detailed bookkeeping of the experiment. + + The user should be aware that even with having both time instances specified, + it may not be possible to infer how long the experiment took or for how + long data were acquired. + + More detailed timing data over the course of the experiment have + to be collected to compute this. These computations can take + advantage of individual time stamps start_time and end_time + in :ref:`NXevent_data_em` instances. + + + + + ISO 8601 time code with local time zone offset to UTC included when + the microscope session ended. See docstring of the start_time field + to see how the start_time and end_time should be used together. + + + + + + The program and eventual software libraries used with which the + NeXus instance was created. For the NOMAD OASIS research data + management system e.g. pynxtools and eventually all modules + if desired. + + + + + + Possibility to store a collection of data artifacts + associated with the experiment. + + + + + + Contact information and eventually details of at least one person + who performed or was involved in the session. This can be the + principle investigator who performed this experiment or the student + who performed the simulation. + Adding multiple users if relevant is recommended. + + + + Given (first) name and surname of the user. + + + + + Name of the affiliation of the user at the point in time + when the experiment was performed. + + + + + Postal address of the affiliation. + + + + + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + + + + + Service as another mean of identification of a user than by the name. + Examples could be details about an ORCID or social media account of + the user. + + + + + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + + + + + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope, student, postdoc, principle investigator, or guest + are common examples. + + + + + + + A description of the material characterized in the experiment. + Sample and specimen are threaded as de facto synonyms. + Samples can be real specimens or virtual (see method). + + + + A qualifier whether the sample is a real one or a + virtual one (in a computer simulation) + + + + + + + + + + Ideally, (globally) unique persistent identifier which distinguishes + the specimen from all others and especially the predecessor/origin + from where the specimen was cut. + + This field must not be used for an alias! Instead, use name. + + In cases where multiple specimens were loaded into the microscope, + the identifier has to resolve the specific sample, whose results are + stored by this :ref:`NXentry` instance, because a single NXentry should be + used only for the characterization of a single specimen. + + Details about the specimen preparation should be + stored in resources referring to parent_identifier. + + + + + Identifier of the sample from which the sample was cut or the string + *None*. The purpose of this field is to support functionalities + for tracking sample provenance via a research data management system. + + + + + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. Ideally, this + matches the last timestamp that is mentioned in the digital resource + pointed to by parent_identifier. + + Knowing when the specimen was exposed to e.g. specific atmosphere is + especially required for environmentally sensitive material such as + hydrogen charged specimens or experiments including tracers with a + short half time. Additional time stamps prior to preparation_date + should better be placed in resources which describe but which do not pollute + the description here with prose. Resolving these connected pieces of information + is considered within the responsibility of the research data management + system. + + + + + An alias used to refer to the specimen to please readability for humans. + + + + + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + `atom_types`. + + The purpose of the field is to offer research data management systems an + opportunity to parse the relevant elements without having to interpret + these from the resources pointed to by parent_identifier or walk through + eventually deeply nested groups in data instances. + + + + + + (Measured) sample thickness. + + The information is recorded to qualify if the beam used was likely + able to shine through the specimen. For scanning electron microscopy, + in many cases the specimen is typically thicker than what is + illuminatable by the electron beam. + + In this case the value should be set to the actual thickness of + the specimen viewed for an illumination situation where the nominal + surface normal of the specimen is parallel to the optical axis. + + + + + + + (Measured) density of the specimen. + + For multi-layered specimens this field should only be used to describe + the density of the excited volume. For scanning electron microscopy + the usage of this field is discouraged and instead an instance of an + :ref:`NXinteraction_vol_em` within individual :ref:`NXevent_data_em` + instances can provide a cleaner description of the relevant details + why one may wish to store the density of the specimen. + + + + + Discouraged free-text field to provide further detail although adding + parent_identifier and having a working research data management system + should provide this contextualization. + + + + + + + + + + + + A region-of-interest analyzed either during or after the session + for which specific processed data generated from the measured or the + simulated data are available. + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_conventions_ebsd.nxdl.xml b/contributed_definitions/NXem_conventions_ebsd.nxdl.xml new file mode 100644 index 0000000000..8a19f1e29b --- /dev/null +++ b/contributed_definitions/NXem_conventions_ebsd.nxdl.xml @@ -0,0 +1,230 @@ + + + + + + + Base class for method-specific conventions EBSD. + + This base class is expected to be used with :ref:`NXem_conventions`. + + This is the main issue which currently is not in all cases documented + and thus limits the interoperability and value of collected EBSD data. + Not communicating EBSD data with such contextual pieces of information + and the use of file formats which do not store this information is the + key unsolved problem. + + + + Details about the gnomonic projection reference frame. + + + + Type of coordinate system/reference frame used for identifying + positions in the gnomonic projection space Xg, Yg, Zg + according to DOI: 10.1016/j.matchar.2016.04.008. + + + + + + + + + Handedness of coordinate system. + + + + + + + + + Is the origin of the gnomonic coordinate system located + where we assume the location of the pattern centre. + This is the location Xg = 0, Yg = 0, Zg = 0 according to + reference DOI: 10.1016/j.matchar.2016.04.008. + + + + + + + + + Direction of the positively pointing "gnomomic" x-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + + + + + + + + + + + + + + Direction of the positively pointing "gnomomic" y-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + Direction of the positively pointing "gnomomic" z-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + + + + + + + + + + + + + + + Details about the definition of the pattern centre + as a special point in the gnomonic projection reference frame. + + + + From which border of the EBSP (in the detector reference frame) + is the pattern centre's x-position (PCx) measured? + Keywords assume the region-of-interest is defined by + a rectangle. We observe this rectangle and inspect the + direction of the outer-unit normals to the edges of + this rectangle. + + + + + + + + + + + + In which direction are positive values for PCx measured from + the specified boundary. Keep in mind that the gnomonic space + is in virtually all cases embedded in the detector space. + Specifically, the XgYg plane is defined such that it is + embedded/laying inside the XdYd plane (of the detector + reference frame). + When the normalization direction is the same as e.g. the + detector x-axis direction, we state that we effectively + normalize in fractions of the width of the detector. + + The issue with terms like width and height is that these + degenerate if the detector region-of-interest is square-shaped. + This is why we should better avoid talking about width and height but + state how we would measure distances practically with a ruler and + how we then measure positive distances. + + + + + + + + + + + + From which border of the EBSP (in the detector reference + frame) is the pattern centre's y-position (PCy) measured? + For further details inspect the help button of + xaxis_boundary_convention. + + + + + + + + + + + + In which direction are positive values for PCy measured from + the specified boundary. + For further details inspect the help button of + xaxis_normalization_direction. + + + + + + + + + + + + diff --git a/contributed_definitions/NXem_correlation.nxdl.xml b/contributed_definitions/NXem_correlation.nxdl.xml new file mode 100644 index 0000000000..58c0f68255 --- /dev/null +++ b/contributed_definitions/NXem_correlation.nxdl.xml @@ -0,0 +1,245 @@ + + + + + + Base class to combine different method-specific data in electron microscopy. + + This base class represent a template for documenting correlations + (spatial, temporal) between different method-specific results. + + + + Details about processing steps. + + + + + + Details about correlated or logically connected EBSD datasets. + + One important class of such correlated experiments are the so-called + (quasi) in-situ experiments. In this case the same or nearly the same ROI + gets analyzed via a repetitive sequence of thermomechanical treatment, + sample preparation, measurement, on-the-fly-indexing. Phenomena + investigated are recrystallization, strain accumulation, material damage. + Post-processing is required to correlate and reidentify eventual + microstructural features or local ROIs across several orientation maps. + + Another important class of correlated experiments are the so-called + serial-sectioning experiments. Here the same sample is measured + repetitively after polishing each time, to create a stack of + orientation data which can be reconstructed to a + three-dimensional volume ROI. + + Data can be correlated in time, position (spatial), or both (spatiotemporal). + + Spatial correlations between repetitively characterized regions-of-interests + are typically correlated using image registration and alignment algorithms. + For this typically so-called landmarks are used. These can be grains with + a very large size or specific shape, i.e. grains which are qualitatively + different enough to be used as a guide how images are shifted relative to + one another. Other commonly used landmarks are fiducial marks which are + milled into the specimen surface using focus-ion beam milling and/or various + types of indentation methods. + + As far as the same physical region-of-interest is just measured several times, + the additional issue of the depth increment is not a concern. However, correct + assumptions for the depth increment, amount of material removed along the milling + direction is relevant for accurate and precise three-dimensional (serial-sectioning) + correlations. For these studies it can be tricky though to assume or estimate + useful depth increments. Different strategies have been proposed like + calibrations, wedged-shaped landmarks and computer simulation assisted + assumption making. + + Despite the use of landmarks, there are many practical issues which make the + processing of correlations imprecise and inaccurate. Among these are drift + and shift of the specimen, instabilities of the holder, the beam, irrespective + of the source of the drift, charging effects, here specifically causing local + image distortions and rotations which may require special processing algorithms + to reduce such imprecisions. + + Time correlations face all of the above-mentioned issues surplus the challenge + that specific experimental protocols have to be used to ensure the material state + is observed at specific physical time. The example of quasi in-situ characterization + of crystal growth phenomena, a common topic in engineering or modern catalysis research + makes it necessary to consider that e.g. the target value for the desired annealing + temperature is not just gauged based on macroscopic arguments but considers + that transient effects take place. Heating or quenching a sample might thus might + not have been executed under conditions in the interaction volume as they are + documented and/or assumed. + + These issue cause that correlations have an error margin as to how accurately + respective datasets were not only just synced based on the geometry of the + region-of-interests and the time markers but also to asssure which physical + conditions the specimen experienced over the course of the measurements. + + The fourth example of the em_om reference implementation explores the use of the + correlation group with a serial-sectioning datasets that was collected by the + classical Inconel 100 dataset collected by M. D. Uchic and colleagues + (M. Groeber M, Haley BK, Uchic MD, Dimiduk DM, Ghosh S 3d reconstruction and + characterization of polycrystalline microstructures using a fib-sem system data set. + Mater Charac 2006, 57 259–273. 10.1016/j.matchar.2006.01.019M). + + This dataset was specifically relevant in driving forward the implementation + of the DREAM.3D software. DREAM.3D is an open-source software project for + post-processing and reconstructing, i.e. correlating sets of orientation + microscopy data foremost spatially. One focus of the software is the + (post-)processing of EBSD datasets. Another cutting edge tool with similar + scope but a commercial solution by Bruker is QUBE which was developed by + P. Konijnenberg and coworkers. + + Conceptually, software like DREAM.3D supports users with creating linear + workflows of post-processing tasks. Workflows can be instructed via the + graphical user interface or via so-called pipeline processing via command line + calls. DREAM.3D is especially useful because its internal system documents all + input, output, and parameter of the processing steps. This makes DREAM.3D a + good candidate to interface with tools like em_om parser. Specifically, DREAM.3D + documents numerical results via a customized HDF5 file format called DREAM3D. + Workflow steps and settings are stored as nested dictionaries in JSON syntax + inside a supplementary JSON file or alongside the data in the DREAM3D file. + DREAM.3D has a few hundred algorithms implemented. These are called filters + in DREAM.3D terminology. + + Users configure a workflow which instructs DREAM.3D to send the data through + a chain of predefined and configured filters. Given that for each analysis + the filter is documented via its version tags surplus its parameter and setting + via a controlled vocabulary, interpreting the content of a DREAM3D HDF5 file + is possible in an automated manner using a parser. This makes DREAM.3D analyses + repeatable and self-descriptive. A key limitation though is that most frequently + the initial set of input data come from commercial files like ANG. + This missing link between the provenance of these input files, their associated + creation as electron microscope session, is also what NXem_ebsd solves. + + Nevertheless, as this can be solved with e.g. NXem_ebsd we are convinced that + the DREAM.3D and the em_om parser can work productively together to realize + RDMS-agnostic parsing of serial-section analyses. + + The internal documentation of the DREAM.3D workflow also simplifies the + provenance tracking represented by an instance of NXem_ebsd as not every + intermediate results has to be stored. Therefore, the fourth example + focuses on the key result obtained from DREAM.3D - the reconstructed + and aligned three-dimensional orientation map. + + Usually, this result is the starting point for further post-processing + and characterization of structural features. As here orientation microscopy + is insofar scale invariant using DREAM.3D, NXem_ebsd, and em_om should + be useful for different characterization methods, such as EBSD, Transmission + Kikuchi Diffraction (TKD), Automated Crystal Orientation Mapping (ACOM), + Nanobeam Electron Diffraction (using commercial systems like NanoMegas ASTAR) + or open-source implementations of these techniques (such as via pyxem/orix). + + The result of orientation microscopy methods are maps of local orientation + and thermodynamic phase (crystal structure) pieces of information. Virtually + all post-processing of such results for structural features includes again + a workflow of steps which are covered though by the NXms partner application + definition. The respective source of the data in an instance of NXms can + again be a link or reference to an instance of NXem_ebsd to complete the + chain of provenance. + + + + + + Descriptor representing the image contrast. + + + + + + Title of the default plot. + + + + + Descriptor values displaying the ROI. + + + + + + + + + + Descriptor values. + + + + + + Calibrated coordinate along the z-axis. + + + + + + + Label for the z axis + + + + + + Calibrated coordinate along the y-axis. + + + + + + + Label for the y axis + + + + + + Calibrated coordinate along the x-axis. + + + + + + + Label for the x axis + + + + + + + diff --git a/contributed_definitions/NXem_ebsd_conventions.nxdl.xml b/contributed_definitions/NXem_ebsd_conventions.nxdl.xml deleted file mode 100644 index 7ef85f8716..0000000000 --- a/contributed_definitions/NXem_ebsd_conventions.nxdl.xml +++ /dev/null @@ -1,610 +0,0 @@ - - - - - - - Conventions for rotations and coordinate systems to interpret EBSD data. - - This is the main issue which currently is not in all cases documented - and thus limits the interoperability and value of collected EBSD data. - Not communicating EBSD data with such contextual pieces of information - and the use of file formats which do not store this information is the - key unsolved problem. - - - - - Mathematical conventions and materials-science-specific conventions - required for interpreting every collection of orientation data. - - - - Convention how a positive rotation angle is defined when viewing - from the end of the rotation unit vector towards its origin, - i.e. in accordance with convention 2 of - DOI: 10.1088/0965-0393/23/8/083501. - Counter_clockwise is equivalent to a right-handed choice. - Clockwise is equivalent to a left-handed choice. - - - - - - - - - - How are rotations interpreted into an orientation - according to convention 3 of - DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - - How are Euler angles interpreted given that there are several - choices (e.g. ZXZ, XYZ, etc.) according to convention 4 of - DOI: 10.1088/0965-0393/23/8/083501. - The most frequently used convention is ZXZ which is based on - the work of H.-J. Bunge but other conventions are possible. - - - - - - - - - To which angular range is the rotation angle argument of an - axis-angle pair parameterization constrained according to - convention 5 of DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - Which sign convention is followed when converting orientations - between different parameterizations/representations according - to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - - - Details about eventually relevant named directions that may - give reasons for anisotropies. The classical example is cold-rolling - where one has to specify which directions (rolling, transverse, and normal) - align how with the direction of the base vectors of the sample_reference_frame. - - - - Type of coordinate system and reference frame according to - convention 1 of DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - - Direction of the positively pointing x-axis base vector of - the processing_reference_frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. - - - - - - - - - - - - - - Name or alias assigned to the x-axis base vector, e.g. rolling direction. - - - - - Direction of the positively pointing y-axis base vector of - the processing_reference_frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. For further information consult - also the help info for the xaxis_direction field. - - - - - - - - - - - - - - Name or alias assigned to the y-axis base vector, e.g. transverse direction. - - - - - Direction of the positively pointing z-axis base vector of - the processing_reference frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. For further information consult - also the help info for the xaxis_direction field. - - - - - - - - - - - - - - Name or alias assigned to the z-axis base vector, e.g. normal direction. - - - - - Location of the origin of the processing_reference_frame. - This specifies the location Xp = 0, Yp = 0, Zp = 0. - Assume regions-of-interest in this reference frame form a - rectangle or cuboid. - Edges are interpreted by inspecting the direction of their - outer unit normals (which point either parallel or antiparallel) - along respective base vector direction of the reference frame. - - - - - - - - - - - - - - - - - Details about the sample/specimen reference frame. - - - - Type of coordinate system and reference frame according to - convention 1 of DOI: 10.1088/0965-0393/23/8/083501. - The reference frame for the sample surface reference is used for - identifying positions on a (virtual) image which is formed by - information collected from an electron beam scanning the - sample surface. We assume the configuration is inspected by - looking towards the sample surface from a position that is - located behind the detector. - Reference DOI: 10.1016/j.matchar.2016.04.008 - The sample surface reference frame has coordinates Xs, Ys, Zs. - In three dimensions these coordinates are not necessarily - located on the surface of the sample as there are multiple - faces/sides of the sample. Most frequently though the coordinate - system here is used to define the surface which the electron - beam scans. - - - - - - - - - - Direction of the positively pointing x-axis base vector of - the sample surface reference frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. - Different tools assume that different strategies can be used - and are perceived as differently convenient to enter - details about coordinate system definitions. In this ELN users - have to possibility to fill in what they assume is sufficient to - define the coordinate system directions unambiguously. - Software which works with this user input needs to offer parsing - capabilities which detect conflicting input and warn accordingly. - - - - - - - - - - - - - - Direction of the positively pointing y-axis base vector of - the sample surface reference frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. For further information consult - also the help info for the xaxis_direction field. - - - - - - - - - - - - - - Direction of the positively pointing z-axis base vector of - the sample surface reference frame. We assume the configuration - is inspected by looking towards the sample surface from a position - that is located behind the detector. For further information consult - also the help info for the xaxis_direction field. - - - - - - - - - - - - - - Location of the origin of the sample surface reference frame. - This specifies the location Xs = 0, Ys = 0, Zs = 0. - Assume regions-of-interest in this reference frame form a - rectangle or cuboid. - Edges are interpreted by inspecting the direction of their - outer unit normals (which point either parallel or antiparallel) - along respective base vector direction of the reference frame. - - - - - - - - - - - - - - - - - Details about the detector reference frame. - - - - Type of coordinate system/reference frame used for - identifying positions in detector space Xd, Yd, Zd, - according to DOI: 10.1016/j.matchar.2016.04.008. - - - - - - - - - - Direction of the positively pointing x-axis base vector of - the detector space reference frame. We assume the configuration - is inspected by looking towards the sample surface from a - position that is located behind the detector. - Different tools assume that different strategies can be used - and are perceived as differently convenient to enter - details about coordinate system definitions. In this ELN users - have to possibility to fill in what they assume is sufficient to - define the coordinate system directions unambiguously. - Software which works with this user input needs to offer parsing - capabilities which detect conflicting input and warn accordingly. - - - - - - - - - - - - - - Direction of the positively pointing y-axis base vector of - the detector space reference frame. We assume the configuration - is inspected by looking towards the sample surface from a - position that is located behind the detector. - For further information consult also the help info for the - xaxis_direction field. - - - - - - - - - - - - - - Direction of the positively pointing z-axis base vector of - the detector space reference frame. We assume the configuration - is inspected by looking towards the sample surface from a - position that is located behind the detector. - For further information consult also the help info for the - xaxis_direction field. - - - - - - - - - - - - - - Where is the origin of the detector space reference - frame located. This is the location of Xd = 0, Yd = 0, Zd = 0. - Assume regions-of-interest in this reference frame form a - rectangle or cuboid. - Edges are interpreted by inspecting the direction of their - outer unit normals (which point either parallel or antiparallel) - along respective base vector direction of the reference frame. - - - - - - - - - - - - - - - - - Details about the gnomonic projection reference frame. - - - - Type of coordinate system/reference frame used for identifying - positions in the gnomonic projection space Xg, Yg, Zg - according to DOI: 10.1016/j.matchar.2016.04.008. - - - - - - - - - - Direction of the positively pointing "gnomomic" x-axis base - vector when viewing how the diffraction pattern looks on the - detector screen. We assume the configuration is inspected by - looking towards the sample surface from a position - that is located behind the detector. - Different tools assume that different strategies can be used - and are perceived as differently convenient to enter - details about coordinate system definitions. In this ELN users - have to possibility to fill in what they assume is sufficient to - define the coordinate system directions unambiguously. - Software which works with this user input needs to offer parsing - capabilities which detect conflicting input and warn accordingly. - - - - - - - - - - - - - - Direction of the positively pointing "gnomomic" y-axis base - vector when viewing how the diffraction pattern looks on the - detector screen. We assume the configuration is inspected by - looking towards the sample surface from a position - that is located behind the detector. - For further information consult also the help info for the - xaxis_direction field. - - - - - - - - - - - - - - Direction of the positively pointing "gnomomic" z-axis base - vector when viewing how the diffraction pattern looks on the - detector screen. We assume the configuration is inspected by - looking towards the sample surface from a position - that is located behind the detector. - For further information consult also the help info for the - xaxis_direction field. - - - - - - - - - - - - - - Is the origin of the gnomonic coordinate system located - where we assume the location of the pattern centre. - This is the location Xg = 0, Yg = 0, Zg = 0 according to - reference DOI: 10.1016/j.matchar.2016.04.008. - - - - - - - - - - Details about the definition of the pattern centre - as a special point in the gnomonic projection reference frame. - - - - From which border of the EBSP (in the detector reference frame) - is the pattern centre's x-position (PCx) measured? - Keywords assume the region-of-interest is defined by - a rectangle. We observe this rectangle and inspect the - direction of the outer-unit normals to the edges of - this rectangle. - - - - - - - - - - - - In which direction are positive values for PCx measured from - the specified boundary. Keep in mind that the gnomonic space - is in virtually all cases embedded in the detector space. - Specifically, the XgYg plane is defined such that it is - embedded/laying inside the XdYd plane (of the detector - reference frame). - When the normalization direction is the same as e.g. the - detector x-axis direction, we state that we effectively - normalize in fractions of the width of the detector. - - The issue with terms like width and height is that these - degenerate if the detector region-of-interest is square-shaped. - This is why we should better avoid talking about width and height but - state how we would measure distances practically with a ruler and - how we then measure positive distances. - - - - - - - - - - - - From which border of the EBSP (in the detector reference - frame) is the pattern centre's y-position (PCy) measured? - For further details inspect the help button of - xaxis_boundary_convention. - - - - - - - - - - - - In which direction are positive values for PCy measured from - the specified boundary. - For further details inspect the help button of - xaxis_normalization_direction. - - - - - - - - - - - - diff --git a/contributed_definitions/NXem_eds.nxdl.xml b/contributed_definitions/NXem_eds.nxdl.xml new file mode 100644 index 0000000000..735bfe8979 --- /dev/null +++ b/contributed_definitions/NXem_eds.nxdl.xml @@ -0,0 +1,144 @@ + + + + + + + + + + Number of pixel along the y direction, the slow direction + + + + + Number of pixel along the x direction, the fast direction + + + + + Number of X-ray photon energy (bins), the fastest direction. + + + + + Number of identified elements + + + + + Number of peaks detected + + + + + Base class method-specific for energy-dispersive X-ray spectroscopy (EDS/EDX). + + `IUPAC instead of Siegbahn notation <https://doi.org/10.1002/xrs.1300200308>`_ should be used. + + + + + Details about computational steps how peaks were indexed as elements. + + + + The program with which the indexing was performed. + + + + + Name and location of each X-ray line which was indexed as a known ion. + For each ion, an NXion instance should be created which specifies + the origin of the signal. For each ion also the relevant IUPAC notation + X-ray lines should be specified. + + + + + Associated lower :math:`[e_{min}, e_{max}]` bounds of the + energy which is assumed associated with this peak. + + + + + + + + Theoretical energy of the line according to IUPAC. + + + + + IUPAC notation identifier of the line which the peak represents. + + This can be a list of IUPAC notations for (the seldom) case that + multiple lines are grouped with the same peak. + + + + + + + + + + List of the names of identified elements. + + + + + + + + Individual element-specific EDS/EDX/EDXS/SXES mapping + + A composition map is an image whose intensities for each pixel are the + accumulated X-ray quanta *under the curve(s)* of a set of peaks. + + These element-specific EDS maps are NXimage_r_set instances + and need to be named with the name of the element from the + element_names field. + + + + + A list of NXpeak instance names whose X-ray quanta + where accumulated for each pixel which yields an element-specific + EDS map. + + + + + + + + + + diff --git a/contributed_definitions/NXem_eels.nxdl.xml b/contributed_definitions/NXem_eels.nxdl.xml new file mode 100644 index 0000000000..c355f6fd62 --- /dev/null +++ b/contributed_definitions/NXem_eels.nxdl.xml @@ -0,0 +1,79 @@ + + + + + + + + Number of electron energy loss bins. + + + + + Base class method-specific for Electron Energy Loss Spectroscopy (EELS). + + + + + NXspectrum_set_em specialized for EELS. + + + + + + + + + + Energy loss. + + + + + + + + + Energy loss. + + + + + + + Energy loss. + + + + + + + diff --git a/contributed_definitions/NXem_img.nxdl.xml b/contributed_definitions/NXem_img.nxdl.xml new file mode 100644 index 0000000000..ebf17380a6 --- /dev/null +++ b/contributed_definitions/NXem_img.nxdl.xml @@ -0,0 +1,63 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Base class for method-specific generic imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. + + + + Which imaging mode was used? + + + + + + + + diff --git a/contributed_definitions/NXem_method.nxdl.xml b/contributed_definitions/NXem_method.nxdl.xml new file mode 100644 index 0000000000..086d4833d2 --- /dev/null +++ b/contributed_definitions/NXem_method.nxdl.xml @@ -0,0 +1,47 @@ + + + + + + + Base class to describe specific analysis methods in electron microscopy. + + This base class represent a template how specialized, deep, and method-specific + base classes can be defined with which an (NXem) application + definition gets equipped with specific groups to document method-specific + processing steps and report analyzed quantities. + + The template base class name :ref:`NXem_method` needs to be changed for each + method e.g. :ref:`NXem_adf`, :ref:`NXem_ebsd`, :ref:`NXem_eels`, :ref:`NXem_eds`. + + + + Details about processing steps. + + + + + + + diff --git a/contributed_definitions/NXem_msr.nxdl.xml b/contributed_definitions/NXem_msr.nxdl.xml new file mode 100644 index 0000000000..a6442b1e2e --- /dev/null +++ b/contributed_definitions/NXem_msr.nxdl.xml @@ -0,0 +1,96 @@ + + + + + + Base class for collecting a session with a real electron microscope. + + For collecting data and experiments which are simulations of an + electron microscope use the :ref:`NXem_sim` base class. + + + + (Meta)data of the microscope and the lab in which it stands. + + This em_lab group differs from potential em_lab groups inside + :ref:`NXevent_data_em` instances in that here the more static descriptions + are kept while changing, i.e. time-dependent pieces of information are + logged, via the em_lab group inside the desired number of instances + of NXevent_data_em. + + While using an :ref:`NXevent_data_em` instance, users should store only those + settings about a component which are relevant to understand the current + state of the component. Here, current means for the time interval which + the event covers (as it is detailed via start_time and end_time) timestamps. + + For example it is not relevant to store in each :ref:`NXevent_data_em` + electron_source group again the details of the gun type and the manufacturer + but only the high-voltage value and that only if it is different from the value + that is specified in the em_lab section for the static settings. + + In effect, this defines an information inference hierarchy which starts + in an individual :ref:`NXevent_data_em` instance followed by a probing of the + static section. + + + + Given name of the microscope at the hosting institution. + This is an alias. Examples could be NionHermes, Titan, JEOL, + Gemini, etc. + + + + + Location of the lab or place where the instrument is installed. + Using GEOREF is preferred. + + + + + + + + + + Description of the type of the detector. + + Electron microscopes have typically multiple detectors. + Different technologies are in use like CCD, scintillator, + direct electron, CMOS, or image plate to name but a few. + + + + Instrument-specific alias/name + + + + + + + + + + diff --git a/contributed_definitions/NXem_sim.nxdl.xml b/contributed_definitions/NXem_sim.nxdl.xml new file mode 100644 index 0000000000..f5f10b1b95 --- /dev/null +++ b/contributed_definitions/NXem_sim.nxdl.xml @@ -0,0 +1,60 @@ + + + + + + + Base class for simulating electron microscopy relevant beam-matter interaction. + + The concept behind this base class is to keep it as generic as possible + that simulations of electron/ion beam interaction with matter can be + represented. This base class is envisioned as the twin of the :ref:`NXem_msr` + base class. + + It is an attempt to test the idea if at some point one might even use the + same base class template to describe measurements and computer simulations + of electron microscopy. This idea is attractive because the only practical + difference between a description of a measurement with a microscope and a + computer simulation is that the latter is typically a substantially simplified + representation of the real microscope surplus the focus of the research + in such cases on specific questions. + + Such simplification can be with respect to the optical setup, typically the + ignoring of the fact that the electron beam is produced by a complex setup + of lenses while in simulations often single Einzel lenses are considered. + Dynamics of the environment like temperature fluctuation in a lab, vibrations, + users, and multiple detectors are typically either ignored or reduced in + complexity and number and coming with idealizations to keep the simulations + focused on the specific reason questions and efficiently numerically executable. + + + + Details about the simulation. + + + + + + + diff --git a/contributed_definitions/NXimage_c_set.nxdl.xml b/contributed_definitions/NXimage_c_set.nxdl.xml new file mode 100644 index 0000000000..64c945c99e --- /dev/null +++ b/contributed_definitions/NXimage_c_set.nxdl.xml @@ -0,0 +1,247 @@ + + + + + + + + Number of images in the (hyper)stack. + + + + + Number of pixel per image in the slowest direction. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Specialized base class container for reporting a set of images in reciprocal space. + + In practice, complex numbers are encoded via some formatted pair of real values. + Typically, fast Algorithms for computing Fourier Transformations (FFT) are + used to encode images in reciprocal (frequency) space. FFT libraries are used + for implementing the key functionalities of these mathematical operations. + + Different libraries use different representations and encoding of the + image computed. Details can be found in the respective sections of the + typical FFT libraries: + + * `FFTW by M. Frigo and S. G. Johnson <https://www.fftw.org/fftw3_doc/Tutorial.html#Tutorial>`_ + * `Intel MKL by the Intel Co. <https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2023-0/fourier-transform-functions.html>`_ + * `cuFFT by the NVidia Co. <https://docs.nvidia.com/cuda/cufft/index.html>`_ + + Users are strongly advised to inspect carefully which specific conventions + their library uses to be able to store and modify the implementation of their + code so that the serialized representations as it is detailed + here for NeXus matches with their intention. + + One- and two-dimensional FFTs should use the stack(NXdata) instances. + Three-dimensional FFTs should use the hyperstack(NXdata) instances. + + + + + Image stack. + + + + Image intensity of the real part. + + + + + + + + + + Image intensity of the imaginary part. + + + + + + + + + + Magnitude of the image intensity. + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + + Pixel coordinate center along j direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along i direction. + + + + + + + Coordinate along i direction. + + + + + + + Image hyperstack. + + + + Image intensity of the real part. + + + + + + + + + + + Image intensity of the imaginary part. + + + + + + + + + + + Magnitude of the image intensity. + + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + Pixel coordinate center along k direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along j direction. + + + + + + + Coordinate along j direction. + + + + + + Pixel coordinate center along i direction. + + + + + + + Coordinate along i direction. + + + + + diff --git a/contributed_definitions/NXimage_r_set.nxdl.xml b/contributed_definitions/NXimage_r_set.nxdl.xml new file mode 100644 index 0000000000..3ef371809d --- /dev/null +++ b/contributed_definitions/NXimage_r_set.nxdl.xml @@ -0,0 +1,100 @@ + + + + + + + + Number of images in the stack. + + + + + Number of pixel per image in the slow direction. + + + + + Number of pixel per image in the fast direction. + + + + + Specialized base class container for reporting a set of images in real space. + + + + + Image (stack). + + + + Image intensity values. + + + + + + + + + + Image identifier + + + + + + + Image identifier. + + + + + + Pixel coordinate center along y direction. + + + + + + + Coordinate along y direction. + + + + + + Pixel coordinate center along x direction. + + + + + + + Coordinate along x direction. + + + + + diff --git a/contributed_definitions/NXimage_r_set_diff.nxdl.xml b/contributed_definitions/NXimage_r_set_diff.nxdl.xml new file mode 100644 index 0000000000..c9ff02c0d9 --- /dev/null +++ b/contributed_definitions/NXimage_r_set_diff.nxdl.xml @@ -0,0 +1,179 @@ + + + + + + + + Number of scanned points. Scan point may have none, one, or more pattern. + + + + + Number of diffraction pattern. + + + + + Number of pixel per pattern in the slow direction. + + + + + Number of pixel per pattern in the fast direction. + + + + + Base class specialized for reporting a cuboidal stack of diffraction pattern. + + Diffraction pattern, whether they were simulated or measured are the raw data + for computational workflows to characterize the phase and orientation + of crystalline regions in matter. + + Steps of post-processing the diffraction patterns should be documented using + method-specific specialized base classes. All eventual post-processing of + resulting orientation maps (2D or 3D) should be documented via :ref:`NXms_recon`. + + To implement an example how this base class can be used we focused in FAIRmat + on Kikuchi diffraction pattern here specifically the research community + of Electron Backscatter Diffraction (EBSD). + + For this reason, this base class and related :ref:`NXem_base` classes extend the + work of `M. A. Jackson et al. <https://doi.org/10.1186/2193-9772-3-4>`_ + (one of the developers of DREAM.3D) and the H5OINA public file format developed by + `P. Pinard et al. <https://doi.org/10.1017/S1431927621006103>`_ with Oxford Instruments. + + Kikuchi pattern are typically collected with FIB/SEM microscopes, + for two- and three-dimensional orientation microscopy. + + For a detailed overview of these techniques see e.g. + + * `M. A. Groeber et al. <https://doi.org/10.1186/2193-9772-3-5>`_ + * `A. J. Schwartz et al. <https://doi.org/10.1007/978-1-4757-3205-4>`_ + * `P. A. Rottman et al. <https://doi.org/10.1016/j.mattod.2021.05.003>`_ + + Serial-sectioning demands a recurrent sequence of ion milling and measuring. + This suggests that each serial section is at least an own NXevent_data_em + instance. The three-dimensional characterization as such demands a computational + step where the maps for each serial section get cleaned, aligned, and registered + into an image stack. This image stack represents a digital model of the + inspected microstructural volume. Often this volume is called a (representative) + volume element (RVE). Several software packages exists for performing + these post-processing tasks. + + This example may inspire users of other types of diffraction methods. + + + + Category which type of diffraction pattern is reported. + + + + + + + + Collected diffraction pattern as an image stack. As raw and closest to the + first retrievable measured data as possible, i.e. do not use this + container to store already averaged, filtered or whatever post-processed + pattern unless these are generated unmodifiably in such manner by the + instrument given the way how the instrument and control software + was configured for your microscope session. + + + + Array which resolves the scan point to which each pattern belongs. + + Scan points are evaluated in sequence starting from scan point zero + until scan point n_sc - 1. Evaluating the cumulated of this array + decodes which pattern in intensity belongs to which scan point. + + Take an example with three scan points: The first scan point has one + pattern, the second has three pattern, the last scan point has no + pattern. In this case the scan_point_identifier are 0, 1, 1, 1. + The length of the scan_point_identifier array is four because four + pattern were measured in total. + + In most cases usually one pattern is averaged by the detector for + some amount of time and then reported as one pattern. + + + + + + + + Intensity of the diffraction pattern. + + + + + + + + + + Pattern intensity + + + + + + + Pattern are enumerated starting from 0 to n_p - 1. + + + + + + + Pattern identifier + + + + + + + diff --git a/contributed_definitions/NXinteraction_vol_em.nxdl.xml b/contributed_definitions/NXinteraction_vol_em.nxdl.xml index a6beeb6482..59c71c10ef 100644 --- a/contributed_definitions/NXinteraction_vol_em.nxdl.xml +++ b/contributed_definitions/NXinteraction_vol_em.nxdl.xml @@ -1,36 +1,56 @@ - + - + + - Base class for storing details about a modelled shape of interaction volume. + Base class for describing the interaction volume of particle-matter interaction. - The interaction volume is mainly relevant in scanning electron microscopy - when the sample is thick enough so that the beam is unable to illuminate - through the specimen. - Computer models like Monte Carlo or molecular dynamics / electron beam - interaction simulations can be used to qualify and/or quantify the shape of - the interaction volume. + Computer models like Monte Carlo or molecular dynamics / electron- or ion-beam + interaction simulations can be used to qualify and (or) quantify the shape of + the interaction volume. Results of such simulations can be summary statistics + or single-particle resolved sets of trajectories. Explicit or implicit descriptions are possible. - * An implicit description is via a set of electron/specimen interactions - represented ideally as trajectory data from the computer simulation. - * An explicit description is via an iso-contour surface using either - a simulation grid or a triangulated surface mesh of the approximated - iso-contour surface evaluated at specific threshold values. - Iso-contours could be computed from electron or particle fluxes through - an imaginary control surface (the iso-surface). - Threshold values can be defined by particles passing through a unit control - volume (electrons) or energy-levels (e.g. the case of X-rays). - Details depend on the model. - * Another explicit description is via theoretical models which may - be relevant e.g. for X-ray spectroscopy + * An implicit description is via a set of electron/specimen interactions + represented ideally as trajectory data from the computer simulation. + * An explicit description is via an iso-contour surface using either + a simulation grid or a triangulated surface mesh of the approximated + iso-contour surface evaluated at specific threshold values. + Iso-contours could be computed from electron or particle fluxes through + an imaginary control surface (the iso-surface). + Threshold values can be defined by particles passing through a unit control + volume (electrons) or energy-levels (e.g. the case of X-rays). + Details depend on the model. + * Another explicit description is via theoretical models which may + be relevant e.g. for X-ray spectroscopy Further details on how the interaction volume can be quantified is available in the literature for example: - * `S. Richter et al. <https://doi.org/10.1088/1757-899X/109/1/012014>`_ - * `J. Bünger et al. <https://doi.org/10.1017/S1431927622000083>`_ + * `S. Richter et al. <https://doi.org/10.1088/1757-899X/109/1/012014>`_ + * `J. Bünger et al. <https://doi.org/10.1017/S1431927622000083>`_ + * `J. F. Ziegler et al. <https://doi.org/10.1007/978-3-642-68779-2_5>`_ diff --git a/contributed_definitions/NXms_ipf.nxdl.xml b/contributed_definitions/NXms_ipf.nxdl.xml new file mode 100644 index 0000000000..49568b0ac1 --- /dev/null +++ b/contributed_definitions/NXms_ipf.nxdl.xml @@ -0,0 +1,383 @@ + + + + + + + + + Number of pixel along the z slowest direction. + + + + + Number of pixel along the y slow direction. + + + + + Number of pixel along the x fast direction. + + + + + Number of RGB values along the fastest direction, always three. + + + + + Dimensionality of the mapping (either 2 or 3). + + + + + Base class to store an inverse pole figure (IPF) mapping (IPF map). + + + + Reference to the coordinate system whereby the projection_direction is defined. + + If the field depends_on is not provided but a parent of the instance + of this base class or its specialization defines an :ref:`NXcoordinate_system_set` + and exactly one :ref:`NXcoordinate_system`, the reference points to this system. + + If nothing is provided and none of the above-mentioned references pointing + in a parent, McStas is assumed. + + + + + The direction along which orientations are projected. + + + + + + + + Details about the original grid. + + Here original grid means the one onto which the IPF map was computed + when exported from the tech partner's file format representation. + + + + + Details about the grid onto which the IPF is recomputed. + + Rescaling the visualization of the IPF map may be needed to enable + visualization in specific software tools like H5Web. + The value specifies the fractional change of the spacing between + the original mapping and the scaled one. + + + + + How where orientation values at the location of the output grid + positions computed. + + Nearest neighbour means the orientation of the closed (Euclidean distance) + grid point of the input_grid was taken. + + + + + + + + Inverse pole figure mapping. + + Default inverse pole figure (IPF) plot of the data specific for each + phase. No ipf_mapID instances for non-indexed scan points as these are + by definition assigned the null phase with phase_identifier 0. + Inspect the definition of :ref:`NXcrystal_structure` and its field + phase_identifier for further details. + + Details about possible regridding and associated interpolation + during the computation of the IPF map visualization can be stored + using the input_grid, output_grid, and interpolation fields. + + The main purpose of this map is to offer a normalized default representation + of the IPF map for consumption by a research data management system (RDMS). + This is aligned with the first aim of :ref:`NXms_ipf`, to bring colleagues and + users of IPF maps together to discuss which pieces of information + need to be stored together. We are convinced a step-by-step design and + community-driven discussion about which pieces of information should + and/or need to be included is a practical strategy to work towards an + interoperable description and data model for exchanging IPF maps as specific + community-accepted tools to convey orientation maps. + + With this design the individual RDMS solutions and tools can still continue + to support specific custom data analyses workflow and routes but at least + there is one common understanding which enables also those users who are + not necessarily experts in all the details of the underlying techniques + can understand and thus eventually judge if the dataset is worth to be + reused or repurposed. + + + + + + Inverse pole figure color code for each map coordinate. + + + + + + + + + + Pixel center coordinate calibrated for step size along the z axis of the map. + + + + + + + + + Pixel center coordinate calibrated for step size along the y axis of the map. + + + + + + + + + Pixel center coordinate calibrated for step size along the x axis of the map. + + + + + + + + + + The color code which maps colors into orientation into the fundamental zone. + + For each stereographic standard triangle (SST), i.e. a rendering of the + fundamental zone of the crystal-symmetry-reduced orientation space + SO3, it is possible to define a color model which assigns each point in + the fundamental zone a color. + + Different mapping models are used. These implement (slightly) different + scaling relations. Differences exist across representations of tech partners. + + Differences are which base colors of the RGB color model are placed in + which extremal position of the SST and where the white point is located. + + For further details see: + + * [G. Nolze et al.](https://doi.org/10.1107/S1600576716012942) + * Srikanth Patala and coworkers"'" work and of others. + + Details are implementation-specific and not standardized yet. + + Given that the SST has a complicated geometry, it cannot yet be + visualized using tools like H5Web, which is why for now the matrix + of a rasterized image which is rendered by the backend tool gets + copied into an RGB matrix to offer a default plot. + + + + + + Inverse pole figure color code for each map coordinate. + + + + + + + + + + Pixel along the y-axis. + + + + + + + + + Pixel along the x-axis. + + + + + + + + + diff --git a/contributed_definitions/NXms_ipf_set.nxdl.xml b/contributed_definitions/NXms_ipf_set.nxdl.xml new file mode 100644 index 0000000000..776eb0a6c9 --- /dev/null +++ b/contributed_definitions/NXms_ipf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_ipf` instances. + + A collection of inverse pole figure approximations. + + + diff --git a/contributed_definitions/NXms_mtex_config.nxdl.xml b/contributed_definitions/NXms_mtex_config.nxdl.xml new file mode 100644 index 0000000000..a810d12b3c --- /dev/null +++ b/contributed_definitions/NXms_mtex_config.nxdl.xml @@ -0,0 +1,310 @@ + + + + + + Base class to store the configuration when using the MTex/Matlab software. + + MTex is a Matlab package for texture analysis used in the Materials and Earth Sciences. + See `R. Hielscher et al. <https://mtex-toolbox.github.io/publications>`_ and + the `MTex source code <https://github.com/mtex-toolbox>`_ for details. + + + + Reference frame and orientation conventions. + Consult the `MTex docs <https://mtex-toolbox.github.io/EBSDReferenceFrame.html>`_ for details. + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + TODO with MTex developers + + + + + + + + + + + Settings relevant for generating plots. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + True if MTex renders a scale bar with figures. + + + + + True if MTex renders a grid with figures. + + + + + Code for the function handle used for annotating pole figure plots. + + + + + TODO with MTex developers + + + + + + + + + TODO with MTex developers + + + + + + + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Miscellaneous other settings of MTex. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + + Miscellaneous settings relevant for numerics. + + + + Return value of the Matlab eps command. + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Miscellaneous settings relevant of the system where MTex runs. + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + TODO with MTex developers + + + + + + Collection of paths from where MTex reads information and code. + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + Absolute path to specific component of MTex source code. + + + + + List of file type suffixes for which MTex assumes + texture/pole figure information. + + + + + List of file type suffixes for which MTex assumes EBSD content. + + + + + diff --git a/contributed_definitions/NXms_odf.nxdl.xml b/contributed_definitions/NXms_odf.nxdl.xml new file mode 100644 index 0000000000..988034557d --- /dev/null +++ b/contributed_definitions/NXms_odf.nxdl.xml @@ -0,0 +1,171 @@ + + + + + + + + Number of pixel per varphi section plot along the varphi_one fastest direction. + + + + + Number of pixel per varphi section plot along the capital_phi slow direction. + + + + + Number of pixel per varphi section plot along the varphi_two slowest direction. + + + + + Number of local maxima evaluated in the component analysis. + + + + + Base class to store an orientation distribution function (ODF) computation. + + + + Details about the algorithm used for computing the ODF. + + + + Point group of the crystal structure (International Table of Crystallography) + of the phase for which the here documented phase-dependent ODF was computed. + + + + + Point group assumed for processing-induced *sample symmetries*. + (according to International Table of Crystallography). + + + + + Halfwidth of the kernel. + + + + + Name of the kernel. + + + + + Resolution of the kernel. + + + + + + + Number of local maxima evaluated for the ODF. + + + + + + Euler angle representation of the kth-most maxima of the ODF + in decreasing order of the intensity maximum. + + + + + + + + + Disorientation threshold within which intensity of the ODF + is integrated for the component analysis. + + + + + Integrated ODF intensity within a theta-ball of SO3 about + each location as specified for each location in the order + and reported in the order of these locations. + + + + + + + + + Visualization of the ODF intensity as orthogonal sections through Euler space. + + This is one example of typical default plots used in the texture + community in Materials Engineering. + + Mind that the Euler space is a distorted space. Therefore, equivalent + orientations show intensity contributions in eventually multiple + locations. + + + + + ODF intensity at probed locations relative to + null model of a completely random texture. + + + + + + + + + + Pixel center angular position along the :math:`\varphi_1` direction. + + + + + + + + + Pixel center angular position along the :math:`\varphi_2` direction. + + + + + + + + + Pixel center angular position along the :math:`\Phi` direction. + + + + + + + + diff --git a/contributed_definitions/NXms_odf_set.nxdl.xml b/contributed_definitions/NXms_odf_set.nxdl.xml new file mode 100644 index 0000000000..d41a609a8b --- /dev/null +++ b/contributed_definitions/NXms_odf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_odf` instances. + + A collection of orientation distribution function approximations. + + + diff --git a/contributed_definitions/NXms_pf.nxdl.xml b/contributed_definitions/NXms_pf.nxdl.xml new file mode 100644 index 0000000000..9a627ac62b --- /dev/null +++ b/contributed_definitions/NXms_pf.nxdl.xml @@ -0,0 +1,111 @@ + + + + + + + + Number of pixel per pole figure in the slow direction. + + + + + Number of pixel per pole figure in the fast direction. + + + + + Base class to store a pole figure (PF) computation. + + + + Details about the algorithm that was used to compute the pole figure. + + + + Point group of the crystal structure of the phase for which the + here documented phase-dependent pole figure was computed + (according to International Table of Crystallography). + + + + + Point group assumed for processing induced *sample symmetries* + (according to International Table of Crystallography). + + + + + Halfwidth of the kernel. + + + + + Miller indices (:math:`(hkl)[uvw]`) to specify the pole figure. + + + + + Resolution of the kernel. + + + + + + Pole figure. + + + + + Pole figure intensity. + + + + + + + + + Pixel center along y direction in the equatorial plane of + a stereographic projection of the unit sphere. + + + + + + + + + Pixel center along x direction in the equatorial plane of + a stereographic projection of the unit sphere. + + + + + + + + diff --git a/contributed_definitions/NXms_pf_set.nxdl.xml b/contributed_definitions/NXms_pf_set.nxdl.xml new file mode 100644 index 0000000000..3ca5fc0005 --- /dev/null +++ b/contributed_definitions/NXms_pf_set.nxdl.xml @@ -0,0 +1,33 @@ + + + + + + + Base class to group multiple :ref:`NXms_pf` instances. + + A collection of pole figure approximations. + + + diff --git a/contributed_definitions/NXms_recon.nxdl.xml b/contributed_definitions/NXms_recon.nxdl.xml new file mode 100644 index 0000000000..99e629ba23 --- /dev/null +++ b/contributed_definitions/NXms_recon.nxdl.xml @@ -0,0 +1,454 @@ + + + + + + + + The symbols used in the schema to specify e.g. dimensions of arrays. + + + + + The number of crystal projections. + + + + + The number of interface projections. + + + + + The number of assumed triple junction projections aka triple points. + + + + + + The number of crystals. + + + + + The number of interfaces + + + + + The number of triple lines + + + + + The number of quadruple junctions. + + + + + Base class to describe discretized (micro)structural features of a material. + + One instance of this base class can be used to describe the current configuration + the base class does not include time-dependent descriptions for the sake of + clarity and because of the fact that virtually all simulations or experiments + probe time by sampling. Therefore, time-dependent state descriptions should + be realized with creating a set of :ref:`NXms_snapshot_set` with instances of + :ref:`NXms_snapshot` using e.g. :ref:`NXms_recon` base class instances. + + + + + The configuration and parameterization of the reconstruction algorithm + whereby the microstructural features were identified. + + + + + Dimensionality of the analysis. + + This field can be used e.g. by a research data management system + to identify if the described feature set specifies a + one-, two-, or three-dimensional feature set. + + + + + + + + + + Which algorithm is used to reconstruct the features. + + + + + + + + + + + Threshold to define at which disorientation angle to assume + two crystalline regions have a significant orientation difference + which warrants to argue that there is an interface between the + two regions. + + + + + + + + + + + + + Projections of crystals on the sample surface as typically + characterized with optical or electron microscopy. + + + + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Most microscopy techniques support to generate only a two-dimensional + representation (projection) of the characterized material. + + For true volumetric techniques use the specifically + specialized crystals :ref:`NXms_feature_set` instead. + See stereology literature for more details e.g. + E.E. Underwood's book entitled Quantitative Stereology + + + + + Number of crystals. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier used for crystals for explicit indexing. + + + + + + + + How many phases are distinguished + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + + + + + Identifier used for phase for explicit indexing. + + + + + + + + + True, if the crystal makes contact with the edge of the ROI, + false otherwise. + + + + + + + + Average disorientation angle between individual orientation of the + crystal at probed positions (weighted by area of that position) versus + the average disorientation of the crystal. + + + + + + + + + Calibrated area of surrounded by the polyline about each crystal. + + + + + + + + + + Projections of grain or phase boundaries as typically sectioned + with optical or electron microscopy characterization. + + + + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Set of tuples of polyline segments which build the interface. + + + + + + Set of pairs of crystal_identifier resolved via depends_on which + are adjacent to each interface. + + + + + + + + The specific crystal_projections(NXms_feature_set) instance + to resolve crystal identifier. + + + + + + + Set of pairs of triple_point_identifier which the interface connects. + For 2D projections of 3D microstructural features a triple point is + physically only the projection of a triple line. + + + + + + + + The specific triple_line_projections(NXms_feature_set) instance + whereby to resolve triple_point identifier. + + + + + + + The length of the interface. + + This is not necessarily the same as the length of the individual + polyline segments whereby the interface is discretized. + + The actual coordinate system whereby the geometry is calibrated + with real physical dimensions is typically documented by the + depends_on attribute of the respective NXcg_primitive_set. + This depends_on attribute should point explicitly to an + instance of a :ref:`NXcoordinate_system` to support users as + much as possible with interpreting how and where the lines are + located in the reference frame. + + + + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier for each interface using explicit indexing. + + + + + + + + + + Projections of triple lines as typically characterized with optical + or electron microscopy. + + Mind that most specimens are thermo-chemo-mechanically treated before + they are characterized. Therefore, the projected crystal defects are + have physically no longer the same structure as in the bulk. + + Examples are manifest as effects such as thermal grooving, or relaxation + effects of an intersection between a triple line that is cut + by the specimen surface as these defects are then exposed typically + to a different atmosphere and hence have different thermodynamic boundary + conditions than of their true volumetric defects in the bulk. + + + + Reference to points(NXcg_point_set) which supports the + locations of these triple points. + + + + + + Number of triple points. + + + + + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + + + + Identifier for each triple point using explicit indexing. + + + + + + + + Set of triple point identifiers. + + + + + + + The relevant points(NXcg_point_set) instance whereby to + resolve interface identifiers. + + + + + + Set of triplets of identifier of line-like features. + Each triplet resolves which three interface projections + the triple point connects. + + + + + + + + The specific interface_projections(NXms_feature_set) + instance whereby to resolve interface identifiers. + + + + + + + Triplet of identifier of polyline segments. Each triplet resolves + which three segments of polyline segments the triple junction connects. + + + + + + + + The specific lines(NXcg_polyline_set) instance to resolve + polyline segments. + + + + + + diff --git a/contributed_definitions/NXroi.nxdl.xml b/contributed_definitions/NXroi.nxdl.xml new file mode 100644 index 0000000000..b77834bb69 --- /dev/null +++ b/contributed_definitions/NXroi.nxdl.xml @@ -0,0 +1,34 @@ + + + + + + Base class to describe a region-of-interest analyzed. + + + + Details about processing steps. + + + + diff --git a/contributed_definitions/nyaml/NXcg_primitive_set.yaml b/contributed_definitions/nyaml/NXcg_primitive_set.yaml new file mode 100644 index 0000000000..586929596f --- /dev/null +++ b/contributed_definitions/nyaml/NXcg_primitive_set.yaml @@ -0,0 +1,136 @@ +category: base +doc: | + Computational geometry description of a set of primitives in Euclidean space. + + Primitives must neither be degenerated nor self-intersect. + Individual primitives can differ in their properties (e.g. size, shape, rotation). +# this base class defines common fields and properties of geometric primitives +# more complex primitive sets like NXcg_cylinder_set are considered specializations +# of NXcg_primitive_set. They contain all fields and groups which NXcg_primitive_set +# defines. This is an action of compositing an information set; an act of inheriting +# TODO:: many properties of non-degenerate primitives are in the number set +# R+ instead of in R+0 but currently NeXus does not allow for such value range +# constraints unless the coarsely discretized NX_INT, NX_POSINT, NX_FLOAT +# but there is no say NX_FLOAT+0 +# MK::but in computational geometry numerical precision matters as it defines +# whether objects numerically intersect or not and thus it can make a real difference +# if one stores triangles with 16, 32, or 64 bit precision, however: +# are two triangle_set instance A and B no longer conceptually triangle sets +# because A stores the positions of vertices using int8 while B stores such using float64 ? +# we here assume that we still conceptually talk that A and B are triangle sets +# but this brings at the level of the application definition the problem that if the +# precision is not properly constrainted a consuming application will not obtain +# the instances of the concept triangle_set with relevant high enough precision +# and thus neither the base class nor the application definition is specific enough +# for what it was designed in the first place - be specific about the requirements +# on your data... +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + d: | + The dimensionality of the space. + c: | + The cardinality of the set, i.e. the number of members. +type: group +NXcg_primitive_set(NXobject): + # individual specializations like NXcg_polyline_set typically overwrite + # the meaning of the depends_on concept to build consistent inference chains + # to enable an instantiation of the actual geometric primitives + \@depends_on(NX_CHAR): + doc: | + Hint to help resolve in which Euclidean coordinate system field values + like center or orientation are defined. + dimensionality(NX_POSINT): + doc: | + The dimensionality of the primitive set. + unit: NX_UNITLESS + enumeration: [1, 2, 3] + cardinality(NX_POSINT): + doc: | + The cardinality of the primitive set. + unit: NX_UNITLESS + identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + + Therefore, implicit identifier are completely defined by the value of + identifier_offset and cardinality. For example if identifier run from + -2 to 3 the value for identifier_offset is -2. + + For explicit indexing the field identifier has to be used. + Fortran-/Matlab- and C-/Python-style indexing have specific implicit + identifier conventions where identifier_offset is 1 and 0 respectively. + unit: NX_UNITLESS + identifier(NX_INT): + doc: | + Identifier of each member for explicit indexing. + dim: (c,) # numpy style indexing + center(NX_NUMBER): + doc: | + The center of mass position of each primitive. + unit: NX_ANY + dim: (c, d) + # a depends_on to define in which coordinate system + is_center_of_mass(NX_BOOLEAN): + doc: | + True if the center is a center of mass. + dim: (c,) + shape(NX_NUMBER): + doc: | + A qualitative description of the shape of each primitive. + unit: NX_LENGTH + dim: (c, d) + length(NX_NUMBER): + doc: | + Qualifier for the length of characteristic features of the primitive. + + Often the term length is associated with the assumption that one + edge is parallel to an axis of the coordinate system. + unit: NX_LENGTH + dim: (c,) + width(NX_NUMBER): + doc: | + Qualifier often used to describe the length of one characteristic edge + within the coordinate system. + unit: NX_LENGTH + dim: (c,) + is_closed(NX_BOOLEAN): + doc: | + True if primitive is closed such that it has properties like area or volume. + dim: (c,) + volume(NX_NUMBER): + doc: | + Volume of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + unit: NX_VOLUME + dim: (c,) + area(NX_NUMBER): + doc: | + Alias for surface_area of each primitive. + + Set to NaN if does not apply for primitives for which is_closed is False. + unit: NX_AREA + dim: (c,) + orientation(NX_NUMBER): + doc: | + Direction unit vector which points along the + longest principal axis of each primitive. + + Use the depends_on attribute to specify in which coordinate system + these direction unit vectors are defined. + unit: NX_DIMENSIONLESS + dim: (c, d) + vertex_normal(NXcg_unit_normal_set): + edge_normal(NXcg_unit_normal_set): + face_normal(NXcg_unit_normal_set): + # roi(NXcg_parallelogram_set or NXcg_hexahedron_set) + # aabb(NXcg_parallelogram_set or NXcg_hexahedron_set) + # obb(NXcg_parallelogram_set or NXcg_hexahedron_set) + # MK::one could add (NXcg_parallelogram_set) and/or (NXcg_hexahedron_set) + # but then one would not give any hint at the base class level how to name diff --git a/contributed_definitions/nyaml/NXcomponent_em.yaml b/contributed_definitions/nyaml/NXcomponent_em.yaml new file mode 100644 index 0000000000..78870cc26b --- /dev/null +++ b/contributed_definitions/nyaml/NXcomponent_em.yaml @@ -0,0 +1,39 @@ +category: base +doc: | + Base class for components used in an electron microscope. + + The electron microscope can be a real one or a simulated microscope. + The key motivation behind this generalization is the observation that in all + cases a controlled electron beam is generated in reality or that beam is simulated + and this beam is then used or modified in a controlled manner for the purpose + of studying physical interaction mechanisms of the beam with matter. + Here it does not matter whether one considers a real specimen or a simulated one. + + Using a common description for the real experiment in the lab and - what is + typically a simplification of it - via a computer simulation, has the benefit + that many pieces of information can be stored in the same way. In effect, + users are guided with finding information and unnecessary descriptive + variety for what are exactly the same concept is avoided to work towards + more interoperability. + + Another motivation to make no fundamental distinction between a scanning and + a transmission electron microscope is that both are electron microscopes whose + components are often very similar. +# `point Electronic GmbH `_ +type: group +NXcomponent_em(NXobject): + name(NX_CHAR): + doc: | + Given name to the component e.g stage, lens C1, etc. + description(NX_CHAR): # NXidentifier + doc: | + Ideally, a (globally) unique persistent identifier, link, or text to a + resource which gives further details to this component. + If such resource does not exist, a free-text field to report + further details about the component is possible. + (NXfabrication): + (NXprogram): + (NXtransformations): + doc: | + Collection of axis-based translations and rotations to describe the + location and geometry of the component in the instrument. diff --git a/contributed_definitions/nyaml/NXcoordinate_system.yaml b/contributed_definitions/nyaml/NXcoordinate_system.yaml new file mode 100644 index 0000000000..b219399001 --- /dev/null +++ b/contributed_definitions/nyaml/NXcoordinate_system.yaml @@ -0,0 +1,86 @@ +category: base +doc: | + Base class to detail a coordinate system (CS). + + Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as + a member in an :ref:`NXcoordinate_system_set` and the name of the instance + should be this alias. This may support a process whereby jargon when talking + about coordinate systems and conventions may become cleaner for users + because it is not evident for people outside a lab that terms like e.g. + tip space or specimen space refer to the same coordinate system. + This is an example of jargon used in e.g. the field of atom + probe tomography. +type: group +NXcoordinate_system(NXobject): + origin(NX_CHAR): + doc: | + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door-handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. + # implementing a proposal for "a common base table" along thoughts like: + # https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#nxtransformations + # similar to a place where all transformations are stored + # https://www.zenodo.org/record/3526738/files/lyso009a_0087.JF07T32V01_master.h5?download=1 + alias(NX_CHAR): + doc: | + An alternative name given to that coordinate system. + type(NX_CHAR): + doc: | + Coordinate system type. + enumeration: [cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + x_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the x-axis. + x_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. + x(NX_NUMBER): + doc: | + Base unit vector along the first axis which spans the coordinate system. + This axis is frequently referred to as the x-axis in real space and + the i-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) + y_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the y-axis. + y_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + y(NX_NUMBER): + doc: | + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) + z_alias(NX_CHAR): + doc: | + Possibility to define an alias for the name of the z-axis. + z_direction(NX_CHAR): + doc: | + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + z(NX_NUMBER): + doc: | + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. + unit: NX_LENGTH + dim: (3,) diff --git a/contributed_definitions/nyaml/NXcrystal_structure.yaml b/contributed_definitions/nyaml/NXcrystal_structure.yaml new file mode 100644 index 0000000000..796ac83d3c --- /dev/null +++ b/contributed_definitions/nyaml/NXcrystal_structure.yaml @@ -0,0 +1,178 @@ +category: base +doc: | + Base class to describe the atomic crystal structure of a phase. + + This base class contains key metadata that are relevant parameter to every + physics-based model to simulate radiation matter interaction. + + Examples where such base class is useful are kinematic or dynamic + diffraction simulations of e.g. (Kikuchi or other type of) patterns. +# The actual indexing of Kikuchi patterns may use different algorithms. +# Such are used within different workflows where simulated and measured +# Kikuchi pattern are compared to rate which phase and orientation is the most +# likely candidate describing the pattern measured at that each scan point +# respectively. If this evaluation yields scan points without any solutions, +# these are represented using the null-phase model phase0, aka n/a aka notIndexed. +# Traditionally, Hough transformation-based indexing has been the most frequently +# used algorithm. Dictionary-based alternatives are emerging. +symbols: + n_hkl: | + Number of reflectors (Miller crystallographic plane triplets). + n_pos: | + Number of atom positions. + d: | + Dimensionality of the lattice. +type: group +NXcrystal_structure(NXobject): + \@depends_on(NX_CHAR): + doc: | + Detail in which reference frame the unit cell is defined. + dimensionality(NX_POSINT): + doc: | + Dimensionality of the lattice. + enumeration: [1, 2, 3] + reference(NXidentifier): + doc: | + Reference to another resource that was used for + instantiating this structure model. + a_b_c(NX_NUMBER): + doc: | + Crystallography unit cell parameters a, b, and c. + unit: NX_LENGTH + dim: (d,) + # defined using which convention? + alpha_beta_gamma(NX_NUMBER): + doc: | + Crystallography unit cell parameters alpha, beta, and gamma. + unit: NX_ANGLE + dim: (d,) + area(NX_NUMBER): + doc: | + Area of the unit cell considering that d = 2. + unit: NX_AREA + volume(NX_NUMBER): + doc: | + Volume of the unit cell considering that d = 3. + unit: NX_VOLUME + crystal_system(NX_CHAR): + doc: | + Crystal system + enumeration: [triclinic, monoclinic, orthorhombic, tetragonal, rhombohedral, hexagonal, cubic] + # 2d + laue_group(NX_CHAR): + doc: | + Laue group using International Table of Crystallography Notation. + # add enumeration of all possible + point_group(NX_CHAR): + doc: | + Point group using International Table of Crystallography Notation. + # add enumeration all possible + # 3d + space_group(NX_CHAR): + doc: | + Space group from the International Table of Crystallography Notation. + # add enumeration of all possible + is_centrosymmetric(NX_BOOLEAN): + doc: | + True if space group is considered a centrosymmetric one. + False if space group is considered a non-centrosymmetric one. + Centrosymmetric has all types and combinations of symmetry elements + (translation, rotational axis, mirror planes, center of inversion) + Non-centrosymmetric compared to centrosymmetric is constrained (no inversion). + Chiral compared to non-centrosymmetric is constrained (no mirror planes). + is_chiral(NX_BOOLEAN): + doc: | + True if space group is considered a chiral one. + False if space group is consider a non-chiral one. + phase_identifier(NX_INT): + doc: | + Identifier for each phase. + + The value 0 is reserved for the unknown phase that represents the + null-model no sufficiently significant confirmation. In other words, + the phase_name is n/a, notIndexed. + + The phase identifier value has to match with the integer postfix of the + group name which represents that instance in a NeXus/HDF5 file, i.e. + if two phases were used e.g. 0 and 1, two instances of an + :ref:`NXcrystal_structure` named phase0 and phase1 + should be stored in the HDF5 file. + unit: NX_UNITLESS + # \@depends_on(NX_CHAR): + # doc: | + # Refers to the specific identifier_offset to consider. + # + # If not provided assume identifier_offset is 0. + phase_name(NX_CHAR): + doc: | + Name of the phase/alias. + + If the phase_identifier is 0 and one would like to use the field + phase_name the value should be n/a. + atom_identifier(NX_CHAR): + doc: | + Label for each atom position. + dim: (n_pos,) + atom_type(NX_UINT): + doc: | + The hash value :math:`H` is :math:`H = Z + N*256` with :math:`Z` + the number of protons and :math:`N` the number of neutrons + of each isotope respectively. Z and N have to be 8-bit unsigned integers. + For the rationale behind this `M. Kühbach et al. (2021) `_ + unit: NX_UNITLESS + dim: (n_pos,) + # atom_position(NXcg_point_set): + atom_position(NX_NUMBER): + doc: | + Atom positions. + dim: (n_pos, d) + unit: NX_ANY + \@depends_on(NX_CHAR): + doc: | + Reference to an instance of :ref:`NXcoordinate_system` + whereby the positions can be resolved. + # in addition we need to have a physical model e.g. kinematic or dynamical e-diffraction theory + # to describe the simulated Kikuchi pattern generated from such a model + atom_occupancy(NX_NUMBER): + doc: | + Relative occupancy of the atom position. + unit: NX_DIMENSIONLESS + dim: (n_pos,) + number_of_planes(NX_UINT): + doc: | + How many reflectors are distinguished. + + Value has to match value for symbol n_hkl. + unit: NX_UNITLESS + # Miller indices :math:`(hkl)[uvw]`. + miller(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Miller indices :math:`(hkl)[uvw]` of the planes. + + The first triplet specify :math:`(hkl)` the second triplet :math:`[uvw]`. + Miller indices refer to the Cartesian right-handed coordinate system + of the unit cell. + dim: (n_hkl, 6) + dspacing(NX_NUMBER): + doc: | + Spacing between crystallographic planes as defined by field miller. + unit: NX_LENGTH + dim: (n_hkl,) + relative_intensity(NX_NUMBER): + doc: | + Relative intensity of the signal for the plane. + unit: NX_DIMENSIONLESS + dim: (n_hkl,) + number_of_scan_points(NX_UINT): + doc: | + In case the :ref:`NXcrystal_structure` base class is used + with analyzed orientation maps this field stores how many scan points + of the map were identified as that phase. + unit: NX_UNITLESS + ipfID(NXms_ipf): + pfID(NXms_pf): + odfID(NXms_odf): +# here the theoreticians expert (Marc deGraeff, Aimo Winkelmann, Peter Rez) +# can give some good suggestions on how to improve and ideally make even +# more general this section diff --git a/contributed_definitions/nyaml/NXcs_cpu_obj.yaml b/contributed_definitions/nyaml/NXcs_cpu_obj.yaml new file mode 100644 index 0000000000..73097d5ca5 --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_cpu_obj.yaml @@ -0,0 +1,12 @@ +category: base +doc: | + Computer science description of a (central) processing unit (C)PU of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_cpu_obj(NXobject): + name(NX_CHAR): + doc: | + Given name of the CPU. Users should be as specific as possible. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_cpu_sys.yaml b/contributed_definitions/nyaml/NXcs_cpu_sys.yaml new file mode 100644 index 0000000000..5eaf8f0eab --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_cpu_sys.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Computer science description of a system of classical central processing units. + + For coprocessor or graphic cards use :ref:`NXcs_gpu_sys` instead. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_cpu_sys(NXobject): + cpuID(NXcs_cpu_obj): + doc: | + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single CPU one + could describe using one instance of :ref:`NXcs_cpu_obj` inside one instance of + :ref:`NXcs_cpu_sys`. + A dual-socket server one could describe using two instances of :ref:`NXcs_cpu_obj` + inside one instance of :ref:`NXcs_cpu_sys`. + A server with two dual-socket server nodes one could describe + with the above group of one :ref:`NXcs_cpu_sys` into another :ref:`NXcs_cpu_sys`. diff --git a/contributed_definitions/nyaml/NXcs_gpu_obj.yaml b/contributed_definitions/nyaml/NXcs_gpu_obj.yaml new file mode 100644 index 0000000000..04468b7b2b --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_gpu_obj.yaml @@ -0,0 +1,12 @@ +category: base +doc: | + Computer science description of a graphic processing unit (GPU) of a computer. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_gpu_obj(NXobject): # NXcircuit_board ? + name(NX_CHAR): + doc: | + Given name of the GPU. Users should be as specific as possible. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXcs_gpu_sys.yaml b/contributed_definitions/nyaml/NXcs_gpu_sys.yaml new file mode 100644 index 0000000000..dee199330c --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_gpu_sys.yaml @@ -0,0 +1,20 @@ +category: base +doc: | + Computer science description of a system of coprocessor or graphics processors. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_gpu_sys(NXobject): + gpuID(NXcs_gpu_obj): + doc: | + Granularizing at the socket level. + + Typical examples follow: A desktop computer with a single GPU one + could describe using one instance of :ref:`NXcs_gpu_obj` inside one instance of + :ref:`NXcs_gpu_sys`. + A desktop computer with two GPUs one could describe using two instances + of :ref:`NXcs_gpu_obj` inside one instance of :ref:`NXcs_gpu_sys`. + A GPU server like nowadays used for artificial intelligence + one could describe as a system with n instances of :ref:`NXcs_gpu_obj` + in one :ref:`NXcs_gpu_sys` or :ref:`NXcs_cpu_sys`. diff --git a/contributed_definitions/nyaml/NXcs_mm_obj.yaml b/contributed_definitions/nyaml/NXcs_mm_obj.yaml new file mode 100644 index 0000000000..d1fead8c8b --- /dev/null +++ b/contributed_definitions/nyaml/NXcs_mm_obj.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Computer science description of a memory in a memory system. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. +type: group +NXcs_mm_obj(NXobject): + technology(NX_CHAR): + doc: | + Qualifier for the type of random access memory. + # make an enumeration + max_physical_capacity(NX_NUMBER): + doc: | + Total amount of data which the medium can hold. + unit: NX_ANY + # NX_BIT + name(NX_CHAR): + doc: | + Given name to the I/O unit. + (NXfabrication): diff --git a/contributed_definitions/nyaml/NXem_adf.yaml b/contributed_definitions/nyaml/NXem_adf.yaml new file mode 100644 index 0000000000..b7011639e5 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_adf.yaml @@ -0,0 +1,28 @@ +category: base +doc: | + Base class method-specific for annular dark field imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXem_adf(NXem_method): + IMAGE_R_SET(NXimage_r_set): + half_angle_interval(NX_NUMBER): + doc: | + Annulus inner (first value) and outer (second value) half angle. + unit: NX_ANGLE + dim: (2,) + # all information about annular dark field images is composed from + # the NXimage_r_set_em base class diff --git a/contributed_definitions/nyaml/NXem_base.yaml b/contributed_definitions/nyaml/NXem_base.yaml new file mode 100644 index 0000000000..2de8081a8c --- /dev/null +++ b/contributed_definitions/nyaml/NXem_base.yaml @@ -0,0 +1,297 @@ +category: base +# template to be used for an application definition +doc: | + Blue-print of a generic appdef for electron microscopy research formulated as a deep base class. + + This base class combines a method-specific and technical-design-level base class + instance to provide a template for storing parameterized descriptions of + pieces of information collected when performing electron microscopy research. + + The base class here shows all possible branches without making any statements + as to which of these have to be used in an instance. Thereby, the base class + provides a template how to name and structure concepts in a hierarchy + to support finding information and reducing the need for renaming and + restructuring information for a research field where many scientists perform + very specific research but who all also share commonalities like usage of + controlled electron beams, a focus on studies of electron beam matter interaction + to explore physical mechanisms and phenomena, or the desire to characterize materials + using electron microscopy. +# flesh out the description of that to read the docs, because currently the +# description on the NeXus front-page is overwhelming +# considering what we learned from the diataxis workshop we write here a +# specification neither a how to nor a tutorial which explains all the context +# because we address here developers of software +type: group +NXem_base(NXroot): + (NXprogram): + doc: | + A collection of all programs and libraries which are considered relevant + to understand with which software tools this NeXus file instance was + generated. Ideally, to enable a binary recreation from the input data. + + Examples include the name and version of the libraries used to write the + instance. Ideally, the software that writes these :ref:`NXprogram` instances + also includes the version of the set of NeXus classes i.e. the specific + set of base classes, application definitions, and contributed definitions + with which the here described concepts can be resolved. + + For the `pynxtools library `_ + which is used by the `NOMAD `_ + research data management system, it makes sense to store e.g. the GitHub + repository commit and respective submodule references used. + # each NeXus file instance should have a default plot + # however as there are cases when this cannot be assured we cannot + # make the default required, one example is e.g. a NeXus instance + # where scientists just store conventions without a default plot + cs_profiling(NXcs_profiling): + doc: | + The configuration of the I/O writer software (e.g. `pynxtools `_) + which was used to generate this NeXus file instance. + (NXentry): # means ENTRY(NXentry) + \@version(NX_CHAR): + doc: | + An at least as strong as SHA256 hashvalue of the file + which specifies the application definition. + definition(NX_CHAR): + doc: | + NeXus NXDL schema to which this file conforms. + enumeration: [NXem] + experiment_identifier(NXidentifier): + doc: | + Ideally, a (globally) unique persistent identifier + for referring to this experiment. + + An experiment should be understood in that this can be an experiment + in reality or a computer simulation because also the latter is an + experiment (see the Cambridge Dictionary experiment: + *a test done in order to find out something, eg if an idea is correct*). + + The identifier is usually issued by the facility, laboratory, + or the principle investigator. The identifier enables to link + experiments/simulations to e.g. proposals. + experiment_description(NX_CHAR): + doc: | + Free-text description about the experiment. + + Users are strongly advised to parameterize their description of the + experiment by using the respective base classes instead of writing prose + into this field. + + The reason is that such free-text field is difficult to machine-interpret. + The motivation behind keeping this field for now is to learn through + the information entered in this field in how far the current base + classes are incomplete. + start_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information included + when the microscope session started. If the application demands that time + codes in this section of the application definition should only be used + for specifying when the experiment was performed - and the exact + duration is not relevant - this start_time field should be used. + + Often though it is useful to specify a time interval via setting both + a start_time and an end_time because this enables software tools and + users to collect a more detailed bookkeeping of the experiment. + + The user should be aware that even with having both time instances specified, + it may not be possible to infer how long the experiment took or for how + long data were acquired. + + More detailed timing data over the course of the experiment have + to be collected to compute this. These computations can take + advantage of individual time stamps start_time and end_time + in :ref:`NXevent_data_em` instances. + end_time(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC included when + the microscope session ended. See docstring of the start_time field + to see how the start_time and end_time should be used together. + (NXcite): + (NXprogram): + doc: | + The program and eventual software libraries used with which the + NeXus instance was created. For the NOMAD OASIS research data + management system e.g. pynxtools and eventually all modules + if desired. + # the above-description overwrites the default description of the NXprogram base class + # this is composed from the NXprogram base class + # program: + # \@version: + # \@url: + # NXnote and thumbnail dropped for the reason that these are + # arbitrary binary containers without any clear provenance. + (NXserialized): + doc: | + Possibility to store a collection of data artifacts + associated with the experiment. + # using NXserialized here instead of NXnote as the former is more specific + (NXuser): + doc: | + Contact information and eventually details of at least one person + who performed or was involved in the session. This can be the + principle investigator who performed this experiment or the student + who performed the simulation. + Adding multiple users if relevant is recommended. + name(NX_CHAR): + doc: | + Given (first) name and surname of the user. + affiliation(NX_CHAR): + doc: | + Name of the affiliation of the user at the point in time + when the experiment was performed. + address(NX_CHAR): + doc: | + Postal address of the affiliation. + email(NX_CHAR): + doc: | + Email address of the user at the point in time when the experiment + was performed. Writing the most permanently used email is recommended. + identifier(NXidentifier): + doc: | + Service as another mean of identification of a user than by the name. + Examples could be details about an ORCID or social media account of + the user. + telephone_number(NX_CHAR): + doc: | + (Business) (tele)phone number of the user at the point + in time when the experiment was performed. + role(NX_CHAR): + doc: | + Which role does the user have in the place and at the point + in time when the experiment was performed? Technician operating + the microscope, student, postdoc, principle investigator, or guest + are common examples. + sample(NXsample): + # NEW ISSUE: inject the conclusion from the discussion with Andrea + # according to SAMPLE.yaml 0f8df14 2022/06/15 + # ID: -> maps to name + # name: -> short_title + # user: -> not matched right now + # citation: doi ->why relevant, should be solved by RDMS + doc: | + A description of the material characterized in the experiment. + Sample and specimen are threaded as de facto synonyms. + Samples can be real specimens or virtual (see method). + method(NX_CHAR): + doc: | + A qualifier whether the sample is a real one or a + virtual one (in a computer simulation) + enumeration: [experiment, simulation] + # MK:: declared_by_vendor I would rather expect this for a substance + # COMPONENT.yaml + # SUBSTANCE: + # QUANTIFY + identifier(NXidentifier): + doc: | + Ideally, (globally) unique persistent identifier which distinguishes + the specimen from all others and especially the predecessor/origin + from where the specimen was cut. + + This field must not be used for an alias! Instead, use name. + + In cases where multiple specimens were loaded into the microscope, + the identifier has to resolve the specific sample, whose results are + stored by this :ref:`NXentry` instance, because a single NXentry should be + used only for the characterization of a single specimen. + + Details about the specimen preparation should be + stored in resources referring to parent_identifier. + parent_identifier(NXidentifier): + doc: | + Identifier of the sample from which the sample was cut or the string + *None*. The purpose of this field is to support functionalities + for tracking sample provenance via a research data management system. + preparation_date(NX_DATE_TIME): + doc: | + ISO 8601 time code with local time zone offset to UTC information + when the specimen was prepared. + + Ideally, report the end of the preparation, i.e. the last known time + the measured specimen surface was actively prepared. Ideally, this + matches the last timestamp that is mentioned in the digital resource + pointed to by parent_identifier. + + Knowing when the specimen was exposed to e.g. specific atmosphere is + especially required for environmentally sensitive material such as + hydrogen charged specimens or experiments including tracers with a + short half time. Additional time stamps prior to preparation_date + should better be placed in resources which describe but which do not pollute + the description here with prose. Resolving these connected pieces of information + is considered within the responsibility of the research data management + system. + name(NX_CHAR): + doc: | + An alias used to refer to the specimen to please readability for humans. + atom_types(NX_CHAR): + doc: | + List of comma-separated elements from the periodic table that are + contained in the sample. If the sample substance has multiple + components, all elements from each component must be included in + `atom_types`. + + The purpose of the field is to offer research data management systems an + opportunity to parse the relevant elements without having to interpret + these from the resources pointed to by parent_identifier or walk through + eventually deeply nested groups in data instances. + # NEW ISSUE: use Andrea and MarkusK groups for describing the geometry of the sample + thickness(NX_NUMBER): + doc: | + (Measured) sample thickness. + + The information is recorded to qualify if the beam used was likely + able to shine through the specimen. For scanning electron microscopy, + in many cases the specimen is typically thicker than what is + illuminatable by the electron beam. + + In this case the value should be set to the actual thickness of + the specimen viewed for an illumination situation where the nominal + surface normal of the specimen is parallel to the optical axis. + unit: NX_LENGTH + # \@units: nm + # NEW ISSUE: error estimates of the thickness and origin, i.e. how the value was obtained would be useful + # NEW ISSUE: error model + # NEW ISSUE: the KIT/SCC SEM, TEM schemata further qualify samples whether they are conductive e/ibeam sensitive + # etc. The problem with this is that beam sensitivity is too vague but spatiotemporal electron dose integral dependent + # KIT/SCC distinguish further conductivity and magnetic properties. While the motivation is clear, making + # it thus simple is likely problematic when the data entered in such fields remaining qualitative. + # what are good or bad properties, it would make sense though to quantify these values + # this includes the description of eventual plasma cleaning steps, + # just knowing that a sample was plasma cleaned is insufficient, maybe it was not cleaned long enough + # if plasma cleaning is done outside the EM than its certainly history, if it happens inside the EM + # are the ibeam description capabilities not sufficient enough? + density(NX_NUMBER): + # NX_MASS_PER_VOLUME + doc: | + (Measured) density of the specimen. + + For multi-layered specimens this field should only be used to describe + the density of the excited volume. For scanning electron microscopy + the usage of this field is discouraged and instead an instance of an + :ref:`NXinteraction_vol_em` within individual :ref:`NXevent_data_em` + instances can provide a cleaner description of the relevant details + why one may wish to store the density of the specimen. + unit: NX_ANY + description: + doc: | + Discouraged free-text field to provide further detail although adding + parent_identifier and having a working research data management system + should provide this contextualization. + # (NXmonitor): + (NXdata): + (NXcoordinate_system_set): + # link to an instance of an NXinstrument but that is anyway specialized for EM + measurement(NXem_msr): + simulation(NXem_sim): + (NXroi): + doc: | + A region-of-interest analyzed either during or after the session + for which specific processed data generated from the measured or the + simulated data are available. + se(NXem_img): + bse(NXem_img): + ebsd(NXem_ebsd): + eds(NXem_eds): + adf(NXem_adf): + eels(NXem_eels): + correlation(NXem_correlation): + # cl(NXem_cl): diff --git a/contributed_definitions/nyaml/NXem_conventions.yaml b/contributed_definitions/nyaml/NXem_conventions.yaml new file mode 100644 index 0000000000..7835d9a654 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_conventions.yaml @@ -0,0 +1,296 @@ +category: base +# symbols: +doc: | + Conventions for rotations and coordinate systems to interpret crystal orientation + and other data and results collected with electron microscopy research. + + Documenting explicitly all used conventions and coordinate systems is + the decisive context whereby many results from electron microscopy are + at all interpretable. + +# This base class provides several sets of such assumptions and conventions. +# Further base classes should be defined when specific techniques and methods +# demand further specifications or have specialized demands. NXem_conventions_ebsd +# is an example for such method-specific base class to summarize key conventions +# for Electron Backscatter Diffraction (EBSD). + +# What is could be a best practice for application definition developers +# who would like to describe an electron microscopy case where multiple +# methods and/or detectors are used. In this case one should define a +# method-specific base class like the template NXem_conventions_ebsd. +# Even though this may come at a cost of some duplicated information where +# the same physical detector is used in different ways, i.e. the signal collect +# from the detector is interpreted in a different way. +# As in most cases established types of signal and thus detectors are used +# (secondary electron, backscattered electron, etc.) one could equally use +# just one NXem_conventions base class instance in an application definition +# and use detector_reference_frame as a template. For each method and detector +# one then creates one NXprocess group named detector_reference_frame1, +# detector_reference_frame2, detector_reference_frame3, and so on and so forth +# and adds inside that NXprocess and use the depends_on field. + +# What is considered best practice in an application definition with multiple +# NXentry instances? In this case each NXentry instance should have an own +# NXspecimen instance and thus the NXem_conventions instance should be place +# inside that NXentry. This enables to group multiple experiments on multiple +# samples together without setting a constraint that in all these instances +# the conventions have to be the same. + +# However, best practice is the conventions should be expressed explicitly +# and they should whenever possible be as simple as possible and as few +# as possible to support users with understanding the content of the application +# definition. +type: group +NXem_conventions(NXobject): + # mandatory information about used or + # assumed reference frame and rotation conventions + rotation_conventions(NXobject): + doc: | + Mathematical conventions and materials-science-specific conventions + required for interpreting every collection of orientation data. + rotation_handedness(NX_CHAR): + doc: | + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + enumeration: [undefined, counter_clockwise, clockwise] + rotation_convention(NX_CHAR): + doc: | + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, passive, active] + euler_angle_convention(NX_CHAR): + doc: | + How are Euler angles interpreted given that there are several + choices (e.g. ZXZ, XYZ, etc.) according to convention 4 of + DOI: 10.1088/0965-0393/23/8/083501. + The most frequently used convention is ZXZ which is based on + the work of H.-J. Bunge but other conventions are possible. + enumeration: [undefined, zxz] + axis_angle_convention(NX_CHAR): + doc: | + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, rotation_angle_on_interval_zero_to_pi] + sign_convention(NX_CHAR): + doc: | + Which sign convention is followed when converting orientations + between different parameterizations/representations according + to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, p_plus_one, p_minus_one] + processing_reference_frame(NXcoordinate_system): + doc: | + Details about eventually relevant named directions that may + give reasons for anisotropies. The classical example is cold-rolling + where one has to specify which directions (rolling, transverse, and normal) + align how with the direction of the base vectors of the sample_reference_frame. + type(NX_CHAR): + doc: | + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of coordinate system. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Location of the origin of the processing_reference_frame. + This specifies the location Xp = 0, Yp = 0, Zp = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. rolling direction. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the y-axis base vector, + e.g. transverse direction. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the processing_reference_frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the z-axis base vector, + e.g. normal direction. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the processing_reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + sample_reference_frame(NXcoordinate_system): + doc: | + Details about the sample/specimen reference frame. + type(NX_CHAR): + doc: | + Type of coordinate system and reference frame according to + convention 1 of DOI: 10.1088/0965-0393/23/8/083501. + The reference frame for the sample surface reference is used for + identifying positions on a (virtual) image which is formed by + information collected from an electron beam scanning the + sample surface. We assume the configuration is inspected by + looking towards the sample surface from a position that is + located behind the detector. + Reference DOI: 10.1016/j.matchar.2016.04.008 + The sample surface reference frame has coordinates Xs, Ys, Zs. + In three dimensions these coordinates are not necessarily + located on the surface of the sample as there are multiple + faces/sides of the sample. Most frequently though the coordinate + system here is used to define the surface which the electron + beam scans. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Location of the origin of the sample surface reference frame. + This specifies the location Xs = 0, Ys = 0, Zs = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. longest edge. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the y-axis base vector, + e.g. long edge. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the z-axis base vector, + e.g. shortest edge. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the sample surface reference frame. We assume the configuration + is inspected by looking towards the sample surface from a position + that is located behind the detector. For further information consult + also the help info for the xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + detector_reference_frameID(NXcoordinate_system): + doc: | + Details about the detector reference frame for a specific detector. + \@depends_on(NX_CHAR): + doc: | + Reference to the specifically named :ref:`NXdetector` instance + for which these conventions in this :ref:`NXprocess` group apply + (e.g. /entry1/instrument/detector1). + type(NX_CHAR): + doc: | + Type of coordinate system/reference frame used for + identifying positions in detector space Xd, Yd, Zd, + according to DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of the coordinate system if it is a Cartesian. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Where is the origin of the detector space reference + frame located. This is the location of Xd = 0, Yd = 0, Zd = 0. + Assume regions-of-interest in this reference frame form a + rectangle or cuboid. + Edges are interpreted by inspecting the direction of their + outer unit normals (which point either parallel or antiparallel) + along respective base vector direction of the reference frame. + enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, front_bottom_left, back_top_left, back_top_right, back_bottom_right, back_bottom_left] + x_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. longest edge as some landmark on the detector. + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing x-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. long edge as some landmark on the detector. + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing y-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_alias(NX_CHAR): + doc: | + Name or alias assigned to the x-axis base vector, + e.g. short edge as some landmark on the detector. + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing z-axis base vector of + the detector space reference frame. We assume the configuration + is inspected by looking towards the sample surface from a + position that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + # conventions specific for EBSD + (NXem_conventions_ebsd): \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml b/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml new file mode 100644 index 0000000000..1ec180e23f --- /dev/null +++ b/contributed_definitions/nyaml/NXem_conventions_ebsd.yaml @@ -0,0 +1,125 @@ +category: base +# symbols: +doc: | + Base class for method-specific conventions EBSD. + + This base class is expected to be used with :ref:`NXem_conventions`. + + This is the main issue which currently is not in all cases documented + and thus limits the interoperability and value of collected EBSD data. + Not communicating EBSD data with such contextual pieces of information + and the use of file formats which do not store this information is the + key unsolved problem. +type: group +NXem_conventions_ebsd(NXem_conventions): + gnomonic_projection_reference_frame(NXcoordinate_system): + doc: | + Details about the gnomonic projection reference frame. + type(NX_CHAR): + doc: | + Type of coordinate system/reference frame used for identifying + positions in the gnomonic projection space Xg, Yg, Zg + according to DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, cartesian] + handedness(NX_CHAR): + doc: | + Handedness of coordinate system. + enumeration: [right_handed, left_handed] + origin(NX_CHAR): + doc: | + Is the origin of the gnomonic coordinate system located + where we assume the location of the pattern centre. + This is the location Xg = 0, Yg = 0, Zg = 0 according to + reference DOI: 10.1016/j.matchar.2016.04.008. + enumeration: [undefined, in_the_pattern_centre] + x_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" x-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + Different tools assume that different strategies can be used + and are perceived as differently convenient to enter + details about coordinate system definitions. In this ELN users + have to possibility to fill in what they assume is sufficient to + define the coordinate system directions unambiguously. + Software which works with this user input needs to offer parsing + capabilities which detect conflicting input and warn accordingly. + enumeration: [undefined, north, east, south, west, in, out] + y_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" y-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + z_direction(NX_CHAR): + doc: | + Direction of the positively pointing "gnomomic" z-axis base + vector when viewing how the diffraction pattern looks on the + detector screen. We assume the configuration is inspected by + looking towards the sample surface from a position + that is located behind the detector. + For further information consult also the help info for the + xaxis_direction field. + enumeration: [undefined, north, east, south, west, in, out] + pattern_centre(NXprocess): + doc: | + Details about the definition of the pattern centre + as a special point in the gnomonic projection reference frame. + x_boundary_convention(NX_CHAR): + doc: | + From which border of the EBSP (in the detector reference frame) + is the pattern centre's x-position (PCx) measured? + Keywords assume the region-of-interest is defined by + a rectangle. We observe this rectangle and inspect the + direction of the outer-unit normals to the edges of + this rectangle. + enumeration: [undefined, top, right, bottom, left] + x_normalization_direction(NX_CHAR): + doc: | + In which direction are positive values for PCx measured from + the specified boundary. Keep in mind that the gnomonic space + is in virtually all cases embedded in the detector space. + Specifically, the XgYg plane is defined such that it is + embedded/laying inside the XdYd plane (of the detector + reference frame). + When the normalization direction is the same as e.g. the + detector x-axis direction, we state that we effectively + normalize in fractions of the width of the detector. + + The issue with terms like width and height is that these + degenerate if the detector region-of-interest is square-shaped. + This is why we should better avoid talking about width and height but + state how we would measure distances practically with a ruler and + how we then measure positive distances. + enumeration: [undefined, north, east, south, west] + y_boundary_convention(NX_CHAR): + doc: | + From which border of the EBSP (in the detector reference + frame) is the pattern centre's y-position (PCy) measured? + For further details inspect the help button of + xaxis_boundary_convention. + enumeration: [undefined, top, right, bottom, left] + y_normalization_direction(NX_CHAR): + doc: | + In which direction are positive values for PCy measured from + the specified boundary. + For further details inspect the help button of + xaxis_normalization_direction. + enumeration: [undefined, north, east, south, west] + + # distance_convention: + # doc: | + # How is the third of the three pattern centre parameter values, + # the (distance) parameter DD, normalized. Which convention + # is followed. We are aware that specifying one of the options here + # also implicitly comes with conventions for some of the parameter + # requested in this ELN. For now we would rather like to ask + # the users though to be specific also to learn how such an ELN + # will be used in practice. + # enumeration: [undefined, Bruker, JEOL, FEI, Oxford] diff --git a/contributed_definitions/nyaml/NXem_correlation.yaml b/contributed_definitions/nyaml/NXem_correlation.yaml new file mode 100644 index 0000000000..2acf65ec86 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_correlation.yaml @@ -0,0 +1,191 @@ +category: base +doc: | + Base class to combine different method-specific data in electron microscopy. + + This base class represent a template for documenting correlations + (spatial, temporal) between different method-specific results. +type: group +NXem_correlation(NXem_method): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): + indexing(NXprocess): + doc: | + Details about correlated or logically connected EBSD datasets. + + One important class of such correlated experiments are the so-called + (quasi) in-situ experiments. In this case the same or nearly the same ROI + gets analyzed via a repetitive sequence of thermomechanical treatment, + sample preparation, measurement, on-the-fly-indexing. Phenomena + investigated are recrystallization, strain accumulation, material damage. + Post-processing is required to correlate and reidentify eventual + microstructural features or local ROIs across several orientation maps. + + Another important class of correlated experiments are the so-called + serial-sectioning experiments. Here the same sample is measured + repetitively after polishing each time, to create a stack of + orientation data which can be reconstructed to a + three-dimensional volume ROI. + + Data can be correlated in time, position (spatial), or both (spatiotemporal). + + Spatial correlations between repetitively characterized regions-of-interests + are typically correlated using image registration and alignment algorithms. + For this typically so-called landmarks are used. These can be grains with + a very large size or specific shape, i.e. grains which are qualitatively + different enough to be used as a guide how images are shifted relative to + one another. Other commonly used landmarks are fiducial marks which are + milled into the specimen surface using focus-ion beam milling and/or various + types of indentation methods. + + As far as the same physical region-of-interest is just measured several times, + the additional issue of the depth increment is not a concern. However, correct + assumptions for the depth increment, amount of material removed along the milling + direction is relevant for accurate and precise three-dimensional (serial-sectioning) + correlations. For these studies it can be tricky though to assume or estimate + useful depth increments. Different strategies have been proposed like + calibrations, wedged-shaped landmarks and computer simulation assisted + assumption making. + + Despite the use of landmarks, there are many practical issues which make the + processing of correlations imprecise and inaccurate. Among these are drift + and shift of the specimen, instabilities of the holder, the beam, irrespective + of the source of the drift, charging effects, here specifically causing local + image distortions and rotations which may require special processing algorithms + to reduce such imprecisions. + + Time correlations face all of the above-mentioned issues surplus the challenge + that specific experimental protocols have to be used to ensure the material state + is observed at specific physical time. The example of quasi in-situ characterization + of crystal growth phenomena, a common topic in engineering or modern catalysis research + makes it necessary to consider that e.g. the target value for the desired annealing + temperature is not just gauged based on macroscopic arguments but considers + that transient effects take place. Heating or quenching a sample might thus might + not have been executed under conditions in the interaction volume as they are + documented and/or assumed. + + These issue cause that correlations have an error margin as to how accurately + respective datasets were not only just synced based on the geometry of the + region-of-interests and the time markers but also to asssure which physical + conditions the specimen experienced over the course of the measurements. + + The fourth example of the em_om reference implementation explores the use of the + correlation group with a serial-sectioning datasets that was collected by the + classical Inconel 100 dataset collected by M. D. Uchic and colleagues + (M. Groeber M, Haley BK, Uchic MD, Dimiduk DM, Ghosh S 3d reconstruction and + characterization of polycrystalline microstructures using a fib-sem system data set. + Mater Charac 2006, 57 259–273. 10.1016/j.matchar.2006.01.019M). + + This dataset was specifically relevant in driving forward the implementation + of the DREAM.3D software. DREAM.3D is an open-source software project for + post-processing and reconstructing, i.e. correlating sets of orientation + microscopy data foremost spatially. One focus of the software is the + (post-)processing of EBSD datasets. Another cutting edge tool with similar + scope but a commercial solution by Bruker is QUBE which was developed by + P. Konijnenberg and coworkers. + + Conceptually, software like DREAM.3D supports users with creating linear + workflows of post-processing tasks. Workflows can be instructed via the + graphical user interface or via so-called pipeline processing via command line + calls. DREAM.3D is especially useful because its internal system documents all + input, output, and parameter of the processing steps. This makes DREAM.3D a + good candidate to interface with tools like em_om parser. Specifically, DREAM.3D + documents numerical results via a customized HDF5 file format called DREAM3D. + Workflow steps and settings are stored as nested dictionaries in JSON syntax + inside a supplementary JSON file or alongside the data in the DREAM3D file. + DREAM.3D has a few hundred algorithms implemented. These are called filters + in DREAM.3D terminology. + + Users configure a workflow which instructs DREAM.3D to send the data through + a chain of predefined and configured filters. Given that for each analysis + the filter is documented via its version tags surplus its parameter and setting + via a controlled vocabulary, interpreting the content of a DREAM3D HDF5 file + is possible in an automated manner using a parser. This makes DREAM.3D analyses + repeatable and self-descriptive. A key limitation though is that most frequently + the initial set of input data come from commercial files like ANG. + This missing link between the provenance of these input files, their associated + creation as electron microscope session, is also what NXem_ebsd solves. + + Nevertheless, as this can be solved with e.g. NXem_ebsd we are convinced that + the DREAM.3D and the em_om parser can work productively together to realize + RDMS-agnostic parsing of serial-section analyses. + + The internal documentation of the DREAM.3D workflow also simplifies the + provenance tracking represented by an instance of NXem_ebsd as not every + intermediate results has to be stored. Therefore, the fourth example + focuses on the key result obtained from DREAM.3D - the reconstructed + and aligned three-dimensional orientation map. + + Usually, this result is the starting point for further post-processing + and characterization of structural features. As here orientation microscopy + is insofar scale invariant using DREAM.3D, NXem_ebsd, and em_om should + be useful for different characterization methods, such as EBSD, Transmission + Kikuchi Diffraction (TKD), Automated Crystal Orientation Mapping (ACOM), + Nanobeam Electron Diffraction (using commercial systems like NanoMegas ASTAR) + or open-source implementations of these techniques (such as via pyxem/orix). + + The result of orientation microscopy methods are maps of local orientation + and thermodynamic phase (crystal structure) pieces of information. Virtually + all post-processing of such results for structural features includes again + a workflow of steps which are covered though by the NXms partner application + definition. The respective source of the data in an instance of NXms can + again be a link or reference to an instance of NXem_ebsd to complete the + chain of provenance. + (NXcrystal_structure): + roi(NXdata): + descriptor: + doc: | + Descriptor representing the image contrast. + # \@signal: # data + # \@axes: # [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + # \@signal: + # \@axes: + # \@AXISNAME_indices: + # \@long_name: + title: + doc: | + Title of the default plot. + data(NX_NUMBER): + unit: NX_UNITLESS + doc: | + Descriptor values displaying the ROI. + dim: (n_z, n_y, n_x) + # n_0 slowest 3, n_1 slow 2, n_2 fast 1, rgb triplet is fastest 0 + # in axes fast to fastest + # while for _indices fastest to fast + \@long_name: + doc: | + Descriptor values. + axis_z(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the z-axis. + dim: (n_z,) + \@long_name: + doc: | + Label for the z axis + axis_y(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the y-axis. + dim: (n_y,) + \@long_name: + doc: | + Label for the y axis + axis_x(NX_NUMBER): + unit: NX_LENGTH + doc: | + Calibrated coordinate along the x-axis. + dim: (n_x,) + \@long_name: + doc: | + Label for the x axis + # NEW ISSUE: implement support for filters eventually many of them + # NEW ISSUE: for now only show that data from DREAM3D can be loaded. + # NEW ISSUE: how to handle landmarks + # NEW ISSUE: again an entire set of workflows such as rigid or non-rigid + # image registration etc. + # sequence_index(N0): diff --git a/contributed_definitions/nyaml/NXem_eds.yaml b/contributed_definitions/nyaml/NXem_eds.yaml new file mode 100644 index 0000000000..9a5a97fcd0 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_eds.yaml @@ -0,0 +1,80 @@ +category: base +doc: | + Base class method-specific for energy-dispersive X-ray spectroscopy (EDS/EDX). + + `IUPAC instead of Siegbahn notation `_ should be used. + +# NEW ISSUE: use computational geometry to offer arbitrary scan pattern +# NEW ISSUE: make the binning flexible per scan point +symbols: + # n_p: Number of scan points + n_y: | + Number of pixel along the y direction, the slow direction + n_x: | + Number of pixel along the x direction, the fast direction + n_photon_energy: | + Number of X-ray photon energy (bins), the fastest direction. + n_elements: | + Number of identified elements + n_peaks: | + Number of peaks detected +type: group +NXem_eds(NXem_method): + # NXprocess is composed from NXem_method base class + # SPECTRUM_SET(NXspectrum_set) is composed from NXem_method base class + # for post-processing of/with the above-defined data entries + # including feedback from Christoph Pauly (from MX Uni Saarland, NFDI-MatWerk), + # Sabine Bergmann and Sebastian Brückner (both from FAIRmat, IKZ), + # and Adrien Teutrie, Cecile Hebert (EPFL) + indexing(NXprocess): + doc: | + Details about computational steps how peaks were indexed as elements. + (NXprogram): + doc: | + The program with which the indexing was performed. + PEAK(NXpeak): + doc: | + Name and location of each X-ray line which was indexed as a known ion. + For each ion, an NXion instance should be created which specifies + the origin of the signal. For each ion also the relevant IUPAC notation + X-ray lines should be specified. + (NXion): + energy_range(NX_NUMBER): + doc: | + Associated lower :math:`[e_{min}, e_{max}]` bounds of the + energy which is assumed associated with this peak. + unit: NX_ENERGY + dim: (2,) + energy(NX_NUMBER): + doc: | + Theoretical energy of the line according to IUPAC. + unit: NX_ENERGY + iupac_line_names(NX_CHAR): + doc: | + IUPAC notation identifier of the line which the peak represents. + + This can be a list of IUPAC notations for (the seldom) case that + multiple lines are grouped with the same peak. + dim: (i,) + element_names(NX_CHAR): + doc: | + List of the names of identified elements. + dim: (n_elements,) + IMAGE_R_SET(NXimage_r_set): + doc: | + Individual element-specific EDS/EDX/EDXS/SXES mapping + + A composition map is an image whose intensities for each pixel are the + accumulated X-ray quanta *under the curve(s)* of a set of peaks. + + These element-specific EDS maps are NXimage_r_set instances + and need to be named with the name of the element from the + element_names field. + (NXprocess): + peaks(NX_CHAR): + doc: | + A list of NXpeak instance names whose X-ray quanta + where accumulated for each pixel which yields an element-specific + EDS map. + dim: (n_peaks,) + # everything else is composed from NXimage_r_set diff --git a/contributed_definitions/nyaml/NXem_eels.yaml b/contributed_definitions/nyaml/NXem_eels.yaml new file mode 100644 index 0000000000..4e5c69fe4a --- /dev/null +++ b/contributed_definitions/nyaml/NXem_eels.yaml @@ -0,0 +1,39 @@ +category: base +doc: | + Base class method-specific for Electron Energy Loss Spectroscopy (EELS). +symbols: + n_energy_loss: | + Number of electron energy loss bins. +type: group +NXem_eels(NXem_method): + # NXem_method can offers to keep a SPECTRUM_SET + # NXem_method also has an NXprocess which in this base class can be + # specialized to include EELS-specific post-processing + SPECTRUM_SET(NXspectrum_set): + doc: | + NXspectrum_set_em specialized for EELS. + stack(NXdata): + # \@signal: data_counts + # \@axes: [axis_y, axis_x, axis_energy_loss] + # \@energy_loss_indices: 2 + # \@axis_x_indices: 1 + # \@axis_y_indices: 0 + axis_energy_loss(NX_NUMBER): + unit: NX_ENERGY + dim: (n_energy_loss,) + \@long_name(NX_CHAR): + doc: | + Energy loss. + summary(NXdata): + # \@signal: data_counts + # \@axes: [axis_energy_loss] + # \@energy_loss_indices: 0 + axis_energy_loss(NX_NUMBER): + unit: NX_ENERGY + doc: | + Energy loss. + dim: (n_energy_loss,) + \@long_name(NX_CHAR): + doc: | + Energy loss. + # collection if needed can be composed from NXspectrum_set diff --git a/contributed_definitions/nyaml/NXem_img.yaml b/contributed_definitions/nyaml/NXem_img.yaml new file mode 100644 index 0000000000..8c257d121a --- /dev/null +++ b/contributed_definitions/nyaml/NXem_img.yaml @@ -0,0 +1,25 @@ +category: base +doc: | + Base class for method-specific generic imaging. + + In the majority of cases simple d-dimensional regular scan patterns are used + to probe a region-of-interest (ROI). Examples can be single point aka spot + measurements, line profiles, or (rectangular) surface mappings. + The latter pattern is the most frequently used. + + For now the base class provides for scans for which the settings, + binning, and energy resolution is the same for each scan point. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXem_img(NXem_method): + imaging_mode(NX_CHAR): + doc: | + Which imaging mode was used? + enumeration: [secondary_electron, backscattered_electron] + IMAGE_R_SET(NXimage_r_set): diff --git a/contributed_definitions/nyaml/NXem_method.yaml b/contributed_definitions/nyaml/NXem_method.yaml new file mode 100644 index 0000000000..afe91de973 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_method.yaml @@ -0,0 +1,21 @@ +category: base +doc: | + Base class to describe specific analysis methods in electron microscopy. + + This base class represent a template how specialized, deep, and method-specific + base classes can be defined with which an (NXem) application + definition gets equipped with specific groups to document method-specific + processing steps and report analyzed quantities. + + The template base class name :ref:`NXem_method` needs to be changed for each + method e.g. :ref:`NXem_adf`, :ref:`NXem_ebsd`, :ref:`NXem_eels`, :ref:`NXem_eds`. +# :ref:`NXem_se`, :ref:`NXem_bse`. +type: group +NXem_method(NXobject): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): + IMAGE_R_SET(NXimage_r_set): + IMAGE_C_SET(NXimage_c_set): + SPECTRUM_SET(NXspectrum_set): diff --git a/contributed_definitions/nyaml/NXem_msr.yaml b/contributed_definitions/nyaml/NXem_msr.yaml new file mode 100644 index 0000000000..16c349ca58 --- /dev/null +++ b/contributed_definitions/nyaml/NXem_msr.yaml @@ -0,0 +1,63 @@ +category: base +doc: | + Base class for collecting a session with a real electron microscope. + + For collecting data and experiments which are simulations of an + electron microscope use the :ref:`NXem_sim` base class. +type: group +NXem_msr(NXem_method): + em_lab(NXinstrument): + doc: | + (Meta)data of the microscope and the lab in which it stands. + + This em_lab group differs from potential em_lab groups inside + :ref:`NXevent_data_em` instances in that here the more static descriptions + are kept while changing, i.e. time-dependent pieces of information are + logged, via the em_lab group inside the desired number of instances + of NXevent_data_em. + + While using an :ref:`NXevent_data_em` instance, users should store only those + settings about a component which are relevant to understand the current + state of the component. Here, current means for the time interval which + the event covers (as it is detailed via start_time and end_time) timestamps. + + For example it is not relevant to store in each :ref:`NXevent_data_em` + electron_source group again the details of the gun type and the manufacturer + but only the high-voltage value and that only if it is different from the value + that is specified in the em_lab section for the static settings. + + In effect, this defines an information inference hierarchy which starts + in an individual :ref:`NXevent_data_em` instance followed by a probing of the + static section. + instrument_name(NX_CHAR): + doc: | + Given name of the microscope at the hosting institution. + This is an alias. Examples could be NionHermes, Titan, JEOL, + Gemini, etc. + location(NX_CHAR): + doc: | + Location of the lab or place where the instrument is installed. + Using GEOREF is preferred. + (NXfabrication): + (NXchamber): + (NXebeam_column): + (NXibeam_column): + (NXoptical_system_em): + (NXdetector): + doc: | + Description of the type of the detector. + + Electron microscopes have typically multiple detectors. + Different technologies are in use like CCD, scintillator, + direct electron, CMOS, or image plate to name but a few. + local_name(NX_CHAR): + doc: | + Instrument-specific alias/name + # it is unfortunate that for NXdetector there are already many places + # how one can specify details which could equally end up in fabrications + # we should give better guidance which option to use, pr to niac + # (NXfabrication): + (NXpump): + (NXstage_lab): + (NXevent_data_em_set): +# (NXevent_data_em): diff --git a/contributed_definitions/nyaml/NXem_sim.yaml b/contributed_definitions/nyaml/NXem_sim.yaml new file mode 100644 index 0000000000..81fe20db1b --- /dev/null +++ b/contributed_definitions/nyaml/NXem_sim.yaml @@ -0,0 +1,34 @@ +category: base +doc: | + Base class for simulating electron microscopy relevant beam-matter interaction. + + The concept behind this base class is to keep it as generic as possible + that simulations of electron/ion beam interaction with matter can be + represented. This base class is envisioned as the twin of the :ref:`NXem_msr` + base class. + + It is an attempt to test the idea if at some point one might even use the + same base class template to describe measurements and computer simulations + of electron microscopy. This idea is attractive because the only practical + difference between a description of a measurement with a microscope and a + computer simulation is that the latter is typically a substantially simplified + representation of the real microscope surplus the focus of the research + in such cases on specific questions. + + Such simplification can be with respect to the optical setup, typically the + ignoring of the fact that the electron beam is produced by a complex setup + of lenses while in simulations often single Einzel lenses are considered. + Dynamics of the environment like temperature fluctuation in a lab, vibrations, + users, and multiple detectors are typically either ignored or reduced in + complexity and number and coming with idealizations to keep the simulations + focused on the specific reason questions and efficiently numerically executable. +# abTEM and other simulation packages, TEMgym, etc. +type: group +NXem_sim(NXem_method): + simulation(NXprocess): + doc: | + Details about the simulation. + # sequence_index(N): + (NXprogram): + (NXcg_geodesic_mesh): + (NXimage_r_set_diff): diff --git a/contributed_definitions/nyaml/NXimage_c_set.yaml b/contributed_definitions/nyaml/NXimage_c_set.yaml new file mode 100644 index 0000000000..8dcd85706d --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_c_set.yaml @@ -0,0 +1,140 @@ +category: base +doc: | + Specialized base class container for reporting a set of images in reciprocal space. + + In practice, complex numbers are encoded via some formatted pair of real values. + Typically, fast Algorithms for computing Fourier Transformations (FFT) are + used to encode images in reciprocal (frequency) space. FFT libraries are used + for implementing the key functionalities of these mathematical operations. + + Different libraries use different representations and encoding of the + image computed. Details can be found in the respective sections of the + typical FFT libraries: + + * `FFTW by M. Frigo and S. G. Johnson `_ + * `Intel MKL by the Intel Co. `_ + * `cuFFT by the NVidia Co. `_ + + Users are strongly advised to inspect carefully which specific conventions + their library uses to be able to store and modify the implementation of their + code so that the serialized representations as it is detailed + here for NeXus matches with their intention. + + One- and two-dimensional FFTs should use the stack(NXdata) instances. + Three-dimensional FFTs should use the hyperstack(NXdata) instances. +symbols: + n_images: | + Number of images in the (hyper)stack. + n_k: | + Number of pixel per image in the slowest direction. + n_j: | + Number of pixel per image in the slow direction. + n_i: | + Number of pixel per image in the fast direction. +type: group +NXimage_c_set(NXimage_set): + # details about the FFT library used could for instance be stored in the + # NXprocess group which the NXimage_c_set base class can borrow from its + # NXimage_set parent base class + # process information are composable from the NXimage_set base class + stack(NXdata): + doc: | + Image stack. + real(NX_NUMBER): + doc: | + Image intensity of the real part. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + imag(NX_NUMBER): + doc: | + Image intensity of the imaginary part. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + magnitude(NX_NUMBER): + doc: | + Magnitude of the image intensity. + unit: NX_UNITLESS + dim: (n_images, n_j, n_i) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + # axis_k(NX_NUMBER): + # doc: | + # Pixel coordinate center along k direction. + # unit: NX_ANY # NX_RECIPROCAL_LENGTH + # dim: (n_k,) + # \@long_name(NX_CHAR): + # doc: | + # Coordinate along j direction. + axis_j(NX_NUMBER): + doc: | + Pixel coordinate center along j direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_i(NX_NUMBER): + doc: | + Pixel coordinate center along i direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Coordinate along i direction. + + hyperstack(NXdata): + doc: | + Image hyperstack. + real(NX_NUMBER): + doc: | + Image intensity of the real part. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + imag(NX_NUMBER): + doc: | + Image intensity of the imaginary part. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + magnitude(NX_NUMBER): + doc: | + Magnitude of the image intensity. + unit: NX_UNITLESS + dim: (n_images, n_k, n_j, n_i) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + axis_k(NX_NUMBER): + doc: | + Pixel coordinate center along k direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_k,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_j(NX_NUMBER): + doc: | + Pixel coordinate center along j direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_j,) + \@long_name(NX_CHAR): + doc: | + Coordinate along j direction. + axis_i(NX_NUMBER): + doc: | + Pixel coordinate center along i direction. + unit: NX_ANY # NX_RECIPROCAL_LENGTH + dim: (n_i,) + \@long_name(NX_CHAR): + doc: | + Coordinate along i direction. diff --git a/contributed_definitions/nyaml/NXimage_r_set.yaml b/contributed_definitions/nyaml/NXimage_r_set.yaml new file mode 100644 index 0000000000..f0437e6e6f --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_r_set.yaml @@ -0,0 +1,45 @@ +category: base +doc: | + Specialized base class container for reporting a set of images in real space. +symbols: + n_images: | + Number of images in the stack. + n_y: | + Number of pixel per image in the slow direction. + n_x: | + Number of pixel per image in the fast direction. +type: group +NXimage_r_set(NXimage_set): + # process information are composable from the NXimage_set base class + stack(NXdata): + doc: | + Image (stack). + intensity(NX_NUMBER): + doc: | + Image intensity values. + unit: NX_UNITLESS + dim: (n_images, n_y, n_x) + axis_image_identifier(NX_INT): + doc: | + Image identifier + unit: NX_UNITLESS + dim: (n_images,) + \@long_name(NX_CHAR): + doc: | + Image identifier. + axis_y(NX_NUMBER): + doc: | + Pixel coordinate center along y direction. + unit: NX_LENGTH + dim: (n_y,) + \@long_name(NX_CHAR): + doc: | + Coordinate along y direction. + axis_x(NX_NUMBER): + doc: | + Pixel coordinate center along x direction. + unit: NX_LENGTH + dim: (n_x,) + \@long_name(NX_CHAR): + doc: | + Coordinate along x direction. diff --git a/contributed_definitions/nyaml/NXimage_r_set_diff.yaml b/contributed_definitions/nyaml/NXimage_r_set_diff.yaml new file mode 100644 index 0000000000..79ca31b168 --- /dev/null +++ b/contributed_definitions/nyaml/NXimage_r_set_diff.yaml @@ -0,0 +1,123 @@ +category: base +doc: | + Base class specialized for reporting a cuboidal stack of diffraction pattern. + + Diffraction pattern, whether they were simulated or measured are the raw data + for computational workflows to characterize the phase and orientation + of crystalline regions in matter. + + Steps of post-processing the diffraction patterns should be documented using + method-specific specialized base classes. All eventual post-processing of + resulting orientation maps (2D or 3D) should be documented via :ref:`NXms_recon`. + + To implement an example how this base class can be used we focused in FAIRmat + on Kikuchi diffraction pattern here specifically the research community + of Electron Backscatter Diffraction (EBSD). + + For this reason, this base class and related :ref:`NXem_base` classes extend the + work of `M. A. Jackson et al. `_ + (one of the developers of DREAM.3D) and the H5OINA public file format developed by + `P. Pinard et al. `_ with Oxford Instruments. + + Kikuchi pattern are typically collected with FIB/SEM microscopes, + for two- and three-dimensional orientation microscopy. + + For a detailed overview of these techniques see e.g. + + * `M. A. Groeber et al. `_ + * `A. J. Schwartz et al. `_ + * `P. A. Rottman et al. `_ + + Serial-sectioning demands a recurrent sequence of ion milling and measuring. + This suggests that each serial section is at least an own NXevent_data_em + instance. The three-dimensional characterization as such demands a computational + step where the maps for each serial section get cleaned, aligned, and registered + into an image stack. This image stack represents a digital model of the + inspected microstructural volume. Often this volume is called a (representative) + volume element (RVE). Several software packages exists for performing + these post-processing tasks. + + This example may inspire users of other types of diffraction methods. +symbols: + n_sc: | + Number of scanned points. Scan point may have none, one, or more pattern. + n_p: | + Number of diffraction pattern. + n_y: | + Number of pixel per pattern in the slow direction. + n_x: | + Number of pixel per pattern in the fast direction. +type: group +NXimage_r_set_diff(NXimage_r_set): + pattern_type(NX_CHAR): + doc: | + Category which type of diffraction pattern is reported. + enumeration: [kikuchi] + stack(NXdata): + doc: | + Collected diffraction pattern as an image stack. As raw and closest to the + first retrievable measured data as possible, i.e. do not use this + container to store already averaged, filtered or whatever post-processed + pattern unless these are generated unmodifiably in such manner by the + instrument given the way how the instrument and control software + was configured for your microscope session. + scan_point_identifier(NX_INT): + doc: | + Array which resolves the scan point to which each pattern belongs. + + Scan points are evaluated in sequence starting from scan point zero + until scan point n_sc - 1. Evaluating the cumulated of this array + decodes which pattern in intensity belongs to which scan point. + + Take an example with three scan points: The first scan point has one + pattern, the second has three pattern, the last scan point has no + pattern. In this case the scan_point_identifier are 0, 1, 1, 1. + The length of the scan_point_identifier array is four because four + pattern were measured in total. + + In most cases usually one pattern is averaged by the detector for + some amount of time and then reported as one pattern. + unit: NX_UNITLESS + dim: (n_p,) + intensity(NX_NUMBER): + doc: | + Intensity of the diffraction pattern. + unit: NX_UNITLESS + dim: (n_p, n_y, n_x) + # n_p fast 2, n_y faster 1, n_x fastest 0 + # in axes fast to fastest + # while for _indices fastest to fast + \@long_name(NX_CHAR): + doc: | + Pattern intensity + # \@signal: intensity + # \@axes: [pattern_identifier, ypos, xpos] + # \@xpos_indices: 0 + # \@ypos_indices: 1 + # \@pattern_identifier_indices: 2 + pattern_identifier(NX_INT): + doc: | + Pattern are enumerated starting from 0 to n_p - 1. + unit: NX_UNITLESS + dim: (n_p,) + \@long_name(NX_CHAR): + doc: | + Pattern identifier + # the following fields are taken from the NXimage_r_set base class + # axis_y(R): + # axis_x(R): + +# If we envision a (knowledge) graph for EBSD it consists of individual sub-graphs +# which convey information about the specimen preparation, the measurement of +# the specimen in the electron microscope, the indexing of the collected +# Kikuchi pattern stack, eventual post-processing of the indexed orientation +# images via similarity grouping algorithms to yield (grains, texture). +# Conceptually, these post-processing steps are most frequently serving +# the idea how can one reconstruct so-called microstructural features +# (grains, phases, interfaces) to infer material properties. +# In practice this calls for workflows which quantify correlations between +# the spatial arrangement of the microstructural features, the individual +# (thermodynamic, chemo-mechanical) properties of the features with the +# properties of materials at a coarser scale. +# With NXem and related NXms base classes we propose a covering +# and general solution how to handle such (meta)data with NeXus. diff --git a/contributed_definitions/nyaml/NXms_ipf.yaml b/contributed_definitions/nyaml/NXms_ipf.yaml new file mode 100644 index 0000000000..11bfc59831 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_ipf.yaml @@ -0,0 +1,299 @@ +category: base +doc: | + Base class to store an inverse pole figure (IPF) mapping (IPF map). +symbols: + # how to make this optional + n_z: | + Number of pixel along the z slowest direction. + n_y: | + Number of pixel along the y slow direction. + n_x: | + Number of pixel along the x fast direction. + n_rgb: | + Number of RGB values along the fastest direction, always three. + d: | + Dimensionality of the mapping (either 2 or 3). +type: group +NXms_ipf(NXprocess): + \@depends_on(NX_CHAR): + doc: | + Reference to the coordinate system whereby the projection_direction is defined. + + If the field depends_on is not provided but a parent of the instance + of this base class or its specialization defines an :ref:`NXcoordinate_system_set` + and exactly one :ref:`NXcoordinate_system`, the reference points to this system. + + If nothing is provided and none of the above-mentioned references pointing + in a parent, McStas is assumed. + projection_direction(NX_NUMBER): + doc: | + The direction along which orientations are projected. + unit: NX_UNITLESS + dim: (3,) + input_grid(NXcg_grid): + doc: | + Details about the original grid. + + Here original grid means the one onto which the IPF map was computed + when exported from the tech partner's file format representation. + output_grid(NXcg_grid): + doc: | + Details about the grid onto which the IPF is recomputed. + + Rescaling the visualization of the IPF map may be needed to enable + visualization in specific software tools like H5Web. + The value specifies the fractional change of the spacing between + the original mapping and the scaled one. + interpolation(NX_CHAR): + doc: | + How where orientation values at the location of the output grid + positions computed. + + Nearest neighbour means the orientation of the closed (Euclidean distance) + grid point of the input_grid was taken. + enumeration: [nearest_neighbour] + map(NXdata): + doc: | + Inverse pole figure mapping. + + Default inverse pole figure (IPF) plot of the data specific for each + phase. No ipf_mapID instances for non-indexed scan points as these are + by definition assigned the null phase with phase_identifier 0. + Inspect the definition of :ref:`NXcrystal_structure` and its field + phase_identifier for further details. + + Details about possible regridding and associated interpolation + during the computation of the IPF map visualization can be stored + using the input_grid, output_grid, and interpolation fields. + + The main purpose of this map is to offer a normalized default representation + of the IPF map for consumption by a research data management system (RDMS). + This is aligned with the first aim of :ref:`NXms_ipf`, to bring colleagues and + users of IPF maps together to discuss which pieces of information + need to be stored together. We are convinced a step-by-step design and + community-driven discussion about which pieces of information should + and/or need to be included is a practical strategy to work towards an + interoperable description and data model for exchanging IPF maps as specific + community-accepted tools to convey orientation maps. + + With this design the individual RDMS solutions and tools can still continue + to support specific custom data analyses workflow and routes but at least + there is one common understanding which enables also those users who are + not necessarily experts in all the details of the underlying techniques + can understand and thus eventually judge if the dataset is worth to be + reused or repurposed. + # \@signal: data + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + data(NX_NUMBER): + # assume a mapping with step size 0.5 micron + # we need to distinguish + # pixel position, i.e. 0, 1, 2, 3, unit px + # answers in which pixel on the map but map is disconnected from sample surface context + # calibrated pixel position 0., 0.5, 1.0, 1.5, unit micron + # answers in addition physical dimensions (relevant to get crystal extent etc.) but still disconnected from sample surface context + # calibrated pixel position including the offset of the original coordinate system + # answers everything would enable one to point if still in the microscope where on the sample surface each pixel is located + # tech partners oftentimes do not report to more than calibrated pixel position + doc: | + Inverse pole figure color code for each map coordinate. + unit: NX_UNITLESS + dim: (n_y, n_x, 3) # | (n_z, n_y, n_x, 3) + axis_z(NX_NUMBER): + doc: | + Pixel center coordinate calibrated for step size along the z axis of the map. + unit: NX_LENGTH + dim: (n_z,) + # \@long_name(NX_CHAR): + axis_y(NX_NUMBER): + unit: NX_LENGTH + doc: | + Pixel center coordinate calibrated for step size along the y axis of the map. + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + unit: NX_LENGTH + doc: | + Pixel center coordinate calibrated for step size along the x axis of the map. + dim: (n_x,) + # \@long_name(NX_CHAR): + # title: + legend(NXdata): + doc: | + The color code which maps colors into orientation into the fundamental zone. + + For each stereographic standard triangle (SST), i.e. a rendering of the + fundamental zone of the crystal-symmetry-reduced orientation space + SO3, it is possible to define a color model which assigns each point in + the fundamental zone a color. + + Different mapping models are used. These implement (slightly) different + scaling relations. Differences exist across representations of tech partners. + + Differences are which base colors of the RGB color model are placed in + which extremal position of the SST and where the white point is located. + + For further details see: + + * [G. Nolze et al.](https://doi.org/10.1107/S1600576716012942) + * Srikanth Patala and coworkers"'" work and of others. + + Details are implementation-specific and not standardized yet. + + Given that the SST has a complicated geometry, it cannot yet be + visualized using tools like H5Web, which is why for now the matrix + of a rasterized image which is rendered by the backend tool gets + copied into an RGB matrix to offer a default plot. + # \@signal: data + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + data(NX_NUMBER): + # hehe, but can be larger than one but could also be an NX_DIMENSIONLESS ! + doc: | + Inverse pole figure color code for each map coordinate. + unit: NX_UNITLESS + dim: (n_y, n_x, 3) + axis_y(NX_NUMBER): + doc: | + Pixel along the y-axis. + unit: NX_UNITLESS + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + doc: | + Pixel along the x-axis. + unit: NX_UNITLESS + dim: (n_x,) + # \@long_name(NX_CHAR): + # title: + +# keep this for now for FAIRmat internal documentation +# It is important to mention that we cannot assume, at least for now, +# that the parser which writes to an NXem_ebsd-compliant file is also +# responsible or capable at all of computing the inverse pole figure +# color keys and maps itself. This cannot be assumed working because +# this mapping of orientation data uses involved mathematical algorithms +# and functions which not every tools used in the EBSD community is capable +# of using or is for sure not using in exactly the same way. +# +# Currently, we assume it is the responsibilty of the tool used which +# generated the data under on_the_fly_indexing to compute these +# plots and deliver these to the parser. +# +# Specific case studies have been explored by the experiment team of +# Area B of the FAIRmat project to realize and implement such mapping. +# +# The first case study uses the H5OINA format and the pyxem/orix library. +# As orix is a Python library, the coloring is performed by the em_om parser. +# +# The second case study uses MTex and its EBSD color coding model. +# As MTex is a Matlab tool, an intermediate format is written from MTex +# first which stores these pieces of information. The parser then pulls +# these data from the intermediate Matlab-agnostic representation and +# supplements the file with missing pieces of information as it is +# required by NXem_ebsd. +# +# The third case study shows how a generic set of Kikuchi pattern +# can be loaded with the em_om parser. The pattern are loaded directly +# from a ZIP file and mapped to an simulation image section for now. +# +# The fourth case study uses the DREAM.3D package which provides an own +# set of EBSD data post-processing procedures. DREAM.3D documents the +# processing steps with a pipeline file which is stored inside DREAM.3D +# output files. In this case study, the parser reads the DREAM.3D file +# and maps data relevant from the perspective of NXem_ebsd plus adds +# relevant IPF color maps as they were computed by DREAM.3D. +# Given that in this case the origin of the data is the DREAM.3D file +# again provenance is kept and more details can be followed upon when +# resolving origin. +# +# These examples offer a first set of suggestions on how to make EBSD +# data injectable into research data management system using schemes +# which themselves are agnostic to the specific RDMS and interoperable. +# Steps of collecting the raw data and post-processing these with custom +# scripts like MTex or commercial tools so far are mainly undocumented. +# The limitation is that a program which consumes results or dump files +# from these tools may not have necessarily all the sufficient information +# available to check if the injected orientation data and color models +# are matching the conventions which a user or automated system has +# injected into an electronic lab notebook from which currently the em_om +# parser collects the conventions and stores them into this NXem_ebsd instance. +# The immediate benefit of the here presented NXem_ebsd concept though +# is that the conventions and reference frame definitions are expected +# in an ELN-agnostic representation to make NXem_ebsd a generally useful +# data scheme for EBSD. +# +# Ideally, the em_om parser would load convention-compliant EBSD data +# and use subsequently a community library to transcode/convert orientation +# conventions and parameterized orientation values. Thereafter, convention- +# compliant default plot(s) could be created that would be truely interoperable. +# +# However, given the variety of post-processing tools available surplus +# the fact that these are not usually executed along standardized +# post-processing workflows which perform exactly the same algorithmic steps, +# this is currently not a practically implementable option. Indeed, first +# developers who wish to implement this would first have to create a library +# for performing such tasks, mapping generally between conventions, +# i.e. map and rotate coordinate systems at the parser level. +# +# The unfortunate situation in EBSD is that due to historical reasons +# and competitive strategies, different players in the field have +# implemented (slightly) different approaches each of which misses +# some part of a complete workflow description which is behind EBSD analyses: +# Sample preparation, measurement, indexing, post-processing, paper... +# +# The here exemplified default plot do not so far apply relevant rotations +# but takes the orientation values as they come from the origin and using +# coloring them as they come. It is thus the scientists responsibility to +# enter and check if the respective dataset is rotation-conventions-wise +# consistent and fit for a particular task. +# +# Ideally, with all conventions defined it can be possible to develop +# a converter which rotates the input data. This application definition +# does not assume this and users should be aware of this limitation. +# +# The key point is that the conventions however are captured and this is +# the most important step to the development of such a generic transcoder +# for creating interoperable EBSD datasets. +# +# Currently the conventions remain in the mind or manual lab book of the +# respective scientists or technicians instead of getting stored and +# communicated with research papers that are written based on +# specific dataset, i.e. database entries. +# +# The default gridded representation of the data should not be +# misinterpreted as the only possible way how EBSD data and OIM +# maps can be created! +# +# Indeed, the most general case is that patterns are collected for +# scan points. The scan generator of an electron microscope is instructed +# to steer the beam in such a way across the specimen surface that the +# beam illuminates certain positions for a certain amount time (usually +# equally-spaced and spending about the same amount of time at each +# position). +# +# Therefore, scan positions can be due to such regular flight plans and +# represent sampling on lines, line stacks, rectangular regions-of- +# interests, but also could instruct spiral, random, or adaptive scans +# instead of tessellations with square or hexagonal pixels. +# +# The majority of EBSD maps is though is reporting results for a regular +# grid (square, hexagon). What matters though in terms of damage induced +# by the electron beam and signal quality is the real electron dose +# history, i.e. for how long the beam exposed which location of the +# specimen. Especially when electron charging occurs (i.e. an excess +# amount of charge accumulates due to e.g. poor conducting away of this +# charge or an improper mounting, too high dose, etc. such details are +# relevant. +# +# Specifically, the default visualization is an inverse pole-figure (IPF) +# map with the usual RGB color coding. Different strategies and +# normalization schemes are in use to define such color coding. +# +# Finally, we should mention that each ipf_map represents data for +# scan points indexed as one phase. The alias/name of this phase should +# be stored in phase_name, the phase_identifier give an ID which must +# not be zero as this value is reserved for non-indexed / null model scan +# points. \ No newline at end of file diff --git a/contributed_definitions/nyaml/NXms_ipf_set.yaml b/contributed_definitions/nyaml/NXms_ipf_set.yaml new file mode 100644 index 0000000000..a783655a24 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_ipf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_ipf` instances. + + A collection of inverse pole figure approximations. +# symbols: +type: group +NXms_ipf_set(NXprocess): + (NXms_ipf): diff --git a/contributed_definitions/nyaml/NXms_mtex_config.yaml b/contributed_definitions/nyaml/NXms_mtex_config.yaml new file mode 100644 index 0000000000..b8fee982d5 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_mtex_config.yaml @@ -0,0 +1,187 @@ +category: base +doc: | + Base class to store the configuration when using the MTex/Matlab software. + + MTex is a Matlab package for texture analysis used in the Materials and Earth Sciences. + See `R. Hielscher et al. `_ and + the `MTex source code `_ for details. +type: group +NXms_mtex_config(NXobject): + conventions(NXcollection): + doc: | + Reference frame and orientation conventions. + Consult the `MTex docs `_ for details. + x_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + # check against v5.12 + z_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + a_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + b_axis_direction(NX_CHAR): + doc: | + TODO with MTex developers + # enumeration: + euler_angle(NX_CHAR): + doc: | + TODO with MTex developers + enumeration: [unknown, undefined, bunge] + plotting(NXcollection): + doc: | + Settings relevant for generating plots. + font_size(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + inner_plot_spacing(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + outer_plot_spacing(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + marker_size(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY + figure_size(NX_NUMBER): + doc: | + TODO with MTex developers + show_micron_bar(NX_BOOLEAN): + doc: | + True if MTex renders a scale bar with figures. + show_coordinates(NX_BOOLEAN): + doc: | + True if MTex renders a grid with figures. + pf_anno_fun_hdl: + doc: | + Code for the function handle used for annotating pole figure plots. + color_map(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_UNITLESS + dim: (i, 3) + default_color_map(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_UNITLESS + dim: (i, 3) + # phase_color_order: + # doc: | + # TODO with MTex developers + # unit: NX_UNITLESS + # dim: (i,) + color_palette(NX_CHAR): + degree_char(NX_CHAR): + doc: | + TODO with MTex developers + arrow_char(NX_CHAR): + doc: | + TODO with MTex developers + marker(NX_CHAR): + doc: | + TODO with MTex developers + marker_edge_color(NX_CHAR): + doc: | + TODO with MTex developers + marker_face_color(NX_CHAR): + doc: | + TODO with MTex developers + hit_test(NX_BOOLEAN): + doc: | + TODO with MTex developers + miscellaneous(NXcollection): + doc: | + Miscellaneous other settings of MTex. + mosek(NX_BOOLEAN): + doc: | + TODO with MTex developers + generating_help_mode(NX_BOOLEAN): + doc: | + TODO with MTex developers + methods_advise(NX_BOOLEAN): + doc: | + TODO with MTex developers + stop_on_symmetry_mismatch(NX_BOOLEAN): + doc: | + TODO with MTex developers + inside_poly(NX_BOOLEAN): + doc: | + TODO with MTex developers + text_interpreter: + numerics(NXcollection): + doc: | + Miscellaneous settings relevant for numerics. + eps(NX_NUMBER): + doc: | + Return value of the Matlab eps command. + unit: NX_UNITLESS + fft_accuracy(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # NX_LENGTH or NX_RECIPROCAL_LENGTH? + max_stwo_bandwidth(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # radiant? + max_sothree_bandwidth(NX_NUMBER): + doc: | + TODO with MTex developers + unit: NX_ANY # radiant? + system(NXcollection): + doc: | + Miscellaneous settings relevant of the system where MTex runs. + memory(NX_NUMBER): + doc: | + TODO with MTex developers + open_gl_bug(NX_BOOLEAN): + doc: | + TODO with MTex developers + save_to_file(NX_BOOLEAN): + doc: | + TODO with MTex developers + path(NXcollection): + doc: | + Collection of paths from where MTex reads information and code. + mtex(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + data(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + cif(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + ebsd(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + pf(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + odf(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + tensor(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + example(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + import_wizard(NX_CHAR): + doc: | + Absolute path to specific component of MTex source code. + pf_extensions(NX_CHAR): + doc: | + List of file type suffixes for which MTex assumes + texture/pole figure information. + ebsd_extensions(NX_CHAR): + doc: | + List of file type suffixes for which MTex assumes EBSD content. + # version as an instance of (NXprogram) one for MTex one for Matlab diff --git a/contributed_definitions/nyaml/NXms_odf.yaml b/contributed_definitions/nyaml/NXms_odf.yaml new file mode 100644 index 0000000000..92ad96589a --- /dev/null +++ b/contributed_definitions/nyaml/NXms_odf.yaml @@ -0,0 +1,99 @@ +category: base +doc: | + Base class to store an orientation distribution function (ODF) computation. +symbols: + n_varphi_one: | + Number of pixel per varphi section plot along the varphi_one fastest direction. + n_capital_phi: | + Number of pixel per varphi section plot along the capital_phi slow direction. + n_varphi_two: | + Number of pixel per varphi section plot along the varphi_two slowest direction. + k: | + Number of local maxima evaluated in the component analysis. +type: group +NXms_odf(NXprocess): + configuration(NXobject): + doc: | + Details about the algorithm used for computing the ODF. + crystal_symmetry_point_group(NX_CHAR): + doc: | + Point group of the crystal structure (International Table of Crystallography) + of the phase for which the here documented phase-dependent ODF was computed. + specimen_symmetry_point_group(NX_CHAR): + doc: | + Point group assumed for processing-induced *sample symmetries*. + (according to International Table of Crystallography). + kernel_halfwidth(NX_NUMBER): + doc: | + Halfwidth of the kernel. + unit: NX_ANGLE + kernel_name(NX_CHAR): + doc: | + Name of the kernel. + resolution(NX_NUMBER): + doc: | + Resolution of the kernel. + unit: NX_ANGLE + kth_extrema(NXobject): + kth(NX_UINT): + doc: | + Number of local maxima evaluated for the ODF. + unit: NX_UNITLESS + # value of kth should be k + location(NX_NUMBER): + doc: | + Euler angle representation of the kth-most maxima of the ODF + in decreasing order of the intensity maximum. + unit: NX_ANGLE + dim: (k, 3) + theta(NX_NUMBER): + doc: | + Disorientation threshold within which intensity of the ODF + is integrated for the component analysis. + unit: NX_ANGLE + volume_fraction(NX_NUMBER): + doc: | + Integrated ODF intensity within a theta-ball of SO3 about + each location as specified for each location in the order + and reported in the order of these locations. + unit: NX_ANY + dim: (k,) + phi_two_plot(NXdata): + doc: | + Visualization of the ODF intensity as orthogonal sections through Euler space. + + This is one example of typical default plots used in the texture + community in Materials Engineering. + + Mind that the Euler space is a distorted space. Therefore, equivalent + orientations show intensity contributions in eventually multiple + locations. + # \@signal: intensity + # \@axes: [varphi_two, capital_phi, varphi_one] + # \@varphi_one_indices: 0 + # \@capital_phi: 1 + # \@varphi_two_indices: 2 + intensity(NX_NUMBER): + doc: | + ODF intensity at probed locations relative to + null model of a completely random texture. + unit: NX_DIMENSIONLESS + dim: (n_varphi_two, n_capital_phi, n_varphi_one) + varphi_one(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\varphi_1` direction. + unit: NX_ANGLE + dim: (n_varphi_one,) + # \@long_name(NX_CHAR): + varphi_two(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\varphi_2` direction. + unit: NX_ANGLE + dim: (n_varphi_two,) + # \@long_name(NX_CHAR): + capital_phi(NX_NUMBER): + doc: | + Pixel center angular position along the :math:`\Phi` direction. + unit: NX_ANGLE + dim: (n_capital_phi,) + # \@long_name(NX_CHAR): diff --git a/contributed_definitions/nyaml/NXms_odf_set.yaml b/contributed_definitions/nyaml/NXms_odf_set.yaml new file mode 100644 index 0000000000..5ea1c4d6cb --- /dev/null +++ b/contributed_definitions/nyaml/NXms_odf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_odf` instances. + + A collection of orientation distribution function approximations. +# symbols: +type: group +NXms_odf_set(NXprocess): + (NXms_odf): diff --git a/contributed_definitions/nyaml/NXms_pf.yaml b/contributed_definitions/nyaml/NXms_pf.yaml new file mode 100644 index 0000000000..09ab12f785 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_pf.yaml @@ -0,0 +1,59 @@ +category: base +doc: | + Base class to store a pole figure (PF) computation. +symbols: + n_y: | + Number of pixel per pole figure in the slow direction. + n_x: | + Number of pixel per pole figure in the fast direction. +type: group +NXms_pf(NXprocess): + configuration(NXobject): + doc: | + Details about the algorithm that was used to compute the pole figure. + crystal_symmetry_point_group(NX_CHAR): + doc: | + Point group of the crystal structure of the phase for which the + here documented phase-dependent pole figure was computed + (according to International Table of Crystallography). + specimen_symmetry_point_group(NX_CHAR): + doc: | + Point group assumed for processing induced *sample symmetries* + (according to International Table of Crystallography). + halfwidth(NX_NUMBER): + doc: | + Halfwidth of the kernel. + unit: NX_ANGLE + miller_indices(NX_CHAR): + doc: | + Miller indices (:math:`(hkl)[uvw]`) to specify the pole figure. + resolution(NX_NUMBER): + doc: | + Resolution of the kernel. + unit: NX_ANGLE + pf(NXdata): + doc: | + Pole figure. + # \@signal: intensity + # \@axes: [axis_y, axis_x] + # \@axis_x_indices: 0 + # \@axis_y_indices: 1 + intensity(NX_NUMBER): + doc: | + Pole figure intensity. + unit: NX_UNITLESS + dim: (n_y, n_x) + axis_y(NX_NUMBER): + doc: | + Pixel center along y direction in the equatorial plane of + a stereographic projection of the unit sphere. + unit: NX_ANY + dim: (n_y,) + # \@long_name(NX_CHAR): + axis_x(NX_NUMBER): + doc: | + Pixel center along x direction in the equatorial plane of + a stereographic projection of the unit sphere. + unit: NX_ANY + dim: (n_x,) + # \@long_name(NX_CHAR): diff --git a/contributed_definitions/nyaml/NXms_pf_set.yaml b/contributed_definitions/nyaml/NXms_pf_set.yaml new file mode 100644 index 0000000000..afd785f157 --- /dev/null +++ b/contributed_definitions/nyaml/NXms_pf_set.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to group multiple :ref:`NXms_pf` instances. + + A collection of pole figure approximations. +# symbols: +type: group +NXms_pf_set(NXprocess): + (NXms_pf): diff --git a/contributed_definitions/nyaml/NXms_recon.yaml b/contributed_definitions/nyaml/NXms_recon.yaml new file mode 100644 index 0000000000..bd6825bacc --- /dev/null +++ b/contributed_definitions/nyaml/NXms_recon.yaml @@ -0,0 +1,315 @@ +# position would need another depends_on the specific coordinate system used, currently we assume McStas +# roi1/ebsd/microstructure1 +category: base +doc: | + Base class to describe discretized (micro)structural features of a material. + + One instance of this base class can be used to describe the current configuration + the base class does not include time-dependent descriptions for the sake of + clarity and because of the fact that virtually all simulations or experiments + probe time by sampling. Therefore, time-dependent state descriptions should + be realized with creating a set of :ref:`NXms_snapshot_set` with instances of + :ref:`NXms_snapshot` using e.g. :ref:`NXms_recon` base class instances. +symbols: + doc: | + The symbols used in the schema to specify e.g. dimensions of arrays. + # in so-called linear intercept analysis we observe + # one-dimensional sections of either projections (see below) + # or true one-dimensional cuts across a volume of material + # n_icept: | + # The number of linear intercepts defined. + # n_c_one: | + # The number of crystal projections segmented by crossing (projected or real) interfaces + # n_i_one: | + # The number of crossings + # two-dimensional projections of characterized in reality three-dimensional objects + # using E. E. Underwood notation + # crystals/grains are projections that are delineated by projections of interface, i.e. interface lines which meet at projections of triple lines i.e. triple "points" + n_c_two: | + The number of crystal projections. + n_i_two: | + The number of interface projections. + n_t_two: | + The number of assumed triple junction projections aka triple points. + # three-dimensional real objects, volumetrically characterized + # crystals are delineated by interfaces that are delineated by triple lines that meet at quad junctions + n_c: | + The number of crystals. + n_i: | + The number of interfaces + n_t: | + The number of triple lines + n_q: | + The number of quadruple junctions. +type: group +NXms_recon(NXobject): + # as e.g. a result of one grain reconstruction with MTex or othe + # grain reconstruction software in commercial tools + # the idea is we may wish to run as many grain reconstructions as we want... + # add details about the processing + configuration(NXprocess): + doc: | + The configuration and parameterization of the reconstruction algorithm + whereby the microstructural features were identified. + # maybe a depends_on what was the input however if the group is injected + # in an roi1/ebsd instance isnt this information implicit? + dimensionality(NX_POSINT): + doc: | + Dimensionality of the analysis. + + This field can be used e.g. by a research data management system + to identify if the described feature set specifies a + one-, two-, or three-dimensional feature set. + unit: NX_UNITLESS + enumeration: [1, 2, 3] + algorithm(NX_CHAR): + doc: | + Which algorithm is used to reconstruct the features. + enumeration: [unknown, disorientation_clustering, fast_multiscale_clustering, markov_chain_clustering] + disorientation_threshold(NX_NUMBER): + doc: | + Threshold to define at which disorientation angle to assume + two crystalline regions have a significant orientation difference + which warrants to argue that there is an interface between the + two regions. + unit: NX_ANGLE + # the result of running one grain reconstruction + # ms_feature_set1 + # we could also enumerate instances ms_feature_setID here because configuration + # may specify a range of different parameter resulting in multiple ms_feature_sets + # dimensionality(N) composed from NXms_feature_set base: + # controlled vocabulary of base class instances to be used to inform about the + # discretization of these features instances to discretize the features + # wherever possible the computational geometry specific instances whose + # purpose is only to support/represent the discretization of the features should + # be separated out from the materials engineering interpretation of what these + # features are, i.e. a grain that is measured with a 2d section ends up + # modelled as an projection of that real 3d grain object + # the model is discretized usign a polyline which models the location of the + # interface at the required here coarse-grained continuum picture + points(NXcg_point_set): + lines(NXcg_polyline_set): + surfaces(NXcg_triangle_set): + volumes(NXcg_polyhedron_set): + + # domain-specific, i.e. microstructural features + # ONE DIMENSIONAL FEATURES + + # TWO DIMENSIONAL FEATURES + crystal_projections(NXms_feature_set): + doc: | + Projections of crystals on the sample surface as typically + characterized with optical or electron microscopy. + \@discretization(NX_CHAR): + doc: | + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Most microscopy techniques support to generate only a two-dimensional + representation (projection) of the characterized material. + + For true volumetric techniques use the specifically + specialized crystals :ref:`NXms_feature_set` instead. + See stereology literature for more details e.g. + E.E. Underwood's book entitled Quantitative Stereology + number_of_crystals(NX_UINT): + doc: | + Number of crystals. + unit: NX_UNITLESS + crystal_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + crystal_identifier(NX_INT): + doc: | + Identifier used for crystals for explicit indexing. + unit: NX_UNITLESS + dim: (n_c_two,) + number_of_phases(NX_UINT): + doc: | + How many phases are distinguished + unit: NX_UNITLESS + phase_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + unit: NX_UNITLESS + phase_identifier(NX_INT): + # \@depends_on(NX_CHAR): + doc: | + Identifier used for phase for explicit indexing. + unit: NX_UNITLESS + dim: (n_c_two,) + # properties of crystal_projections aka grain properties + boundary_contact(NX_BOOLEAN): + doc: | + True, if the crystal makes contact with the edge of the ROI, + false otherwise. + dim: (n_c_two,) + orientation_spread(NX_NUMBER): + doc: | + Average disorientation angle between individual orientation of the + crystal at probed positions (weighted by area of that position) versus + the average disorientation of the crystal. + unit: NX_ANGLE + dim: (n_c_two,) + (NXrotation_set): + area(NX_NUMBER): + doc: | + Calibrated area of surrounded by the polyline about each crystal. + unit: NX_AREA + dim: (n_c_two,) + interface_projections(NXms_feature_set): + # grain boundaries have a network of line-like defects, its explicit description + # often generates unnecessary information duplication and cluttering, + # therefore here a compact and suggestion how to store such data + doc: | + Projections of grain or phase boundaries as typically sectioned + with optical or electron microscopy characterization. + \@discretization(NX_CHAR): + doc: | + Reference to lines(NXcg_polyline_set) which supports the + discretized shape of each cross-sectioned crystal. + + Set of tuples of polyline segments which build the interface. + # topology + # i) Set of pair of crystals sharing an interface + crystals(NX_INT): + doc: | + Set of pairs of crystal_identifier resolved via depends_on which + are adjacent to each interface. + unit: NX_UNITLESS + dim: (n_i_two, 2) + \@depends_on(NX_CHAR): + doc: | + The specific crystal_projections(NXms_feature_set) instance + to resolve crystal identifier. + # ii) Set of pair of topologically connected triple points + triple_points(NX_INT): + doc: | + Set of pairs of triple_point_identifier which the interface connects. + For 2D projections of 3D microstructural features a triple point is + physically only the projection of a triple line. + unit: NX_UNITLESS + dim: (n_i_two, 2) + \@depends_on(NX_CHAR): + doc: | + The specific triple_line_projections(NXms_feature_set) instance + whereby to resolve triple_point identifier. + # alternatively which polyline of adjoining interfaces + # properties, descriptors + length(NX_NUMBER): + doc: | + The length of the interface. + + This is not necessarily the same as the length of the individual + polyline segments whereby the interface is discretized. + + The actual coordinate system whereby the geometry is calibrated + with real physical dimensions is typically documented by the + depends_on attribute of the respective NXcg_primitive_set. + This depends_on attribute should point explicitly to an + instance of a :ref:`NXcoordinate_system` to support users as + much as possible with interpreting how and where the lines are + located in the reference frame. + unit: NX_LENGTH + dim: (n_i_two,) + interface_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + interface_identifier(NX_INT): + doc: | + Identifier for each interface using explicit indexing. + unit: NX_UNITLESS + dim: (n_i_two,) + triple_line_projections(NXms_feature_set): + # only for 2D, quad junction is the equivalent for 3D is not a triple_line + # four alternative descriptors with different strength to specify spatial + # or logical information about the triple junction feature set. + # the explicit description often generating unnecessary information duplication + doc: | + Projections of triple lines as typically characterized with optical + or electron microscopy. + + Mind that most specimens are thermo-chemo-mechanically treated before + they are characterized. Therefore, the projected crystal defects are + have physically no longer the same structure as in the bulk. + + Examples are manifest as effects such as thermal grooving, or relaxation + effects of an intersection between a triple line that is cut + by the specimen surface as these defects are then exposed typically + to a different atmosphere and hence have different thermodynamic boundary + conditions than of their true volumetric defects in the bulk. + \@discretization(NX_CHAR): + doc: | + Reference to points(NXcg_point_set) which supports the + locations of these triple points. + # another view to describe a triple junction is via its topology/connection expressed either via + # i) triplet of interface identifier + number_of_triple_points(NX_UINT): + doc: | + Number of triple points. + unit: NX_UNITLESS + triple_point_identifier_offset(NX_INT): + doc: | + Integer offset whereby the identifier of the first member + of the set differs from zero. + + Identifiers can be defined either implicitly or explicitly. + For implicit indexing identifiers are defined on the interval + :math:`[identifier_offset, identifier_offset + c - 1]`. + unit: NX_UNITLESS + triple_point_identifier(NX_INT): + doc: | + Identifier for each triple point using explicit indexing. + unit: NX_UNITLESS + dim: (n_t_two,) + location(NX_INT): + doc: | + Set of triple point identifiers. + unit: NX_UNITLESS + dim: (n_t_two,) + \@depends_on(NX_CHAR): + doc: | + The relevant points(NXcg_point_set) instance whereby to + resolve interface identifiers. + interfaces(NX_INT): # aka topology or interfaces + doc: | + Set of triplets of identifier of line-like features. + Each triplet resolves which three interface projections + the triple point connects. + unit: NX_UNITLESS + dim: (n_t_two, 3) + \@depends_on(NX_CHAR): + doc: | + The specific interface_projections(NXms_feature_set) + instance whereby to resolve interface identifiers. + # ii) a triplet of line segment identifier whereby the point-like features + # is assumed discretized via three polylines representing interfaces + polylines(NX_INT): + doc: | + Triplet of identifier of polyline segments. Each triplet resolves + which three segments of polyline segments the triple junction connects. + unit: NX_UNITLESS + dim: (n_t_two, 3) + \@depends_on(NX_CHAR): + doc: | + The specific lines(NXcg_polyline_set) instance to resolve + polyline segments. + # the difference in the interpretation of interfaces and polylines + # is that the interface resolves interface (e.g. phase boundary names) + # while polylines resolves segments within the set of named geometric primitive + # instances! + # add all sort of other qualitative or quantitive descriptors (triple junction + # energy, volume etc), i.e properties of that triple point diff --git a/contributed_definitions/nyaml/NXroi.yaml b/contributed_definitions/nyaml/NXroi.yaml new file mode 100644 index 0000000000..a8ba2426ad --- /dev/null +++ b/contributed_definitions/nyaml/NXroi.yaml @@ -0,0 +1,9 @@ +category: base +doc: | + Base class to describe a region-of-interest analyzed. +type: group +NXroi(NXobject): + (NXprocess): + doc: | + Details about processing steps. + sequence_index(NX_INT): diff --git a/manual/source/classes/contributed_definitions/icme-structure.rst b/manual/source/classes/contributed_definitions/icme-structure.rst index b21ad199e5..07aa6ee4e1 100644 --- a/manual/source/classes/contributed_definitions/icme-structure.rst +++ b/manual/source/classes/contributed_definitions/icme-structure.rst @@ -19,19 +19,22 @@ a design strategy and workflow whereby physics-based modelling of microstructure evolution is used to understand the relations between the microstructure and its technologically relevant descriptors to understand and tailor properties of materials. -The following application definitions are proposed to support the discussion -how materials engineering-specific data schemas can connect to or be mapped on +The following application definitions are proposed to support the discussion on how +materials-engineering-specific data schemas can connect to or be mapped on concepts which are equally modellable with NeXus: :ref:`NXms`: An application definition for arbitrary spatiotemporally resolved simulations. + :ref:`NXms_recon`: + A base class for documenting results of reconstructed microstructures. + :ref:`NXms_score_config`: - A specific example how :ref:`NXapm_paraprobe_config_ranger` can be + A specific example of how :ref:`NXapm_paraprobe_config_ranger` can be specialized for documenting the configuration of a computer simulation with the static recrystallization cellular automata model SCORE. :ref:`NXms_score_results`: - A specific example how :ref:`NXms` can be specialized for documenting + A specific example of how :ref:`NXms` can be specialized for documenting results of computer simulations with the static recrystallization cellular automata model SCORE.