xtalforge-cli 1.2.0

//! The clap command tree for the CLI.

use clap::Subcommand;

use crate::analysis_commands::AnalysisAction;
use crate::feature_args::FeatureAction;
use crate::ff_commands::FfAction;
use crate::format::StructureFormat;
use crate::mof_commands::MofAction;
use crate::powder_commands::PowderAction;
use crate::spacegroup;
use crate::symmetry::SymmetryAction;

use crate::build_structures;

#[derive(Debug, Subcommand)]
pub(crate) enum ProjectAction {
    /// Pack a structure into a `.xtalproj` archive.
    Pack {
        /// Input structure path.
        path: String,
        /// Output archive path.
        out: String,
    },
    /// Print the parts of a project archive.
    Info {
        /// Archive path.
        path: String,
    },
    /// Extract a project into a directory.
    Extract {
        /// Archive path.
        path: String,
        /// Destination directory.
        dir: String,
    },
}

/// Model cache actions.
#[derive(Debug, Subcommand)]
pub(crate) enum ModelAction {
    /// List the catalogue and the cache state.
    List,
    /// Download a model into the cache and record its checksum.
    Fetch {
        /// Catalogue name: mace-mp-0, orb-v3 or mattersim.
        name: String,
        /// Artifact URL chosen by the user.
        #[arg(long)]
        url: String,
    },
    /// Recompute the checksum of a cached model.
    Verify {
        /// Catalogue name.
        name: String,
    },
    /// Remove a cached model and its metadata.
    Remove {
        /// Catalogue name.
        name: String,
    },
}

/// Skill document actions.
#[derive(Debug, Subcommand)]
pub(crate) enum SkillAction {
    /// Print the default install directory.
    Path,
    /// List the embedded documents.
    List,
    /// Print one document.
    Show {
        /// Path or base name, for example `SKILL` or `references/api.md`.
        name: String,
    },
    /// Write every document into a directory.
    Install {
        /// Destination; defaults to the user data directory.
        dir: Option<String>,
    },
}

#[derive(Debug, Subcommand)]
pub(crate) enum Command {
    /// Print the xtalforge version.
    Version,
    /// Report the features, engines, data bundles and verbs of this installation.
    Capabilities,
    /// Draw a structure to SVG or PNG.
    Render {
        /// Input path, or `-` for standard input.
        path: String,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
        /// Picture format.
        #[arg(long, value_enum, default_value_t = crate::format::PictureFormat::Svg)]
        format: crate::format::PictureFormat,
        /// Width in pixels.
        #[arg(long, default_value_t = 800)]
        width: u32,
        /// Height in pixels.
        #[arg(long, default_value_t = 600)]
        height: u32,
    },
    /// Run a JSON list of agent verbs against one session.
    Agent {
        /// Script path, or `-` for standard input.
        path: String,
    },
    /// Serve the Model Context Protocol over standard input and output.
    Mcp,
    /// Skill documents for an assistant: path, list, show or install.
    Skill {
        #[command(subcommand)]
        action: SkillAction,
    },
    /// Manage the optional machine-learning model cache.
    Models {
        #[command(subcommand)]
        action: ModelAction,
    },
    /// Print a shell completion script.
    Completions {
        /// Shell to generate for.
        #[arg(value_enum)]
        shell: clap_complete::Shell,
    },
    /// Print the roff manual page.
    Man,
    /// Add the hydrogens an X-ray structure is missing.
    Hydrogens {
        /// Input path, or `-` for standard input.
        path: String,
        /// X-H distance in Angstrom.
        #[arg(long, default_value_t = 1.09)]
        distance: f64,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
        /// Output format; defaults to the output extension or CIF.
        #[arg(long, value_enum)]
        format: Option<StructureFormat>,
    },
    /// Powder refinement: indexing, Le Bail/Pawley, Rietveld and cells.
    Powder {
        #[command(subcommand)]
        action: PowderAction,
    },
    /// MOF topologies, blocks and framework assembly.
    Mof {
        #[command(subcommand)]
        action: MofAction,
    },
    /// Porosity, nets and Zeo++ analysis.
    Analysis {
        #[command(subcommand)]
        action: AnalysisAction,
    },
    /// Force-field energies, optimizers, charges and vibrations.
    Ff {
        #[command(subcommand)]
        action: FfAction,
    },
    /// List the format registry.
    Formats,
    /// List parameter presets or print one schema.
    Params {
        /// Preset name; omit to list the presets.
        name: Option<String>,
    },
    /// Pack, inspect or extract a project archive.
    Project {
        #[command(subcommand)]
        action: ProjectAction,
    },
    /// Inspect or convert a multi-frame trajectory.
    Trajectory {
        /// Input path, or `-` for standard input.
        path: String,
        /// Frame index to write as a structure.
        #[arg(long)]
        frame: Option<usize>,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
        /// Output format; defaults to the output extension or CIF.
        #[arg(long, value_enum)]
        format: Option<StructureFormat>,
    },
    /// Decide whether two structures are the same.
    Compare {
        /// First structure.
        first: String,
        /// Second structure.
        second: String,
        /// Fractional length tolerance.
        #[arg(long, default_value_t = 0.2)]
        ltol: f64,
        /// Site tolerance in Angstrom.
        #[arg(long, default_value_t = 0.3)]
        stol: f64,
        /// Angle tolerance in degrees.
        #[arg(long, default_value_t = 5.0)]
        angle_tol: f64,
        /// Do not accept a supercell relationship.
        #[arg(long)]
        no_supercell: bool,
    },
    /// Group structures into equality classes.
    Group {
        /// Structure paths.
        paths: Vec<String>,
        /// Fractional length tolerance.
        #[arg(long, default_value_t = 0.2)]
        ltol: f64,
        /// Site tolerance in Angstrom.
        #[arg(long, default_value_t = 0.3)]
        stol: f64,
    },
    /// Apply a strain, deformation gradient, volume or density.
    Deform {
        /// Input structure.
        path: String,
        /// Six engineering Voigt components: xx,yy,zz,yz,xz,xy.
        #[arg(long)]
        voigt: Option<String>,
        /// Nine deformation-gradient components.
        #[arg(long)]
        gradient: Option<String>,
        /// Target cell volume in cubic Angstrom.
        #[arg(long)]
        volume: Option<f64>,
        /// Target density in g/cm3.
        #[arg(long)]
        density: Option<f64>,
        /// Output path.
        #[arg(long)]
        out: Option<String>,
        /// Output format.
        #[arg(long, value_enum)]
        format: Option<StructureFormat>,
    },
    /// Core crystal features: matcher edits, local environments, surfaces,
    /// defects, orderings, SQS, interfaces, elasticity and thermodynamics.
    Features {
        #[command(subcommand)]
        action: FeatureAction,
    },
    /// Apply a JSON command list to a structure.
    Script {
        /// Script path.
        path: String,
    },
    /// Print reference data for an element.
    Element {
        /// Element symbol or atomic number.
        input: String,
    },
    /// Print a summary of a structure or structure JSON document.
    Info {
        /// Input path, or `-` for standard input.
        path: String,
    },
    /// Build a cell from its six parameters.
    Cell {
        /// a, b, c in Angstrom and alpha, beta, gamma in degrees.
        #[arg(long, num_args = 6, value_names = ["a", "b", "c", "alpha", "beta", "gamma"])]
        params: Vec<f64>,
    },
    /// Compute the volume of a cell from its six parameters.
    CellVolume {
        /// Cell length a in Angstrom.
        a: f64,
        /// Cell length b in Angstrom.
        b: f64,
        /// Cell length c in Angstrom.
        c: f64,
        /// Angle alpha in degrees.
        alpha: f64,
        /// Angle beta in degrees.
        beta: f64,
        /// Angle gamma in degrees.
        gamma: f64,
    },
    /// Convert a structure between CIF, POSCAR and XYZ.
    Convert {
        /// Input path, or `-` for standard input.
        path: String,
        /// Output format.
        #[arg(long, value_enum)]
        format: StructureFormat,
        /// Output path, or `-` for standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
    },
    /// Calculate a PXRD pattern.
    Pxrd {
        /// Input path, or `-` for standard input.
        path: String,
        /// Radiation: cu-ka, cu-ka1, mo-ka, co-ka, fe-ka, cr-ka or ag-ka.
        #[arg(long, default_value = "cu-ka")]
        radiation: String,
        /// Highest 2-theta in degrees.
        #[arg(long, default_value_t = 80.0)]
        max_two_theta: f64,
        /// Step in degrees.
        #[arg(long, default_value_t = 0.02)]
        step: f64,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
    },
    /// Build graphene or a nanotube.
    Build {
        #[command(subcommand)]
        action: build_structures::BuildAction,
    },
    /// Build a printable STL mesh.
    Mesh {
        /// Input path, or `-` for standard input.
        path: String,
        /// Draw style: ball-stick, space-fill, wireframe or sticks.
        #[arg(long, default_value = "ball-stick")]
        style: String,
        /// Atom radius multiplier.
        #[arg(long, default_value_t = 1.0)]
        scale: f64,
        /// Emit the full scene geometry as JSON instead of an STL mesh.
        #[arg(long)]
        scene: bool,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
    },
    /// Build an na x nb x nc supercell.
    Supercell {
        /// Input path, or `-` for standard input.
        path: String,
        /// Repeats along a.
        na: u32,
        /// Repeats along b.
        nb: u32,
        /// Repeats along c.
        nc: u32,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
        /// Output format; defaults to the output extension or CIF.
        #[arg(long, value_enum)]
        format: Option<StructureFormat>,
    },
    /// Cut a slab along the (h k l) plane.
    Slab {
        /// Input path, or `-` for standard input.
        path: String,
        /// First Miller index.
        h: i32,
        /// Second Miller index.
        k: i32,
        /// Third Miller index.
        l: i32,
        /// Number of layers.
        #[arg(long, value_name = "N")]
        layers: u32,
        /// Vacuum above the slab in Angstrom.
        #[arg(long, value_name = "A")]
        vacuum: f64,
        /// Output path; defaults to standard output.
        #[arg(long, value_name = "PATH")]
        out: Option<String>,
        /// Output format; defaults to the output extension or CIF.
        #[arg(long, value_enum)]
        format: Option<StructureFormat>,
    },
    /// List the perceived bonds of the P1 cell.
    Bonds {
        /// Input path, or `-` for standard input.
        path: String,
    },
    /// List the chordless rings of the P1 cell.
    Rings {
        /// Input path, or `-` for standard input.
        path: String,
        /// Largest ring size in atoms.
        #[arg(long, value_name = "N", default_value_t = 6)]
        max_size: usize,
    },
    /// List the matched functional groups.
    Groups {
        /// Input path, or `-` for standard input.
        path: String,
    },
    /// List the periodic neighbors within a cutoff.
    Neighbors {
        /// Input path, or `-` for standard input.
        path: String,
        /// Cutoff radius in Angstrom.
        #[arg(long, value_name = "A")]
        cutoff: f64,
    },
    /// Minimum-image distance between two P1 atoms.
    Distance {
        /// Input path, or `-` for standard input.
        path: String,
        /// First atom index.
        i: usize,
        /// Second atom index.
        j: usize,
    },
    /// Angle i-j-k in degrees.
    Angle {
        /// Input path, or `-` for standard input.
        path: String,
        /// First atom index.
        i: usize,
        /// Pivot atom index.
        j: usize,
        /// Third atom index.
        k: usize,
    },
    /// Browse the space-group catalogue.
    Spacegroup {
        #[command(subcommand)]
        action: spacegroup::SpacegroupAction,
    },
    /// Detect the space group and Wyckoff positions.
    Symmetry {
        #[command(subcommand)]
        action: SymmetryAction,
    },
    /// Torsion i-j-k-l in degrees.
    Torsion {
        /// Input path, or `-` for standard input.
        path: String,
        /// First atom index.
        i: usize,
        /// Second atom index.
        j: usize,
        /// Third atom index.
        k: usize,
        /// Fourth atom index.
        l: usize,
    },
}