NEP Dataset Display Reference

This reference is organized by entry point. Find the button first, then check whether it opens a settings dialog, which values it requires, and what happens after execution.

1 — Interface overview

• Left: the main scatter-plot area, with descriptor, energy, force, pressure, potential-energy, and related views.

• Right: the structure pane, including the 3D view, structure information, shortest bond, net force, frame index, and playback controls.

• Bottom: the dataset status row, Orig / Now / Rm / Sel / Unsel / Rej.

• Top: split Open and Save buttons. Their menu actions are populated for the active page.

2 — Button and dialog reference

2.1 Main-plot toolbar (left)

Icon	Button	Opens settings?	Action
	Reset View	No	Fit the current plot to its data range
	Pan View	No (toggle)	Toggle pan interaction
	Select by Index	Yes	Select structures by index or slice
	Select by Range	Yes	Select structures by the current plot’s x/y range
	Select by Lattice	Yes	Select structures by lattice-parameter ranges
	Find Max Error Point	Yes	Select the top N errors on the current axis
	Sparse samples	Yes	Run FPS representative sampling
	Mouse Selection	No (toggle)	Toggle polygon and point selection
	Finding non-physical structures	No (progress only)	Find suspicious structures from neighbor distances
	Check Net Force	Yes	Select structures by a net-force threshold
	Inverse Selection	No	Invert selection over active structures
	Undo Selection	No	Undo the most recent selection change
	Undo Delete	No	Restore the most recently deleted structures
	Delete Selected Items	No	Delete the selected structures
	Edit Info	Yes	Batch-edit structure metadata
	Export structure descriptor	Yes (file path)	Export descriptors for the current structures
	Energy Baseline Shift	Yes	Fit and apply an energy-baseline shift
	DFT D3	Yes	Configure and apply a DFT-D3 correction
	Training Set Audit	No (opens the audit page)	Inspect overall composition, data quality, labels, structural phases, and magnetic types.
	Explore distributions	No (opens Training Set Audit)	Inspect numerical-field distributions and select structures from them

2.2 Structure toolbar (right)

Icon	Button	Opens settings?	Action
	Ortho View	No (toggle)	Toggle orthographic projection
	Automatic View	No (toggle)	Fit the structure viewing distance
	Show Bonds	No (toggle)	Show or hide bonds
	Show Arrows	Yes	Show force, moment, or other vector arrows
	Export current structure	Yes	Export the current structure
	Mark Bad (Reject)	No (toggle)	Mark the current structure as rejected
	Drop All Bad	Yes (confirmation)	Delete all rejected structures

2.3 Top-menu actions

Icon	Menu action	Opens settings?	Description
	Open File...	Yes	Choose an *.xyz file
	Open Folder...	Yes	Choose a directory, commonly for deepmd/npy
	Export menus such as Export All...	Yes	Choose ExportFormat, then the destination path

3 — Main-plot toolbar by button

3.1 Buttons without dialogs

Button	Behavior
Reset View	Fit the current plot to its data range
Pan View	Toggle pan interaction
Mouse Selection	Toggle polygon/point selection
Inverse Selection	Invert selection across active structures
Delete Selected Items	Delete selected structures and redraw
Undo Selection	Undo the most recent selection change. If none exists, the app reports No undoable selection!
Undo Delete	Undo the most recent deletion. If none exists, the app reports No undoable deletion!

3.2 Buttons with dialogs

A. Select by Index

• Inputs:

  • indexEdit: index expression

  • Use original indices: enabled by default

• Supported index syntax:

  • Single values: 3, -1

  • Slices: 1:10, :100, ::3, 10:0:-1

  • Multiple segments: 1:10,20,30:40:2, separated by commas or spaces

• Result: select the parsed structures. An empty expression does nothing.

B. Select by Range

• Inputs:

  • xMin/xMax/yMin/yMax: range [-1e8, 1e8], six decimal places

  • Logic: AND or OR (default: AND)

• Defaults: populated from the current plot’s data limits when the dialog opens.

• Result: select structures whose plotted coordinates satisfy the chosen window and logic.

C. Select by Lattice

• Inputs: minimum and maximum values for a/b/c/alpha/beta/gamma.

• Range: [0, 1e6], four decimal places.

• Defaults: the lattice-parameter range of active structures.

• Detail: comparisons use a fixed internal tolerance of 1e-4.

D. Find Max Error Point

• Input: integer N.

• Default: widget.max_error_value, or 10 when unset.

• Result: select the N structures with the largest errors on the current axis.

E. Sparse samples

• Inputs:

  • Selection strategy：

    • Global FPS (compatible): preserves the original global FPS behavior;

    • Element-set balanced FPS: groups structures by element set, reserves at least one slot per group, distributes the remaining slots in proportion to the square root of group size, and starts sampling from each group’s descriptor center.

  • Sampling mode：Fixed count (FPS) / R^2 stop (FPS)

  • Max num：[0, 9999999]

  • Min distance: [0, 10], five decimal places

  • R^2 threshold：[0,1]

  • Descriptor source：Reduced (PCA) / Raw descriptor

  • Training dataset: optional .xyz file or directory

  • Use current selection as region

  • Show training overlay: after sampling, overlay the training set, current data, and selected structures in PCA space

• Balanced mode always uses raw structure-level descriptors and a fixed sample count, so Sampling mode and Descriptor source are locked. Global mode continues to allow the original options.

• With a training set, global mode keeps the original whole-dataset warm start, while balanced mode initializes distances only from existing structures with the same element set.

• Result: FPS updates the selection set. Balanced mode also reports the actual number selected and the number of element sets covered.

F. Finding non-physical structures (no parameter dialog; progress only)

• Parameter source: widget.radius_coefficient (default: 0.7).

• Result: scan and select structures flagged as potentially nonphysical.

G. Check Net Force

• Input: threshold for |ΣF|.

• Range: [0, 1e6], ten decimal places.

• Default: widget.force_balance_threshold, or 1e-3 when unset.

• Result: select structures above the threshold and display summary statistics.

H. Edit Info

• Supported edits:

  • Add labels as key/value pairs

  • Remove labels

  • Rename labels from the context menu

• Confirmation before applying: lists a removed / renamed / added summary.

• Result: update metadata for all selected structures.

I. Export structure descriptor (path selection)

• Default filename: export_descriptor_data.out.

• Result: export descriptors in the background.

J. Energy Baseline Shift

• Preset area: presetCombo plus import, export, and delete buttons.

• Parameters: groupEdit, alignment mode, max generations, population size, and convergence tol.

• Saving: Save baseline as preset plus Preset name.

• Result: fit and apply the baseline shift in the background, then redraw.

K. DFT D3

• Inputs: functional, D3 cutoff, D3 cutoff_cn, and mode (Add/Subtract).

• Result: apply the DFT-D3 correction in the background and redraw.

L. Training Set Audit

• Location: to the right of the separator after the Delete button.

• Scope: current active structures. Deleted structures are excluded.

• Overview: structure and atom statistics, label availability, the element co-occurrence matrix, and exact element sets.

• Evidence: data quality, local chemistry, structural phases, and magnetic types; expensive evidence is computed in the background.

• Selection round-trip: click a chart, table row, or review item to send the corresponding real structure indices back to NEP Dataset Display.

• Report: Export HTML Report records the audit scope, fingerprints, evidence, criteria, and limitations.

For the full workflow and recognition principles, see Training Set Audit.

M. Explore distributions

• Opens Training Set Audit → Data Distributions; it no longer opens a separate Distribution Inspector window.

• In the usual workflow, choose only Field / Value Type / Group By / Data Range.

• Selection Mode / Bins / Auxiliary Curve / Vector Norm are under Advanced Options.

• Metric / Series is linked to the distribution plot. Clicking a bin writes the corresponding structure selection back to Dataset Display.

• Reference, Prediction, and Error are meaningful only when the underlying dataset provides the required paired data.

The former standalone window remains as a compatibility implementation, but the toolbar now opens the unified audit page.

4 — Structure toolbar by button

4.1 Camera and display controls

Button	Behavior
Ortho View	Toggle orthographic projection
Automatic View	Fit the camera orientation and distance
Show Bonds	Show or hide bonds; the icon toggles between show_bond and hide_bond

4.2 Show Arrows

• Requirement: the active structure canvas must support the arrow API, normally provided by VisPy.

• Inputs:

  • Property: an atomic N × 3 vector property only

  • Scale: [0, 1000], default: 1.0

  • Colormap：viridis/magma/plasma/inferno/jet

  • Show arrows: enable to display arrows; disable to clear them

4.3 Export current structure

• Step 1: choose the format

  • XYZ (.xyz / extxyz)

  • DeepMD/NPY (deepmd/npy)

• Step 2: choose the destination

  • xyz: file path, defaulting to structure_{index}.xyz

  • deepmd/npy: directory path

4.4 Mark Bad (Reject) and Drop All Bad

• Mark Bad (Reject): mark without deleting; rejected structures are highlighted in the main plot.

• Drop All Bad: after confirmation, delete every active rejected structure, clear the reject set, and redraw.

5 — Import, export, and NEP model switching

5.1 Import

• Open File...: choose an *.xyz file.

• Open Folder...: choose a directory, commonly a deepmd/npy dataset.

• Drag and drop accepts only paths supported by matches_result_loader().

• If a working path is already open, the app asks for confirmation before switching.

• Loading runs in a background thread; the StateToolTip can request cancellation.

5.2 Export menu (top Save button)

• Actions: Export All / Selected / Removed / Active.

• Availability: data must be loaded and the page must not be busy. Selected, Removed, and Active additionally require a nonzero count.

• For every action, choose ExportFormat first and then the destination path.

5.3 Switching NEP models (dropdown to the right of the path bar)

• Discovery: scan the current directory for *.txt files whose names contain nep.

• Ordering: nep.txt first, then other files alphabetically, with the built-in nep89 optionally appended.

• Switching: use _nep_result_cache when available; otherwise reload asynchronously.

• State preservation: restore selected and reject after the switch.

6 — Structure filter bar

The structure filter bar combines configuration type, formula, element, and custom-expression conditions. Conditions use intersection logic by default, and combinations you use repeatedly can be saved under Saved filters.

6.1 Basic workflow

1. Click Filter conditions to open the editor. An empty filter starts with one blank row.

2. Click + in the lower-left corner to add more conditions, such as Config type contains surface, Must contain Fe,O, and Must not contain H.

3. Choose Match all conditions (AND) or Match any condition (OR) in the upper-right corner.

4. Click Done and preview. The highlighted matches in the plot are only a preview and do not change the current selection.

5. After checking the match count, choose Replace current selection, Add to current selection, or Remove from current selection from Apply result.

After a condition changes, the previous match result is marked Result is stale and cannot be applied until you preview again.

The trash button in the lower-right corner of the editor clears only the filter conditions and match highlight; it does not clear the current selection. Use Clear current selection in the Apply result menu for that action.

6.2 Condition semantics

Condition	Meaning	Example
Configuration type	Contains, exact, starts with, ends with, or regular expression	surface
Formula	Exact by default; contains and regular-expression matching are also available	Fe2O3
Must contain elements	Every listed element must be present; additional elements are allowed	Fe,O matches FeO and FeOC
Must not contain elements	None of the listed elements may be present	H excludes structures containing H
Allow only these elements	The structure cannot contain elements outside the list	Fe,O matches Fe, O, and FeO
Custom expression	Uses the existing structure-expression engine	natoms > 100

Enter multiple values in one configuration-type or formula condition by separating them with semicolons; matching any value is sufficient. Separate elements with commas or spaces, for example Fe, O.

The switch on the left of each row controls whether that condition takes part in filtering. Turning it off keeps the entered value. For config type and formula conditions, Aa controls case sensitivity: highlighted means case-sensitive; otherwise matching is case-insensitive.

An invalid regular expression, unknown element, or invalid expression marks the corresponding condition directly. It is not treated as zero matches and cannot accidentally match every structure.

6.3 Save and reuse filters

If you repeatedly clean the same kind of data, save the whole condition set. For example:

• Configuration type contains surface

• Must contain elements Fe,O

• Must not contain element H

• Logic set to Match all conditions (AND)

After saving it once, you do not need to re-enter every row next time:

1. Set the conditions, AND/OR logic, and Aa states.

2. Choose Saved filters → Save current conditions….

3. Enter a recognizable name such as Fe-O surface, then click Save.

4. The next time you open the editor, click Saved filters, then click that name.

Loading a saved filter replaces the conditions currently in the editor and then refreshes the preview. It does not run Apply result automatically and does not change the current selection.

A saved filter includes:

• Each condition’s type, entered values, and enabled state

• The match mode and Aa state for config type or formula conditions

• Match all conditions (AND) or Match any condition (OR)

Saved filters are stored in the local user configuration and remain available after restarting the application. They do not store the current match result, current selection, dataset path, or NEP model; this feature stores filter conditions, not an automated processing workflow.

To maintain existing entries, open Saved filters → Manage saved filters:

• Rename changes only the name, not the conditions.

• Delete removes only the saved entry; it does not clear the current editor conditions.

• When saving or renaming to an existing name, the application asks before overwriting it.

A filter with a blank row cannot be saved. Complete that row or remove it with the × at the end.

6.4 expression overview

• Purpose: express whether each structure satisfies a condition, then use Search, Select, or Deselect on the matches.

• Scope: current active structures only. Deleted structures are not evaluated.

• Search: highlight matching structures.

• Select: add matches to the current selection.

• Deselect: remove matches from the current selection.

• Deletion remains explicit: normally select with an expression, inspect the result, and then click the toolbar delete button.

6.4.1 Supported operators

• Logical operators: &&, ||, !

• Logical keywords: and, or, not

• Comparison operators: >, >=, <, <=, ==, !=

• Arithmetic operators: +, -, *, /

• Parentheses: (, )

Examples:

• natoms > 100

• has.H && natoms < 50

• (energy_per_atom < -3.0) && (force.norm > 10)

6.4.2 Unsupported syntax

• Function calls are unsupported, including len(structure), mean(force), and any(...).

• Fixed atom indexing is unsupported, for example atom[3].force.x > 1.

• Numeric component suffixes are unsupported, for example force.1 or stress.3.

• String and regular-expression functions are unsupported.

Use natoms directly for the atom count.

6.4.3 Built-in structure fields

These fields are calculated from active structures regardless of which subplot is currently visible.

Field	Meaning
natoms	Number of atoms
n_atoms	Alias of natoms
volume	Cell volume
a b c	Lattice lengths
alpha beta gamma	Lattice angles
spin_natoms	Number of atoms with moments
energy	Total structure energy
energy_per_atom	Energy per atom
has_energy	Whether energy data exist
has_forces	Whether force data exist
has_virial	Whether virial data exist
has_bec	Whether BEC data exist

Examples:

• natoms >= 128

• volume < 500

• a > 4.5 && c < 20

• energy_per_atom < -4.2

• has_forces && !has_bec

6.4.4 Element-statistics fields

Element fields are generated dynamically from species present in active structures.

Field form	Meaning	Example
count.<Elem>	Count of one element	count.Fe >= 4
frac.<Elem>	Fraction of one element	frac.Li > 0.5
has.<Elem>	Whether an element is present	has.H && natoms < 50

Notes:

• <Elem> uses a standard element symbol such as H, O, Fe, or Li.

• Although internal parsing handles prefix case, always use standard element-symbol capitalization in documentation and input.

• If the element is absent from all active structures, the expression reports an error.

6.4.5 Dynamic data fields

Expression mode exposes only fields that exist in the current result data. They commonly come from two sources:

• Result-dataset fields such as force, mforce, stress, virial, dipole, and bec

• Atomic-property fields written as atomic.<name>, for example atomic.spin_vec

Consequences:

• If the current data contain no mforce, autocomplete does not offer mforce.

• Manually entering an unavailable field, such as mforce.ref.x > 1, produces an error.

6.4.6 Suffix rules

A. Data-view suffixes

For dataset fields that provide paired reference and prediction values, append:

• .ref: reference value

• .pred: predicted value

• .err: error, defined as pred - ref

When the data-view suffix is omitted, .ref is used by default.

Examples:

• force.x > 10 is equivalent to force.ref.x > 10.

• stress.err.norm > 2

• energy.pred > -4.0

Not every field supports all three suffixes:

• atomic.<name> does not support .ref, .pred, or .err.

• Unpaired data fields do not support .pred or .err.

B. Component and norm suffixes

Vector and tensor fields support named component suffixes:

• Three-component vectors: .x, .y, .z

• Six-component tensors: .xx, .yy, .zz, .xy, .yz, .zx

• Norm: .norm

Examples:

• force.x > 10

• mforce.norm > 5

• virial.xx < -20

• atomic.spin_vec.z > 0.2

Important:

• Numeric components such as .1, .2, and .3 are unsupported.

• A multicomponent field without a named component or .norm produces an error.

• Scalar fields can be compared directly, for example energy > -10.

6.4.7 Aggregating atomic fields to structures

An expression must return one Boolean result per structure, so atom-level data are reduced to a structure-level value first.

Default rule:

1. First extract the named component or norm.

2. Then calculate max(abs(values)) within each structure.

Therefore:

• force.x > 10 asks whether max(abs(force_x)) > 10 within each structure.

• force.norm > 10 asks whether max(force_norm) > 10 within each structure.

• atomic.spin_vec.y > 0.5 uses the same structure-level maximum-absolute-value reduction.

Structure-level fields such as natoms, volume, and energy are compared directly without aggregation.

6.4.8 Common expression examples

Filter by structure size

• natoms > 100

• natoms >= 32 && natoms <= 128

Filter by lattice or volume

• volume < 1000

• a > 3 && b > 3 && c > 3

• gamma != 120

Filter by composition

• count.O >= 4

• frac.Li > 0.25

• has.Fe && !has.H

Filter by energy

• energy_per_atom < -3.5

• has_energy && energy > -500

Filter by force, stress, or virial

• force.x > 10

• force.norm > 15

• force.err.norm > 0.2

• stress.xx > 5

• virial.err.norm > 1

Filter by an atomic property

• atomic.spin_vec.norm > 1.5

• atomic.spin_scalar > 0.1

Combine conditions

• has.H && natoms < 50 && energy_per_atom < -2.5

• (count.Fe >= 2) && (force.norm > 8 || stress.norm > 2)

6.4.9 Autocomplete and availability counts

Expression mode uses its own dynamic autocomplete and does not share the cache used by tag, formula, or elements.

Autocomplete sources include:

• Built-in structure fields such as natoms and volume

• Element-statistics fields such as count.Fe and frac.O

• Dynamic fields actually present in the dataset, such as force.ref.x and virial.ref.xx

• Atomic properties actually present in current structures, such as atomic.spin_vec.y

The number shown to the right of an autocomplete item is not the current search-match count. It is the number of active structures for which that candidate field is available or meaningful:

• For natoms, the number normally equals the active-structure count.

• For count.Fe, it is the number of structures containing Fe.

• For has.H, it is the number of structures containing H.

• For force.ref.x, it is the number of structures with force data.

• For atomic.spin_vec.y, it is the number of structures with a spin_vec atomic property.

This availability count is distinct from the number of matches produced by a complete expression.

6.4.10 Errors and troubleshooting

Common errors include:

• Unknown field in expression

  • The field does not exist or is absent from the current data.

• Unknown atomic field

  • atomic.<name> is misspelled or the structures lack that atomic property.

• Numeric component suffixes are not supported

  • A numeric component such as .1, .2, or .3 was used.

• Field 'xxx' requires an explicit component or '.norm'

  • A multicomponent field lacks a named component or .norm.

• does not support value views

  • .pred or .err was appended to a field that does not support paired views.

• Invalid expression syntax

  • The expression is incomplete, for example force.x >.

6.4.11 Using expressions in the structure filter

After adding a Custom expression condition, enter the complete expression directly. The existing evaluator still executes it, so all fields, operators, and dynamic-data capabilities described in this section remain available.

An expression can be combined with other conditions. For example:

• Configuration type contains surface

• Must contain elements Fe,O

• Custom expression natoms >= 64 && force.error.norm < 0.2

With Match all conditions, the three conditions are intersected. The filter does not convert expressions into a second simplified syntax, so operators such as !=, lattice angles, Boolean fields, and dynamic fields are preserved.

7 — Status indicators and common messages

• Dataset status: Orig / Now / Rm / Sel / Unsel / Rej.

• Structure status: suspicious shortest bonds are shown in red; net force is displayed as |ΣF|.

• Playback: / .

Message	Trigger
unsupported file format	The import path is unsupported
NEP data has not been loaded yet!	An analysis or export is requested before loading data
Please select some structures first!	Selected export is requested with no selection
No active structures to export.	Active export is requested with no active structures
No removed structures to export.	Removed export is requested with no removed structures
No undoable deletion!	No deletion is available to undo
No vector data available	The vector property required for arrows is absent
Arrow overlay is unavailable...	The current structure canvas does not support the arrow API
Invalid regex pattern.	tag or formula contains an invalid regular expression
Unknown element symbol: Xx	elements contains an unknown element symbol
Unknown field in expression: xxx	expression references a nonexistent or unavailable field
Numeric component suffixes are not supported in expressions.	expression uses a numeric component such as .1, .2, or .3
Expression contains unsupported syntax.	expression contains unsupported syntax
Invalid expression syntax.	expression is incomplete or cannot be parsed

Related pages

• Feature overview: NEP-dataset-display.md

• Example: ../example/NEP-display.md