Fairmat 2024: proposal on atom probe microscopy (APM)

base_classes/NXapm_charge_state_analysis.nxdl.xml

@@ -0,0 +1,159 @@
+<?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) 2024-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 (molecular) ion candidates.
+            </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 the parameters (configuration) and results of a processing for recovering
+        the charge state and nuclide composition of a (molecular) ion from ranging definitions as used
+        in the research field of atom probe microscopy.
+
+        A ranging definition classically reports only the mass-to-charge-state-ratio interval plus the
+        elemental composition, but not necessarily the nuclide that compose the (molecular) ion.
+
+        As the mass-resolving-power in an atom probe instrument is finite and typically lower
+        than for cutting edge tandem mass spectrometry it is possible that different combinations of nuclides
+        are indistinguishable and thus multiple (molecular) ions in eventually even different charge states
+        can be valid labels for a given mass-to-charge-state-ratio peak. Enumerating the possible combinations
+        is a programmatic approach that can help with peak identification.
+    </doc>
+    <group name="config" type="NXparameters">
+        <doc>
+            Parameters for the algorithm that tries to recover which combinations of nuclides
+            have a mass and charge that matches a set of constraints.
+
+            Each parameter in this group is defines one constraint.
+        </doc>
+        <field name="nuclides" type="NX_UINT" units="NX_UNITLESS">
+            <doc>
+                Parameter that defines the elements considered in the combinatorial search.
+                The array contains nuclides as many times as their multiplicity and must not be empty.
+
+                Nuclides are encoded using the hashing rule that is defined in :ref:`NXatom`; 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`.
+                Using 0 for the number of neutrons of an oxygen atom allows to encode that
+                isotopes of oxygen in general are meant, i.e. the element oxygen.
+
+                Constraining the elements or nuclides instead of providing all nuclides
+                reduces the time to perform an exhaustive combinatorial search.
+            </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>
+                Parameter that defines the interval :math:`[{m/q}_{min}, {m/q}_{max}]` within which
+                (molecular) ions with given mass-to-charge-state-ratio qualify as candidates.
+            </doc>
+            <dimensions rank="1">
+                <dim index="1" value="2"/>
+            </dimensions>
+        </field>
+        <field name="min_half_life" type="NX_FLOAT" units="NX_TIME">
+            <doc>
+                Parameter that defines the 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>
+                Parameter that defines the 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>
+    </group>
+    <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 entries in the matrix should be set to 0.
+        </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 the nuclide that has the
+            shortest half life.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="n_cand"/>
+        </dimensions>
+    </field>
+</definition>

base_classes/NXapm_measurement.nxdl.xml

@@ -0,0 +1,70 @@
+<?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) 2025-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_measurement" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <doc>
+        Base class for collecting a run with a real or a simulated atom probe or field-ion microscope.
+
+        The term run is understood as an exact synonym for session, i.e. the usage of a real or simulated
+        tomograph or microscope for a certain amount of time during which one characterizes a single specimen.
+
+        Research workflows for experiments and simulations of atom probe and related field-evaporation
+        evolve continuously and become increasingly connected with other methods used for material
+        characterization specifically electron microscopy. A few examples in this direction are:
+
+        * `T. Kelly et al. &lt;https://doi.org/10.1017/S1431927620022205&gt;`_
+        * `C. Fleischmann et al. &lt;https://doi.org/10.1016/j.ultramic.2018.08.010&gt;`_
+        * `W. Windl et al. &lt;https://doi.org/10.1093/micmic/ozad067.294&gt;`_
+        * `C. Freysoldt et al. &lt;https://doi.org/10.1103/PhysRevLett.124.176801&gt;`_
+        * `G. da Costa et al. &lt;https://doi.org/10.1038/s41467-024-54169-2&gt;`_
+
+        The majority of atom probe research is performed using the so-called Local Electrode Atom Probe (LEAP) instruments
+        from AMETEK/Cameca. In addition, several research groups have built their own instruments and shared different
+        aspects of the technical specifications and approaches including how these groups apply data processing e.g.:
+
+        * `M. Monajem et al. &lt;https://doi.org/10.1017/S1431927622003397&gt;`_
+        * `P. Stender et al. &lt;https://doi.org/10.1017/S1431927621013982&gt;`_
+        * `I. Dimkou et al. &lt;https://doi.org/10.1093/micmic/ozac051&gt;`_
+
+        to name but a few.
+    </doc>
+    <field name="status" type="NX_CHAR">
+        <doc>
+            A statement whether the measurement completed successfully, or was aborted.
+        </doc>
+        <enumeration>
+            <item value="success"/>
+            <item value="aborted"/>
+        </enumeration>
+    </field>
+    <field name="quality" type="NX_CHAR">
+        <doc>
+            Statement about the quality of the measurement.
+
+            The value can be extracted from the CAnalysis.CResults.fQuality
+            field of a CamecaRoot ROOT file.
+        </doc>
+    </field>
+    <group type="NXinstrument_apm"/>
+    <group type="NXevent_data_apm"/>
+</definition>

base_classes/NXapm_ranging.nxdl.xml

@@ -0,0 +1,110 @@
+<?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) 2024-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 certain intervals.
+        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="NXnote"/>
+    <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 :math:`{\frac{m}{q}}_{min}`, increment :math:`{\frac{m}{q}}_{incr}`, and
+                largest mass-to-charge-state ratio :math:`{\frac{m}{q}}_{max}` value respectively.
+
+                The bounds :math:`{\frac{m}{q}}_{min}` and :math:`{\frac{m}{q}}_{max}` are inclusive.
+                The increment should be obey :math:`{\frac{m}{q}}_{max} = {\frac{m}{q}}_{min} + n \cdot :math:`{\frac{m}{q}}_{incr}` with :math:`n` a positive integer.
+            </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>
+                Free-text field to describe how atom probers define a background model.
+
+                Thereby, community feedback can be collected to inform an improved
+                version of this base class in the future.
+            </doc>
+        </field>
+    </group>
+    <group name="peak_search_and_deconvolution" type="NXprocess">
+        <doc>
+            How were peaks in the mass-to-charge-state ratio histogram 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 reserved value.
+
+                Consequently, start counting iontypes 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 that one can typically observe and distinguish
+                typically. 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="NXatom"/>
+    </group>
+</definition>