cheq 0.5.1

A pure Rust library and CLI for fast, dynamic partial charge calculation via the QEq method.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

use clap::{Args, Parser, ValueEnum};
use std::path::PathBuf;

const AUTHORS: &str = "Tony Kan, Ted Yu, William A. Goddard III";
const ABOUT: &str =
    "A command-line tool for calculating dynamic partial atomic charges using the QEq method.";
const COPYRIGHT: &str = "Copyright (c) 2025 California Institute of Technology, Materials and Process Simulation Center (MSC)";
const HELP_TEMPLATE: &str = "\
{before-help}{name} {version}
{author-with-newline}{about-with-newline}
{usage-heading} {usage}

{all-args}{after-help}
";

#[derive(Parser)]
#[command(
    author = AUTHORS,
    version,
    about = ABOUT,
    after_help = COPYRIGHT,
    help_template = HELP_TEMPLATE,
)]
#[command(propagate_version = true)]
pub struct Cli {
    /// Input file containing molecular structure in XYZ format.
    ///
    /// Use '-' to read from standard input. The XYZ format should contain the number of atoms
    /// on the first line, a comment on the second line, followed by lines with element symbol
    /// (or atomic number) and x, y, z coordinates.
    #[arg(value_name = "INPUT")]
    pub input: String,

    #[command(flatten)]
    pub output: OutputOptions,

    #[command(flatten)]
    pub calculation: CalculationOptions,

    #[command(flatten)]
    pub solver: SolverOptions,
}

/// Options for controlling the output format and destination.
#[derive(Args)]
#[command(next_help_heading = "Output Options")]
pub struct OutputOptions {
    /// Output file path.
    ///
    /// If not specified, results are written to standard output.
    #[arg(short, long, value_name = "FILE")]
    pub output: Option<PathBuf>,

    /// Output format for the results.
    #[arg(short, long, value_enum, default_value_t = OutputFormat::Pretty)]
    pub format: OutputFormat,

    /// Number of decimal places to display for floating-point values.
    #[arg(short, long, default_value_t = 6)]
    pub precision: usize,
}

/// Options for controlling the calculation parameters.
#[derive(Args)]
#[command(next_help_heading = "Calculation Options")]
pub struct CalculationOptions {
    /// Custom parameters file in TOML format.
    ///
    /// If not specified, built-in default parameters are used.
    #[arg(short = 'P', long, value_name = "FILE")]
    pub params: Option<PathBuf>,

    /// Total charge of the molecular system.
    #[arg(short = 'q', long, default_value_t = 0.0)]
    pub total_charge: f64,
}

/// Options for controlling the solver behavior.
#[derive(Args)]
#[command(next_help_heading = "Solver Options")]
pub struct SolverOptions {
    /// Convergence tolerance for charge equilibration.
    ///
    /// The solver iterates until the RMS change in charges falls below this threshold.
    #[arg(long, default_value_t = 1e-6)]
    pub tolerance: f64,

    /// Maximum number of iterations allowed.
    #[arg(long, default_value_t = 100)]
    pub max_iterations: u32,

    /// Screening parameter scale factor.
    ///
    /// Multiplier for the orbital screening strength in Coulomb calculations.
    #[arg(long, default_value_t = 0.5)]
    pub lambda_scale: f64,

    /// Enable nonlinear hydrogen hardness update each iteration.
    #[arg(long, default_value_t = true, action = clap::ArgAction::Set)]
    pub hydrogen_scf: bool,

    /// Basis functions to use for Coulomb integrals.
    #[arg(long, value_enum, default_value_t = CliBasisType::Sto)]
    pub basis: CliBasisType,

    /// Damping strategy for the SCF iteration.
    #[arg(long, value_enum, default_value_t = CliDampingStrategy::Auto)]
    pub damping: CliDampingStrategy,

    /// Damping factor (0.0-1.0). Used as fixed value or initial value for auto damping.
    #[arg(long, default_value_t = 0.4)]
    pub damping_factor: f64,
}

/// Output format for the calculation results.
#[derive(Clone, ValueEnum)]
pub enum OutputFormat {
    /// Pretty-printed table with atom indices, elements, positions, and charges.
    Pretty,
    /// XYZ format with charges appended to each atom line.
    Xyz,
    /// Comma-separated values with columns: index, element, x, y, z, charge.
    Csv,
    /// JSON object containing atoms array and metadata.
    Json,
}

/// Basis function types for Coulomb integral calculations.
#[derive(Clone, ValueEnum)]
pub enum CliBasisType {
    /// Slater-Type Orbitals (exact).
    Sto,
    /// Gaussian-Type Orbitals (approximate).
    Gto,
}

/// Damping strategies for the SCF iteration.
#[derive(Clone, ValueEnum)]
pub enum CliDampingStrategy {
    /// Auto-adjust damping based on convergence.
    Auto,
    /// Fixed damping factor.
    Fixed,
    /// No damping.
    None,
}