OpenDXA

A modified Dislocation Extraction Algorithm pipeline that reconstructs dislocation networks from a pre-computed structure-identification package.

OpenDXA (UI name Dislocation Analysis, plugin key opendxa) reconstructs dislocation networks. It is decoupled from structure identification: rather than classifying local structure itself, it runs the Dislocation Extraction Algorithm on a pre-computed annotated dump plus cluster tables.

In the VOLT workflow, OpenDXA chains a structure-analysis plugin via the required structure_analysis_plugin reference (Polyhedral Template Matching or Adaptive Common Neighbor Analysis), which produces the annotated dump and the *_clusters.table / *_cluster_transitions.table files OpenDXA reads.

OpenDXA incorporates OVITO-derived code and ships a LICENSE.OVITO alongside its MIT LICENSE. Those upstream licensing terms are binding.

Parameters

The UI form and the CLI use snake_case argument keys.

Parameter	Type	Default	Description
`structure_analysis_plugin`	`pluginReference`	— (required)	Chained structure-analysis plugin that produces OpenDXA's inputs. Filtered to `polyhedral-template-matching` and `adaptive-common-neighbor-analysis`.
`reference_topology`	`select`	`fcc`	Matrix-phase topology name, resolved from the lattice YAMLs. Options: `fcc`, `bcc`, `hcp`, `sc`, `cubic_diamond`, `hex_diamond`. Mapped onto the chained plugin's `crystal_structure`.
`max_trial_circuit_size`	`number`	`14`	Maximum Burgers circuit size.
`circuit_stretchability`	`number`	`9`	Circuit stretchability factor.
`line_smoothing_level`	`number`	`1.0`	Dislocation line smoothing level.
`line_point_interval`	`number`	`2.5`	Point interval along dislocation lines.

Additional CLI options

Exposed by the OpenDXA binary, passable when invoking it directly (the VOLT entrypoint sets several --export_* toggles for you).

Option	Default	Description
`--lattice_dir <path>`	package lattice dir	Directory of lattice topology YAMLs.
`--clusters_table <path>`	—	Path to the upstream `*_clusters.table`.
`--clusters_transitions <path>`	—	Path to the upstream `*_cluster_transitions.table`.
`--ghost_layer_scale <float>`	`3.5`	Multiplier on the reconstructed max neighbor distance when building ghost atoms for the Delaunay tessellation.
`--interface_alpha_scale <float>`	`5.0`	Multiplier on the reconstructed max neighbor distance for the interface alpha-shape filter.
`--crystal_path_steps <int>`	`4`	Maximum crystal path search depth.
`--clip_pbc_segments <bool>`	`true`	Clip exported dislocation polylines at periodic boundaries.
`--cover_domain_with_finite_tets <bool>`	`false`	Add helper points so the Delaunay domain is fully covered by finite tetrahedra.
`--export_defect_mesh <bool>`	`true`	Write `*_defect_mesh.parquet`.
`--export_interface_mesh <bool>`	`false`	Write `*_interface_mesh.parquet`.
`--export_delaunay_tessellation <bool>`	`false`	Write `*_delaunay_tessellation.parquet`.
`--export_structure_identification <bool>`	`false`	Write `*_atoms.parquet`.
`--export_coherent_crystalline_regions <bool>`	`false`	Write `*_coherent_crystalline_regions.parquet`.
`--export_dislocations <bool>`	`true`	Write `*_dislocations.parquet`.
`--export_circuit_information <bool>`	`true`	Include circuit information in the dislocations parquet.
`--export_dislocation_network_stats <bool>`	`true`	Include network statistics in the dislocations parquet.
`--export_junctions <bool>`	`true`	Include junction information in the dislocations parquet.

The VOLT analysis entrypoint always passes --export_interface_mesh true, --export_structure_identification true, and --export_coherent_crystalline_regions true, in addition to the defaults above.

Output

type Vec3 = [float, float, float];

`{outputBase}_dislocations.parquet`

A standard VOLT line entity table (one row per dislocation segment), consumed by the generic LineExporter. Fixed columns are id and points; every other column is a per-segment property that VOLT discovers, queries and styles generically.

Column	Type	Description
`id`	uint64	Segment entity id.
`points`	list<list<double>>	Polyline vertices, each `[x, y, z]`.
`length`	double	Segment length.
`num_points`	int64	Vertex count.
`magnitude`	double	Length of the local Burgers vector.
`burgers_vector_local`	list<double>	Burgers vector in the cluster lattice frame.
`burgers_vector_global`	list<double>	Burgers vector in the spatial frame.
`crystal_structure`	string	Crystal structure of the owning cluster.
`burgers_family`	string	Burgers family (e.g. `1/2<110>`).
`burgers_family_label`	string	Display label (e.g. `1/2<110> (Perfect)`).
`cluster_id`	int64	Owning cluster id.

`{outputBase}_dislocation_summary.parquet`

Network-level aggregates (JSON payload): main_listing statistics, the network_statistics / circuit_information / junction_information sub-listings, and the Burgers-vector chart series under export.ChartExporter.

interface DislocationSummaryOutput {
    export: {
        ChartExporter: {
            burgers_counts: {
                burgers_vector: string[];
                segment_count: int[];
            };
            burgers_lengths: {
                burgers_vector: string[];
                total_length: float[];
            };
        };
    };
    main_listing: {
        dislocations: int;
        total_points: int;
        average_segment_length: float;
        max_segment_length: float;
        min_segment_length: float;
        total_length: float;
    };
    sub_listings: {
        network_statistics?: object[];
        circuit_information?: object[];
        junction_information?: object[];
    };
}

`{outputBase}_defect_mesh.parquet`

interface MeshPoint {
    index: int;
    position: Vec3;
}

interface MeshFacet {
    vertices: [int, int, int];
}

interface MeshOutput {
    main_listing: {
        total_nodes: int;
        total_facets: int;
    };
    sub_listings: {
        points: MeshPoint[];
        facets: MeshFacet[];
    };
    export: {
        MeshExporter: {
            vertices: MeshPoint[];
            facets: MeshFacet[];
        };
    };
    topology?: {
        euler_characteristic: int;
        is_completely_good: boolean;
        is_completely_bad: boolean;
    };
}

`{outputBase}_interface_mesh.parquet`

Same schema as MeshOutput.

`{outputBase}_delaunay_tessellation.parquet`

The boundary/internal facets of the Delaunay tessellation. Written only when --export_delaunay_tessellation is enabled.

interface DelaunayTessellationOutput {
    main_listing: {
        total_primary_tetrahedra: int;
        total_nodes: int;
        total_facets: int;
        boundary_facets: int;
        internal_facets: int;
    };
    sub_listings: {
        points: MeshPoint[];
        facets: MeshFacet[];
    };
    export: {
        MeshExporter: {
            vertices: MeshPoint[];
            facets: MeshFacet[];
        };
    };
}

`{outputBase}_atoms.parquet`

Per-atom structure-identification results, grouped by structure type name. Written only when --export_structure_identification is enabled.

interface Atom {
    id: int;
    pos: Vec3;
    structure_id: int;
    structure_name: string;
    cluster_id: int;
    topology_name?: string;   // present only when known
}

interface PerAtomProperty {
    id: int;
    structure_id: int;
    structure_name: string;
    cluster_id: int;
    topology_name?: string;
}

interface AtomsOutput {
    export: {
        AtomisticExporter: Record<string, Atom[]>;  // keyed by structure name
        ChartExporter: {
            structure_counts: {
                structure_name: string[];
                atom_count: int[];
            };
        };
    };
    main_listing: {
        total_atoms: int;
        structure_count: int;
        clustered_atoms: int;
        unclustered_atoms: int;
    };
    sub_listings: {
        structures: {
            structure_id: int;
            structure_name: string;
            atom_count: int;
        }[];
    };
    "per-atom-properties": PerAtomProperty[];
}

`{outputBase}_coherent_crystalline_regions.parquet`

Atoms grouped into coherent crystalline regions (clusters). Written only when --export_coherent_crystalline_regions is enabled.

interface CoherentRegion {
    cluster_id: int;
    cluster_name: string;        // e.g. "Cluster 12"
    atom_count: int;
    structure_id: int;
    structure_name: string;
    topology_name: string;
}

interface CoherentRegionAtom {
    id: int;
    pos: Vec3;
    structure_id: int;
    structure_type: int;
    structure_name: string;
    cluster_id: int;
    topology_name?: string;      // present only when known
}

interface CoherentCrystallineRegionsOutput {
    main_listing: {
        total_atoms: int;
        coherent_region_count: int;
        assigned_atoms: int;
        unassigned_atoms: int;
        largest_region_size: int;
    };
    sub_listings: {
        coherent_crystalline_regions: CoherentRegion[];
    };
    export: {
        AtomisticExporter: Record<string, CoherentRegionAtom[]>;  // keyed by cluster name
    };
}