Fairmat 2024: proposal on atom probe microscopy (APM)

base_classes/NXactivity.nxdl.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+<!--
+# NeXus - Neutron and X-ray Common Data Format
+# 
+# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
+# 
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# For further information, see http://www.nexusformat.org
+-->
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXactivity" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <doc>
+         A planned or unplanned action that has a temporal extension and for some time depends on some entity.
+
+         This class is planned be used in the future as the super class for all other activities if inheritance 
+         in base classes is supported in NeXus.
+    </doc>
+    <field name="start_time" type="NX_DATE_TIME">
+        <doc>
+             ISO 8601 formatted time code (with local time zone offset to UTC information
+             included) when this activity started.
+        </doc>
+    </field>
+    <field name="end_time" type="NX_DATE_TIME">
+        <doc>
+             ISO 8601 formatted time code (with local time zone offset to UTC information
+             included) when this activity ended.
+        </doc>
+    </field>
+    <field name="description">
+        <doc>
+             Short description of the activity.
+        </doc>
+    </field>
+    <group name="notes" type="NXnote">
+        <doc>
+             This can be any data or other descriptor acquired during the activity
+             (NXnote allows to add pictures, audio, movies). Alternatively, a
+             reference to the location or a unique identifier or other metadata file. In the
+             case these are not available, free-text description.
+        </doc>
+    </group>
+</definition>

base_classes/NXactuator.nxdl.xml

@@ -85,4 +85,4 @@
         </doc>
     </group>
     <group type="NXfabrication"/>
-</definition>
+</definition>

base_classes/NXapm_charge_state_analysis.nxdl.xml

@@ -0,0 +1,168 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+<!--
+# NeXus - Neutron and X-ray Common Data Format
+#
+# Copyright (C) 2014-2025 NeXus International Advisory Committee (NIAC)
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# For further information, see http://www.nexusformat.org
+-->
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXapm_charge_state_analysis" extends="NXprocess" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <symbols>
+        <doc>
+             The symbols used in the schema to specify e.g. dimensions of arrays.
+        </doc>
+        <symbol name="n_cand">
+            <doc>
+                 The number of also possible but different (molecular) ions.
+            </doc>
+        </symbol>
+        <symbol name="n_ivec_max">
+            <doc>
+                 Maximum number of allowed atoms per (molecular) ion (fragment).
+            </doc>
+        </symbol>
+        <symbol name="n_variable">
+            <doc>
+                 Number of entries
+            </doc>
+        </symbol>
+    </symbols>
+    <doc>
+         Base class to document an algorithm for recovering charge state and nuclide composition of a (molecular) ion.
+
+         Currently ranging definitions in the research field of atom probe face have limitations:
+
+         1. A ranging definition maps all signal within a mass-to-charge-state-ratio value interval
+            on one iontype. Facing limited mass-resolving-power, there are mass-to-charge-state-ratio
+            values, though, for which not only multiple (molecular) ions are indistinguishable but
+            also for which the current practice of documenting classical ranging definitions is incomplete.
+         2. Indeed, ranging definitions often report only (for each interval) the
+            mass-to-charge-state-ratio intervals surplus the composition of elements
+            that build the (molecular) ion.
+         3. Therefore, classical ranging definitions demand a post-processing with an algorithm
+            which can identify nuclides from which the (molecular) ion is constructed
+            and a charge state possibly recovered. Combinatorial algorithms are used for this purpose.
+
+         This base class documents the configuration and results of such an algorithm.
+    </doc>
+    <!--Details and results of the combinatorial analyses of a ranging definition
+to clarify (if possible) the charge_state of an ion and its (not necessarily)
+unique combination of nuclides contained including their multiplicity.
+input/config-->
+    <field name="nuclides" type="NX_UINT" units="NX_UNITLESS">
+        <doc>
+             Input constraint, list of nuclide_hash for typically elements used for the
+             ranging definition of the ion whose charge state the analyses covered.
+             The list contains each hash as many times as its multiplicity.
+             Nuclides are encoded using the hashing rule that is defined in :ref:`NXion`.
+
+             As an example, a ranging definition H:2 O:1 is configured by setting nuclides to
+             a list with entries :math:`1 + 0 \cdot 256`, :math:`1 + 0 \cdot 256`, :math:`8 + 0 \cdot 256`.
+             An empty list does not release the constraint. Instead, a list with all elements
+             in the periodic table (encoded as nuclide_hash values) should be used, i.e.
+             :math:`1 + 0 \cdot 256`, :math:`2 + 0 \cdot 256`, and so on and so forth.
+
+             Keep in mind that with a weakly constrained parameter space the combinatorial
+             analysis may become very time consuming!
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_variable"/>
+        </dimensions>
+    </field>
+    <field name="mass_to_charge_range" type="NX_FLOAT" units="NX_ANY">
+        <doc>
+             Input constraint, interval within which (molecular) ions need to have the
+             mass-to-charge-state-ratio such that an ion qualifies as a candidate.
+        </doc>
+        <dimensions rank="2">
+            <dim index="1" value="1"/>
+            <dim index="2" value="2"/>
+        </dimensions>
+    </field>
+    <field name="min_half_life" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             Input constraint, minimum half life for how long each nuclide of each
+             (molecular) ion needs to be stable such that the ion qualifies as a candidate.
+        </doc>
+    </field>
+    <field name="min_abundance" type="NX_FLOAT" units="NX_DIMENSIONLESS">
+        <doc>
+             Input constraint, minimum natural abundance of each nuclide of each
+             (molecular) ion such that the ion qualifies as a candidate.
+        </doc>
+    </field>
+    <field name="sacrifice_isotopic_uniqueness" type="NX_BOOLEAN">
+        <doc>
+             If the value is false, it means that non-unique solutions are accepted.
+             These are solutions where multiple candidates have been built from
+             different nuclide instances but the charge_state of all the ions is the same.
+        </doc>
+    </field>
+    <!--min_abundance_product(NX_FLOAT):
+  doc: |
+    For each candidate TO BE DEFINED.
+  unit: NX_DIMENSIONLESS
+  dim: (n_cand,)-->
+    <!--output/results
+the n_cand can be 1 in which case all quantities below are scalar-->
+    <field name="charge_state" type="NX_INT" units="NX_UNITLESS">
+        <doc>
+             Signed charge, i.e. integer multiple of the elementary
+             charge of each candidate.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_cand"/>
+        </dimensions>
+    </field>
+    <field name="nuclide_hash" type="NX_UINT" units="NX_UNITLESS">
+        <doc>
+             Table of nuclide instances of which each candidate is composed.
+             Each row vector is sorted in descending order. Unused values are nullified.
+        </doc>
+        <dimensions rank="2">
+            <dim index="1" value="n_cand"/>
+            <dim index="2" value="n_ivec_max"/>
+        </dimensions>
+    </field>
+    <field name="mass" type="NX_FLOAT" units="NX_MASS">
+        <doc>
+             Accumulated mass of the nuclides in each candidate.
+             Not corrected for quantum effects.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_cand"/>
+        </dimensions>
+    </field>
+    <field name="natural_abundance_product" type="NX_FLOAT" units="NX_DIMENSIONLESS">
+        <doc>
+             The product of the natural abundances of the nuclides for each candidate.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_cand"/>
+        </dimensions>
+    </field>
+    <field name="shortest_half_life" type="NX_FLOAT" units="NX_TIME">
+        <doc>
+             For each candidate the half life of that nuclide which has the shortest half
+             life.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_cand"/>
+        </dimensions>
+    </field>
+</definition>

base_classes/NXapm_ranging.nxdl.xml

@@ -0,0 +1,111 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+<!--
+# NeXus - Neutron and X-ray Common Data Format
+#
+# Copyright (C) 2014-2025 NeXus International Advisory Committee (NIAC)
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# For further information, see http://www.nexusformat.org
+-->
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXapm_ranging" extends="NXprocess" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <doc>
+         Base class for the configuration and results of ranging definitions.
+
+         Ranging is a data post-processing step used in the research field of
+         atom probe during which elemental, isotopic, and/or molecular identities
+         are assigned to mass-to-charge-state-ratios within a certain interval.
+         The documentation of these steps is based on ideas that
+         have been described in the literature:
+
+         * `M. K. Miller &lt;https://doi.org/10.1002/sia.1719&gt;`_
+         * `D. Haley et al. &lt;https://doi.org/10.1017/S1431927620024290&gt;`_
+         * `M. Kühbach et al. &lt;https://doi.org/10.1017/S1431927621012241&gt;`_
+    </doc>
+    <group type="NXprogram"/>
+    <group type="NXserialized"/>
+    <group name="mass_to_charge_distribution" type="NXprocess">
+        <doc>
+             Specifies the mass-to-charge-state-ratio histogram.
+        </doc>
+        <group type="NXprogram"/>
+        <field name="min_incr_max" type="NX_FLOAT" units="NX_ANY">
+            <doc>
+                 Smallest, increment, and largest mass-to-charge-state ratio value.
+            </doc>
+            <dimensions rank="1">
+                <dim index="1" value="3"/>
+            </dimensions>
+        </field>
+        <group name="mass_spectrum" type="NXdata">
+            <doc>
+                 A default histogram aka mass spectrum of
+                 the mass-to-charge-state ratio values.
+            </doc>
+        </group>
+    </group>
+    <group name="background_quantification" type="NXprocess">
+        <doc>
+             Details of the background model that was used to
+             correct the total counts per bin into counts.
+        </doc>
+        <group type="NXprogram"/>
+        <field name="description" type="NX_CHAR">
+            <doc>
+                 To begin with we use a free-text field to learn how
+                 atom probers define a background model. Future versions
+                 of NXapm_ranging can then use this information to parameterize
+                 these models.
+            </doc>
+        </field>
+    </group>
+    <!--NEW ISSUE: add parameters of the background model in an e.g.
+NXcollection as these are specific to every background model
+NEW ISSUE: touching upon i.e. research activities by Andrew London et al.
+substantiating the need for a clearer description how peak/signals were
+eventually processed via deconvolution methods-->
+    <group name="peak_search_and_deconvolution" type="NXprocess">
+        <doc>
+             How where peaks in the background-corrected in the histogram
+             of mass-to-charge-state ratio values identified?
+        </doc>
+        <group type="NXprogram"/>
+        <group type="NXpeak"/>
+    </group>
+    <group name="peak_identification" type="NXprocess">
+        <doc>
+             Details about how peaks, with taking into account
+             error models, were interpreted as ion types or not.
+        </doc>
+        <group type="NXprogram"/>
+        <field name="number_of_ion_types" type="NX_UINT" units="NX_UNITLESS">
+            <doc>
+                 How many ion types are distinguished. If no ranging was performed, each
+                 ion is of the special unknown type. The iontype ID of this unknown type
+                 is 0 representing a reserve value. Consequently,
+                 iontypes start counting from 1.
+            </doc>
+        </field>
+        <field name="maximum_number_of_atoms_per_molecular_ion" type="NX_UINT" units="NX_UNITLESS">
+            <doc>
+                 Assumed maximum value that suffices to store all relevant
+                 molecular ions, even the most complicated ones.
+                 Currently, a value of 32 is used (see `M. Kühbach et al. &lt;https://doi.org/10.1017/S1431927621012241&gt;`_).
+            </doc>
+        </field>
+        <group type="NXion"/>
+    </group>
+</definition>