NXapm_paraprobe_config_intersector

Status:

application definition, extends NXobject

Description:

Configuration of a paraprobe-intersector tool run in atom probe microscopy.

Symbols:

The symbols used in the schema to specify e.g. dimensions of arrays.

n_elements: How many elements to use for computing a composition.

Groups cited:

NXcollection, NXentry, NXprocess

Structure:

ENTRY: (required) NXentry

@version: (required) NX_CHAR

Version specifier of this application definition.

definition: (required) NX_CHAR

Official NeXus NXDL schema with which this file was written.

Obligatory value: NXapm_paraprobe_config_intersector

program: (required) NX_CHAR

Given name of the program/software/tool with which this NeXus (configuration) file was generated.

@version: (required) NX_CHAR

Ideally program version plus build number, or commit hash or description of ever persistent resources where the source code of the program and build instructions can be found so that the program can be configured ideally in such a manner that the result of this computational process is recreatable in the same deterministic manner.

analysis_identifier: (optional) NX_CHAR

Ideally, a (globally persistent) unique identifier for referring to this analysis.

analysis_description: (optional) NX_CHAR

Possibility for leaving a free-text description about this analysis.

time_stamp: (required) NX_DATE_TIME

ISO 8601 formatted time code with local time zone offset to UTC information included when this configuration file was created.

intersection_detection_method: (required) NX_CHAR

Specifies the method to use which decides if two objects intersect. For reasons which are detailed in the supplementary material of M. Kühbach et al., the tool by default assumes that two objects intersect if they share at least one ion with the same evaporation ID (shared_ion). Alternatively, with specifying tetrahedra_intersections, the tool can perform an intersection analysis which attempts to tetrahedralize first each polyhedron. If successful, the tool then checks for at least one pair of intersecting tetrahedra to identify if two objects intersect or not.

However, we found that these geometrical analyses can result in corner cases which the currently used library (TetGen) was not unable to tetrahedralize successfully. These cases were virtually always associated with complicated non-convex polyhedra which had portions of the mesh that were connected by almost point like tubes of triangles.

Any of these values: shared_ion | tetrahedra_intersections

has_object_volume: (required) NX_BOOLEAN

Specifies if the tool should load the volume of each object (if existent in the input file) to characterize the evolution of the objects’ volume as a function of set identifier (e.g. time).

This and the has_object_composition option enables to activate computations in the code which correlate the spatio-temporal tracking with an object’s properties. This is useful to explore/understand how the object descriptor values evolve as a function of the parameterization of the object. To arrive at a detailed understanding and quantification of the differences of a given object as a function of delocalization and e.g. iso-surfacing settings.

The point made in M. Kühbach et al. 2022, is that this functionality can be used to track for instance how the accumulated volume and composition of an object depends on its segmentation via iso-surfaces. The benefit of such computations is that users can inspect the parameter sensitivity of an objects representation rigorously.

has_object_composition: (required) NX_BOOLEAN

Specifies if the tool should load the composition of each object (if existent in the input file) to characterize the evolution of the object’s composition as a function of set identifier. See the description of has_object_volume for further details. In M. Kühbach et al. 2022, both has_object options were used to characterize e.g. the parameter sensitivity of computed composition, volume, and shape specifically, for a carbide that was segmented via different carbon iso-composition values.

element_whitelist: (required) NX_UINT (Rank: 1, Dimensions: [n_elements]) {units=NX_UNITLESS}

List of np.uint16 elements, via their proton number. The whitelist is evaluated to compute the composition of an object during tracking when has_object_composition is set to true.

number_of_processes: (required) NX_UINT {units=NX_UNITLESS}

For now a support field for the tool to identify how many individual analyses the tool should execute as part of the analysis.

PROCESS: (required) NXprocess

number_of_tracking_sets: (required) NX_UINT {units=NX_UNITLESS}

For now a support field for the tool to identify how many individual analyses (i. e. individual current_to_next mappings) the tool should perform as part of the high-throughput analysis.

PROCESS: (required) NXprocess

Tracking is the process of building logical relations between objects based on proximity and mesh intersections. For each time step pairs of sets are compared: members of a current_set and a next_set. Members have to be objects and eventually can in addition be so-called proxies. Objects and proxies are non-degenerated closed polyhedra which are not necessarily convex. Proxies are doppelganger/replacement meshes of objects which would otherwise be impossible to describe with a closed mesh.

add_proxies_to_objects: (required) NX_BOOLEAN

Specifies if, in the case of small finite datasets, objects which are located at the edge of the dataset should be accounted for or not. If these so-called proxy/doppelganger objects are accounted for, the respective groupname_proxy and dataset_proxy fields have to be filled to tell the tool where to load which proxy meshes from.

analyze_intersection: (required) NX_BOOLEAN

Specifies if the tool evaluates if for each pair the two objects (and proxies if used) intersect volumetrically.

analyze_proximity: (required) NX_BOOLEAN

Specifies if the tool evaluates if for each pair the two objects (and proxies if used) lie closer to one another than the threshold_proximity.

analyze_coprecipitation: (required) NX_BOOLEAN

Specifies if the tool evaluates, ones all tracking tasks were successfully completed, how intersecting or proximity related objects build sub-graphs. This is the feature which enabled M. Kühbach et al. 2022 the high-throughput analyses of how many objects are coprecipitates in the sense that they are single, duplet, triplet, or high-order. For these analyses to work has_object_volume needs to be activated.

threshold_proximity: (required) NX_FLOAT {units=NX_LENGTH}

The maximum Euclidean distance between two objects below which both objects are still considered within proximity.

has_current_to_next_links: (required) NX_BOOLEAN

Specifies if the tool stores the so-called forward relations between nodes representing members of the current_set to nodes representing members of the next_set.

has_next_to_current_links: (required) NX_BOOLEAN

Specifies if the tool stores the so-called backward relations between nodes representing members of the next_set to nodes representing members of the current_set.

current_set: (required) NXcollection

Current set stores a set of object geometries that should be checked for proximity and/or intersection with member of the next_set.

identifier: (required) NX_UINT {units=NX_ANY}

This identifier can be used to label the current set. The label effectively represents the time/iteration step when the current set was taken. As it is detailed in M. Kühbach et al. 2022, this identifier takes the role of the time variable k.

filename: (required) NX_CHAR

Name of the HDF5 file which contain geometry (vertex coordinates, facet indices) and properties (ions, composition) of polyhedra (l objects) which should be included in the current set. The user has to ensure that the datasets under list_of_dataset_names (vertices, facet_indices, ions) exist and are formatted consistently.

@version: (required) NX_CHAR

Version identifier of the file such as a secure hash which documents the binary state of the file to add an additional layer of reproducibility from which file specifically contains these data.

groupname_object_geometry_data: (required) NX_CHAR

Paraprobe-intersector loads triangulated surface mesh data of a set of objects. For each object its mesh is expected to have three-dimensional position data of the unique vertices and a matrix of vertex indices which describe the faces. As each object has to be a polyhedron/closed surface mesh, this matrix has as many rows as faces, i.e. triangles and three columns. Vertex indices have to start at zero.

groupname_object_supplementary_data: (required) NX_CHAR

The default intersection detection method uses shared ions. Therefore, it is necessary to specify where the results from the paraprobe-nanochem tool run are located which document which ions (with their evaporation IDs) are inside or on the surface of each object. This field points the tool to these evaporation IDs.

groupname_object_property_data: (required) NX_CHAR

In order to correlate object properties like volume and composition with tracking data, it is necessary to specify where the results (object properties) from the paraprobe-nanochem tool run are located. This field instructs the tool where to load these object property data from.

dataset_object_identifier: (required) NX_CHAR

Paraprobe-intersector does not just compare two objects but a set of sets of objects. This field instructs the tool where to load the identifiers (names) of each object in a current_set or next_set respectively from.

groupname_proxy_geometry_data: (optional) NX_CHAR

Like groupname_object_geometry_data but for the proxies. Triangulated surface meshes of proxies have to be formatted in the same manner as objects.

groupname_proxy_interior_supplementary_data: (optional) NX_CHAR

Like groupname_proxy_supplementary_data but for the interior proxies. Leave an empty string if proxies should not be used.

groupname_proxy_exterior_supplementary_data: (optional) NX_CHAR

Like groupname_proxy_supplementary_data but for the exterior proxies. Leave an empty string if proxies should not be used.

next_set: (required) NXcollection

Next set stores a set of object geometries that should be checked for proximity and/or intersection with (each) member(s) of the current_set.

identifier: (required) NX_UINT {units=NX_ANY}

This identifier can be used to label the next set. Like for the current_set the identifier is effectively the time/iteration step when the next set was taken. As it is detailed in M. Kühbach et al. 2022, this identifier takes the role of the time variable k+1.

filename: (required) NX_CHAR

Name of the HDF5 file which contain geometry (vertex coordinates, facet indices) and properties (ions, composition) of polyhedra(l objects) which should be included in the current set. The user has to ensure that the datasets that are referred to under list_of_dataset_names (vertices, facet_indices, ions).

@version: (required) NX_CHAR

Version identifier of the file such as a secure hash which documents the binary state of the file to add an additional layer of reproducibility from which file specifically contains these data.

groupname_object_geometry_data: (required) NX_CHAR

Paraprobe-intersector loads triangulated surface mesh data of a set of objects. For each object its mesh is expected to have three-dimensional position data of the unique vertices and a matrix of vertex indices which describe the faces. As each object has to be a polyhedron/closed surface mesh this matrix has as many rows as faces, i.e. triangles and three columns. Vertex indices have to start at zero.

groupname_object_supplementary_data: (required) NX_CHAR

The default intersection detection method uses shared ions. Therefore, it is necessary to specify where the results from the paraprobe-nanochem tool run are located which document which ions (with their identifiers) are inside or on the surface of each object. This field instructs the tool where to load these ion evaporation ids from.

groupname_object_property_data: (required) NX_CHAR

In order to correlate object properties like volume and composition with tracking data, it is necessary to specify where the results (object properties) from the paraprobe-nanochem tool run are located. This field instructs the tool where to load these object property data from.

dataset_object_identifier: (required) NX_CHAR

Paraprobe-intersector does not just compare two objects but a set of sets of objects. This field instructs the tool where to load the identifiers (names) of each object in a current or next set respectively from.

groupname_proxy_geometry_data: (optional) NX_CHAR

Like groupname_object_geometry_data but for the proxies. Triangulated surface meshes of proxies have to be formatted in the same manner. Leave an empty string if proxies should not be used.

groupname_proxy_interior_supplementary_data: (optional) NX_CHAR

Like groupname_proxy_supplementary_data but for the interior proxies. Leave an empty string if proxies should not be used.

groupname_proxy_exterior_supplementary_data: (optional) NX_CHAR

Like groupname_proxy_supplementary_data but for the exterior proxies. Leave an empty string if proxies should not be used.

Hypertext Anchors

List of hypertext anchors for all groups, fields, attributes, and links defined in this class.

NXDL Source:

https://github.com/FAIRmat-Experimental/nexus_definitions/tree/fairmat/contributed_definitions/NXapm_paraprobe_config_intersector.nxdl.xml