BUCToolkit 1.0b0__py3-none-any.whl

BUCToolkit/cli/input_stub.py

@@ -0,0 +1,140 @@
+#  Copyright (c) 2026.4.1, BUCToolkit.
+#  Authors: Pu Pengxin, Song Xin
+#  Version: 1.0b
+#  File: input_stub.py
+#  Environment: Python 3.12
+from typing import Any
+
+# The parameter dictionary in the format:
+# key: (value, type, description)
+CONFIG_STUB = {
+    "TASK": ("MD", str, "task name. Options: 'OPT', 'TS', 'VIB', 'NEB', 'MD', 'CMD', 'MC'"),
+    "START": (1, int, "0: from scratch; 1: load checkpoint from LOAD_CHK_FILE_PATH; 2: only load model parameters/weights"),
+    "VERBOSE": (1, int, "verbosity level for log output"),
+    "DEVICE": ("cuda:0", str, "the device on which the task would run"),
+    "BATCH_SIZE": (16, int, "the batch size of input data during calculation"),
+
+    # I/O configs
+    "LOAD_CHK_FILE_PATH": ("your/model/checkpoint/file/path", str, "path of model checkpoint to load"),
+    "OUTPUT_PATH": ("your/log/output/path", str, "path to save logs"),
+    "OUTPUT_POSTFIX": ("your_logfile_suffix", str, "suffix for log file name"),
+    "PREDICTIONS_SAVE_FILE": ("your/model/predictions/save/path", str, "path of saving predictions"),
+    "STRICT_LOAD": (True, bool, "whether to strictly load model parameter"),
+    "REDIRECT": (True, bool, "whether output training logs to OUTPUT_PATH or directly print on screen"),
+    "SAVE_PREDICTIONS": (True, bool, "only for predictions. Whether output predictions to a dump file"),
+    "DATA_TYPE": ("BS", str, "Data type. Options: 'POSCAR', 'OUTCAR', 'CIF', 'ASE_TRAJ', 'BS', 'OPT', 'MD'"),
+    "DATA_PATH": ("/your/data/path", str, "path of data used for calculation. If training, it is viewed as the training set"),
+    "DATA_NAME_SELECTOR": (".*$", str, "regular expression to select data names. Only matched names will be loaded"),
+    "FSDATA_PATH": ("your/final/state/data/path", str, "path for final state data, used for calculations requiring both initial and final states, e.g., CI-NEB"),
+    "DISPDATA_PATH": ("your/displacement/data/path", str, "path for displacement data, used for calculations requiring initial guess of a direction, e.g., Dimer"),
+    "VAL_SET_PATH": ("your/validation/set/path", str, "path for validation set, used for training that requires validation data"),
+    "VAL_SPLIT_RATIO": (0.1, float, "ratio of validation set in the total dataset. Ignored if VAL_SET_PATH is provided"),
+    "DATA_LOADER_KWARGS": ({}, dict, "other keyword arguments for data loader"),
+    "IS_SHUFFLE": (False, bool, "whether to randomly shuffle dataset before calculating"),
+
+    # Training
+    "TRAIN": {
+        "EPOCH": (10, int, "number of training epochs"),
+        "VAL_BATCH_SIZE": (20, int, "batch size for validation. default is the same as BATCH_SIZE"),
+        "VAL_PER_STEP": (100, int, "validate every VAL_PER_STEP steps. step = BATCH_SIZE * ACCUMULATE_STEP"),
+        "VAL_IF_TRN_LOSS_BELOW": (1e5, float, "only validating after training loss < VAL_IF_TRN_LOSS_BELOW"),
+        "ACCUMULATE_STEP": (12, int, "gradient accumulation steps"),
+        "LOSS": ("Energy_Loss", str, "loss function name. Options: 'MSE', 'MAE', 'Hubber', 'CrossEntropy', 'Energy_Force_Loss', 'Energy_Loss'"),
+        "LOSS_CONFIG": {
+            "loss_E": ("SmoothMAE", str, "loss function for energy")
+        },
+        "METRICS": (["E_MAE", "E_R2"], list, "list of metrics to compute. Options: E_MAE, F_MAE, F_MaxE, E_R2, MSE, MAE, R2, RMSE"),
+        "METRICS_CONFIG": ({}, dict, "other keyword arguments for metrics"),
+        "OPTIM": ("AdamW", str, "optimizer name. Options: 'Adam', 'SGD', 'AdamW', 'Adadelta', 'Adagrad', 'ASGD', 'Adamax', 'FIRE'"),
+        "OPTIM_CONFIG": {
+            "lr": (2e-4, float, "learning rate")
+        },
+        "LAYERWISE_OPTIM_CONFIG": {
+            "force_block.*": ({"lr": 5e-4}, dict, "learning rate for layers matching regex 'force_block.*'"),
+            "energy_block.*": ({"lr": 2e-4}, dict, "learning rate for layers matching regex 'energy_block.*'"),
+            ".*_bias_layer.*": ({"lr": 2e-4}, dict, "learning rate for layers matching regex '.*_bias_layer.*'")
+        },
+        "GRAD_CLIP": (True, bool, "whether to toggle on gradient clip"),
+        "GRAD_CLIP_MAX_NORM": (10.0, float, "maximum grad. norm to clip"),
+        "GRAD_CLIP_CONFIG": ({}, dict, "other kwargs for torch.nn.utils.clip_grad_norm_"),
+        "LR_SCHEDULER": (None, str, "learning rate scheduler name. Options: 'StepLR', 'ExponentialLR', 'ChainedScheduler', 'ConstantLR', 'LambdaLR', 'LinearLR', 'CosineAnnealingWarmRestarts', 'CyclicLR', 'MultiStepLR', 'CosineAnnealingLR', None"),
+        "LR_SCHEDULER_CONFIG": ({}, dict, "keyword arguments for the learning rate scheduler"),
+        "EMA": (False, bool, "whether to toggle on EMA (Exponential Moving Average)"),
+        "EMA_DECAY": (0.999, float, "EMA decay rate"),
+    },
+
+    # Relaxation
+    "RELAXATION": {
+        "ALGO": ("FIRE", str, "optimization algorithm. Options: CG, BFGS, FIRE"),
+        "ITER_SCHEME": ("PR+", str, "conjugate gradient iteration scheme. Only for ALGO=CG. Options: 'PR+', 'FR', 'PR', 'WYL'"),
+        "E_THRES": (1e4, float, "threshold of energy difference for convergence"),
+        "F_THRES": (0.05, float, "threshold of max force for convergence"),
+        "MAXITER": (300, int, "maximum number of iterations"),
+        "STEPLENGTH": (0.5, float, "initial step length"),
+        "USE_BB": (True, bool, "whether to use Barzilai-Borwein I steplength as initial steplength"),
+        "LINESEARCH": ("B", str, "line search method. 'Backtrack' with Armijo's condition, 'Wolfe' for weak Wolfe condition, 'Exact' for exact linear search"),
+        "LINESEARCH_MAXITER": (8, int, "maximum iterations of line search per outer iteration"),
+        "LINESEARCH_THRES": (0.02, float, "threshold for exact line search"),
+        "LINESEARCH_FACTOR": (0.5, float, "shrinkage factor for backtracking"),
+        "REQUIRE_GRAD": (False, bool, "whether to toggle on auto-gradient during calculation"),
+    },
+
+    # Transition state
+    "TRANSITION_STATE": {
+        "ALGO": ("DIMER", str, "algorithm for transition state search. Options: DIMER"),
+        "X_DIFF_ATTR": ("x_dimer", str, "attribute name of initial dimer direction"),
+        "E_THRES": (1e-4, float, "energy difference threshold for convergence"),
+        "TORQ_THRES": (1e-2, float, "torque threshold during rotation process, i.e., residuals of eigen vector"),
+        "F_THRES": (5e-2, float, "force threshold for convergence"),
+        "MAXITER_TRANS": (300, int, "maximum number of translation steps"),
+        "MAXITER_ROT": (5, int, "maximum number of rotation steps"),
+        "MAX_STEPLENGTH": (0.5, float, "maximum step length"),
+        "DX": (0.1, float, "finite difference length for Hessian-vector product"),
+        "REQUIRE_GRAD": (False, bool, "whether to toggle on auto-gradient during calculation"),
+    },
+
+    # Vibration analyses
+    "VIBRATION": {
+        "METHOD": ("Coord", str, "method for vibration analysis. 'Coord' for finite difference, 'Grad' for auto-grad"),
+        "BLOCK_SIZE": (1, int, "block size for tensor/vectorize parallelization"),
+        "DELTA": (0.01, float, "finite difference length for Hessian-vector product"),
+    },
+
+    # NEB transition state
+    "NEB": {
+        "ALGO": ("CI-NEB", str, "NEB algorithm. Options: CI-NEB"),
+        "N_IMAGES": (7, int, "number of images for CI-NEB calculation"),
+        "SPRING_CONST": (5.0, float, "spring constant for NEB"),
+        "OPTIMIZER": ("FIRE", str, "optimizer for CI-NEB. Currently only FIRE supported"),
+        "STEPLENGTH": (0.2, float, "initial step length for optimizer"),
+        "E_THRESHOLD": (1e-3, float, "energy difference threshold for convergence"),
+        "F_THRESHOLD": (0.05, float, "force threshold for convergence"),
+        "MAXITER": (20, int, "maximum number of iterations"),
+        "REQUIRE_GRAD": (False, bool, "whether to toggle on auto-gradient during calculation"),
+    },
+
+    # Molecular dynamics
+    "MD": {
+        "ENSEMBLE": ("NVT", str, "MD ensemble. Options: NVE, NVT"),
+        "THERMOSTAT": ("CSVR", str, "thermostat for NVT ensemble. Options: Langevin, VR, Nose-Hoover, CSVR"),
+        "THERMOSTAT_CONFIG": {
+            "DAMPING_COEFF": (0.01, float, "damping coefficient for Langevin thermostat. Unit: fs^-1"),
+            "TIME_CONST": (120, float, "time constant for CSVR thermostat. Unit: fs"),
+        },
+        "TIME_STEP": (1, float, "MD time step. Unit: fs"),
+        "MAX_STEP": (100, int, "total number of MD steps. Total time = TIME_STEP * MAX_STEP"),
+        "T_INIT": (298.15, float, "initial temperature. Unit: K. For NVE, used to generate random initial velocities"),
+        "OUTPUT_COORDS_PER_STEP": (1, int, "frequency of outputting atom coordinates. If verbose=3, velocities also output"),
+        "CONSTRAINTS_FILE": ("./constraints.py", str, "path to constraints function file"),
+        "CONSTRAINTS_FUNC": ("func", str, "name of constraints function in CONSTRAINTS_FILE"),
+        "REQUIRE_GRAD": (False, bool, "whether to toggle on auto-gradient during calculation"),
+    },
+
+    # Model configs
+    "MODEL_FILE": ("your/model/file/path/template_model.py", str, "path to model definition file"),
+    "MODEL_NAME": ("YourModel", str, "name of the model class in MODEL_FILE"),
+    "MODEL_CONFIG": {
+        "hyperparameter1": ("xxx", Any, "Model hyperparameter"),
+        "hyperparameter2": ("xxx", Any, "Model hyperparameter"),
+    },
+}

BUCToolkit/cli/main.py

@@ -0,0 +1,368 @@
+"""
+The Traditional Style Main Function/Program that runs tasks by a single command line with
+input files and args.
+"""
+#  Copyright (c) 2026.3.27, BUCToolkit.
+#  Authors: Pu Pengxin, Song Xin
+#  Version: 0.9a
+#  File: main.py
+#  Environment: Python 3.12
+
+import sys
+import argparse
+import time
+import os
+import warnings
+from typing import Dict, Any, Callable
+import importlib.util
+import hashlib
+
+import yaml
+import torch as th
+
+import BUCToolkit as bt
+from BUCToolkit.BatchGenerate.coords_interp import direction_for_finite_diff
+from BUCToolkit.cli.print_logo import generate_display_art
+import BUCToolkit.api as api
+from BUCToolkit.api.DataLoaders import PyGDataLoader, ISFSPyGDataLoader
+import BUCToolkit.Preprocessing.load_files as load_files
+
+
+def parse_center_input_file(path: str):
+    """
+    Parse the input file with the highest level that control the overall task.
+    Args:
+        path: path of the input file.
+
+    Returns:
+        runner: the api of the task. Use `runner.run(model)` to run the task.
+
+    """
+    if not os.path.isfile(path):
+        raise FileNotFoundError(path)
+
+    with open(path, 'r') as f:
+        config: Dict[str, Any] = yaml.safe_load(f)
+
+    TASKS_TYPE = {
+        'TRAIN': api.Trainer,
+        'PREDICT': api.Predictor,
+        'OPT': api.StructureOptimization,
+        'TS': api.StructureOptimization,
+        'VIB': api.VibrationAnalysis,
+        'NEB': api.ClimbingImageNudgedElasticBand,
+        'MD': api.MolecularDynamics,
+        'CMD': api.ConstrainedMolecularDynamics,
+        'MC': api.MonteCarlo,
+    }
+    TASKS_TYPE_ALIAS = {
+        'TRAIN': 'TRAIN',
+        'PREDICT': 'PREDICT',
+        'PREDICTION': 'PREDICT',
+        'OPT': 'OPT',
+        'STRUCTURE_OPTIMIZATION': 'OPT',
+        'STRUC_OPT': 'OPT',
+        'DIMER': 'TS',
+        'TS': 'TS',
+        'VIB': 'VIB',
+        'VIBRATIONAL_ANALYSIS': 'VIB',
+        'NEB': 'NEB',
+        'CINEB': 'NEB',
+        'CI_NEB': 'NEB',
+        'MD': 'MD',
+        'MOLECULAR_DYNAMICS': 'MD',
+        'CMD': 'CMD',
+        'CONSTRAINED_MOLECULAR_DYNAMICS': 'CMD',
+        'CONSTR_MD': 'CMD',
+        'MC': 'MC',
+        'MONTE_CARLO': 'MC',
+    }
+
+    # Section: check task
+    task_type = config.get('TASK', None)
+    if task_type is None:
+        raise ValueError(
+            'Task type is missing. '
+            f'You must specify a task_type by argument `TASK` in the {path} file.\n'
+            f'Available `TASK` values are:\n{", ".join(TASKS_TYPE_ALIAS.keys())} '
+        )
+    else:
+        task_type: str
+        task_type = task_type.upper()
+    if task_type not in TASKS_TYPE_ALIAS:
+        raise ValueError(
+            'Task type is invalid. '
+            f'Available `TASK` values are:\n{", ".join(TASKS_TYPE_ALIAS.keys())}'
+        )
+    else:
+        task_type = TASKS_TYPE_ALIAS[task_type]
+
+    # Section: load model
+    model_file = config.get('MODEL_FILE', None)
+    model_name = config.get('MODEL_NAME', None)
+    if model_file is None:
+        raise ValueError(f"`MODEL_FILE` must be specified.")
+    if model_name is None:
+        raise ValueError(f"`MODEL_NAME` must be specified.")
+    udf_model = load_model(model_file, model_name)
+
+    # Section: load data
+    data_type = config.get('DATA_TYPE', 'POSCAR').upper()
+    data_path = config.get('DATA_PATH', '')
+    data_selector = config.get('DATA_NAME_SELECTOR', None)
+    if data_path == '': raise ValueError(f'`DATA_PATH` is not defined.')
+    data_loader_kwargs = config.get('DATA_LOADER_KWARGS', {})
+    data: bt.Structures = load_data(data_type, data_path, data_loader_kwargs)
+    if data_selector is not None:
+        data = data.select_by_sample_id(rf"{data_selector}")
+        if len(data) == 0:
+            raise RuntimeError(f"No data matches the pattern given by `DATA_NAME_SELECTOR`. BYE!")
+    is_shuffle = config.get('IS_SHUFFLE', False)
+
+    if task_type == 'TRAIN':
+        # handle the validation set data
+        val_set_path = config.get('VAL_SET_PATH', None)
+        validation_ratio = config.get('VAL_SPLIT_RATIO', None)
+        if val_set_path is not None:
+            val_data = load_data(data_type, val_set_path, data_loader_kwargs)
+            if data_selector is not None:
+                val_data = val_data.select_by_sample_id(rf"{data_selector}")
+        elif validation_ratio is not None:
+            # check validation if ratio correct
+            validation_ratio = float(validation_ratio)
+            if validation_ratio >= 1. or validation_ratio <= 0.:
+                raise ValueError(f"`VAL_SPLIT_RATIO` must be in interval (0, 1), but got {validation_ratio}.")
+            n_val = int(validation_ratio * len(data))
+            if n_val >= len(data) or n_val <= 0:
+                raise ValueError(
+                    f"Unreasonable `VAL_SPLIT_RATIO` value `{validation_ratio}`, "
+                    f"which will cause {n_val} validation samples and {len(data) - n_val} training samples."
+                )
+            val_data = data[:n_val]
+            data = data[n_val:]
+        else:
+            raise ValueError(f"THERE IS NO VALIDATION DATA SPECIFIED. TRAINING MAY BE MEANINGLESS.")
+
+        data_list = bt.preprocessing.CreatePygData(1).feat2data_list(data, n_core=1)
+        val_data_list = bt.preprocessing.CreatePygData(1).feat2data_list(val_data, n_core=1)
+
+        trn_ener = [data[atm.idx].Energies[0] for atm in data_list]
+        if data.Forces is None:
+            trn_forc = None
+        else:
+            trn_forc = [data[atm.idx].Forces[0] for atm in data_list]
+        train_data = {'data': data_list, 'labels': {'energy': trn_ener, 'forces': trn_forc}}
+        val_ener = [val_data[atm.idx].Energies[0] for atm in val_data_list]
+        if data.Forces is None:
+            val_forc = None
+        else:
+            val_forc = [val_data[atm.idx].Forces[0] for atm in val_data_list]
+        valid_data = {'data': val_data_list, 'labels': {'energy': val_ener, 'forces': val_forc}}
+        dataset_args = (train_data, valid_data)
+
+    elif task_type == 'NEB' or task_type == 'CMD':  # They use ISFSDataLoader
+        # handle the final state configuration data
+        fs_data_path = config.get('FSDATA_PATH', None)
+        if fs_data_path is not None:
+            fs_data = load_data(data_type, fs_data_path, data_loader_kwargs)
+        else:
+            raise ValueError(f"`FSDATA_PATH` is not defined. For TASK `{task_type}`, "
+                             f"you must specify the final-state-configuration data path by `FSDATA_PATH`.")
+        is_data_list = bt.preprocessing.CreatePygData(1).feat2data_list(data, n_core=1)
+        fs_data_list = bt.preprocessing.CreatePygData(1).feat2data_list(fs_data, n_core=1)
+        run_data = {'dataIS': is_data_list, 'dataFS': fs_data_list}
+        dataset_args = (run_data,)
+
+    elif task_type == 'TS':  # Need a dimer initial guess
+        # handle the final state configuration data
+        disp_data_path = config.get('DISPDATA_PATH', None)
+        displace_flag = config.get('TRANSITION_STATE', None)
+        if displace_flag is None:
+            raise ValueError(
+                f"Transition state search is required but input arguments not provided. "
+                f"Please set `TRANSITION_STATE` section in the config file. "
+            )
+        else:
+            displace_flag = displace_flag.get('X_DIFF_ATTR', None)
+
+        is_data_list = bt.preprocessing.CreatePygData(1).feat2data_list(data, n_core=1)
+
+        if displace_flag is not None:  # IF DISPDATA_PATH is given, canonically use data read from DISPDATA_PATH
+            if disp_data_path is not None:
+                disp_data = load_data(data_type, disp_data_path, data_loader_kwargs)
+                for i, dat in enumerate(is_data_list):
+                    disp_tensor = th.as_tensor(disp_data.Coords[i])
+                    setattr(dat, str(displace_flag), disp_tensor)
+            else:
+                fs_data_path = config.get('FSDATA_PATH', None)  # ELIF FSDATA_PATH, use interpolated middle point of is/fs conf.
+                if fs_data_path is not None:
+                    fs_data = load_data(data_type, fs_data_path, data_loader_kwargs)
+                    # convert to displacement by interpolation
+                    for i, dat in enumerate(is_data_list):
+                        disp_coo, diff = direction_for_finite_diff(dat.pos, fs_data.Coords[i], dat.fixed)
+                        setattr(dat, 'pos', disp_coo)
+                        setattr(dat, str(displace_flag), diff)
+                else:
+                    warnings.warn(f"`X_DIFF_ATTR` is set but no displacement is provided. `X_DIFF_ATTR` will be ignored.")
+                    for i, dat in enumerate(is_data_list):
+                        setattr(dat, str(displace_flag), None)
+        run_data = {'data': is_data_list, 'labels': None}
+        dataset_args = (run_data,)
+
+    else:
+        data_list = bt.preprocessing.CreatePygData(1).feat2data_list(data, n_core=1)
+        run_data = {'data': data_list, 'labels': None}
+        dataset_args = (run_data,)
+
+    # dataloader
+    if task_type == 'NEB' or task_type == 'CMD':
+        dataloader = ISFSPyGDataLoader
+    else:
+        dataloader = PyGDataLoader
+
+    # set runner
+    runner = TASKS_TYPE[task_type](path, 'pyg')
+    runner.set_dataset(*dataset_args, )  # type: ignore
+    runner.set_dataloader(dataloader, {'shuffle': is_shuffle})
+    # set constraints function
+    if task_type == 'CMD':
+        constr_file = config.get('CONSTRAINTS_FILE', None)
+        constr_name = config.get('CONSTRAINTS_FUNC', None)
+        if constr_file is None:
+            raise ValueError(f"`CONSTRAINTS_FILE` must be specified.")
+        if constr_name is None:
+            raise ValueError(f"`CONSTRAINTS_FUNC` must be specified.")
+        constr_func = load_model(constr_file, constr_name)
+        runner.set_constr_func(constr_func)
+
+    return task_type, runner, udf_model
+
+
+def load_data(data_type, data_path, data_loader_kwargs):
+    """
+    A data loader
+    Returns: BatchStructure formated data
+
+    """
+    DATA_TYPE = {
+        'external': {
+            'POSCAR': load_files.POSCARs2Feat,
+            'OUTCAR': load_files.OUTCAR2Feat,
+            'CIF': load_files.Cif2Feat,
+            'ASE_TRAJ': load_files.ASETraj2Feat,
+        },
+        'buildin': {
+            'BS': bt.load,
+            'OPT': bt.read_opt_structures,
+            'MD': bt.read_md_traj,
+        }
+    }
+
+    if data_type in DATA_TYPE['external']:
+        data_reader = DATA_TYPE['external'][data_type](data_path)
+        data = data_reader.read(**data_loader_kwargs)
+    elif data_type in DATA_TYPE['buildin']:
+        data_reader = DATA_TYPE['buildin'][data_type]
+        data = data_reader(data_path, **data_loader_kwargs)
+    else:
+        raise ValueError(
+            f'Data type "{data_type}" is invalid. '
+            f'Available `DATA_TYPE` values are:\n{', '.join(DATA_TYPE['external'].keys())}, {', '.join(DATA_TYPE['buildin'].keys())}'
+        )
+
+    return data
+
+
+def load_model(func_file_path, func_name) -> Callable:
+    """
+    Load user defined model.
+    Args:
+        func_file_path: user-defined function file path
+        func_name: user-defined function name
+
+    Returns:
+
+    """
+    if not os.path.isfile(func_file_path):
+        raise FileNotFoundError(f"File {func_file_path} not found.")
+
+    realpath = os.path.realpath(func_file_path, strict=True)
+    enc_path = hashlib.md5(realpath.encode()).hexdigest()  # hash the file name
+    module_name = f"udf_{enc_path}"
+    spec = importlib.util.spec_from_file_location(module_name, func_file_path)
+    if spec is None:
+        raise ImportError(f"Cannot load module from {func_file_path}.")
+
+    module = importlib.util.module_from_spec(spec)
+
+    # run
+    spec.loader.exec_module(module)
+
+    # get target function
+    udf = getattr(module, func_name, None)
+    if udf is None:
+        raise AttributeError(f"Function/Model {func_name} not found in {func_file_path}.")
+
+    return udf
+
+def launch_task(inp):
+    """
+    launch a task.
+    Args:
+        inp: the input file path.
+
+    Returns: None
+
+    """
+    task_type, runner, udf_model = parse_center_input_file(inp)
+    if task_type == 'TRAIN':
+        runner.train(udf_model)
+    elif task_type == 'TS':
+        runner.ts(udf_model)
+    elif task_type == 'OPT':
+        runner.relax(udf_model)
+    else:
+        runner.run(udf_model)
+
+def main():
+    """
+    Main program interface
+    Usage Convention:
+        buctoolkit -i xxx.inp -o xxx.oup
+    """
+    parser = argparse.ArgumentParser(
+        description=f'BUCToolkit MAIN PROGRAM INTERFACES\n{generate_display_art()}',
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument('-i', '--input', help='The path to input file.', required=True)
+    parser.add_argument(
+        '-o', '--output',
+        help='The path to output file. It will change the stdout. One can also cleanly redirect output by setting '
+             '`REDIRECT: true`, `OUTPUT_PATH: your/path/to/output/log/`, and `OUTPUT_POSTFIX: your_log_postfix` '
+             'in the input file. If so, this argument will be ignored.',
+        default=None,
+        type=str,
+    )
+
+    opened_file = None
+    try:
+        if len(sys.argv) == 1:  # Enter the interactive CLI
+            bt.cli.run_base_cli()
+        else:  # otherwise directly run in one-line command
+            args = parser.parse_args()
+            if args.output is not None:
+                _rename = args.output
+                while os.path.exists(_rename):
+                    _rename += '_1'
+                warnings.warn(f'Output file `{args.output}` already exists. Rename to {_rename}.')
+                opened_file = open(args.output, 'w')
+                sys.stdout = opened_file
+            launch_task(args.input)
+    finally:
+        if opened_file is not None:
+            if not opened_file.closed:
+                opened_file.close()
+        sys.stdout = sys.__stdout__
+
+if __name__ == '__main__':
+    main()

BUCToolkit/cli/print_logo.py

@@ -0,0 +1,149 @@
+
+from BUCToolkit._version import __version__
+import time
+
+def generate_display_art() -> str:
+    letters = {
+        'B': [
+            "BBBBBB ",
+            "B     B",
+            "B     B",
+            "BBBBBB ",
+            "B     B",
+            "B     B",
+            "BBBBBB "
+        ],
+        'U': [
+            "U     U",
+            "U     U",
+            "U     U",
+            "U     U",
+            "U     U",
+            "U     U",
+            " UUUUU "
+        ],
+        'C': [
+            " CCCCC ",
+            "C     C",
+            "C      ",
+            "C      ",
+            "C      ",
+            "C     C",
+            " CCCCC "
+        ],
+        'T': [
+            "TTTTTTT",
+            "   T   ",
+            "   T   ",
+            "   T   ",
+            "   T   ",
+            "   T   ",
+            "   T   "
+        ],
+        'O': [
+            " OOOOO ",
+            "O     O",
+            "O     O",
+            "O     O",
+            "O     O",
+            "O     O",
+            " OOOOO "
+        ],
+        'L': [
+            "LL     ",
+            "LL     ",
+            "LL     ",
+            "LL     ",
+            "LL     ",
+            "LL     ",
+            "LLLLLLL"
+        ],
+        'K': [
+            "K     K",
+            "K   K  ",
+            "K K    ",
+            "KK     ",
+            "K K    ",
+            "K   K  ",
+            "K     K"
+        ],
+        'I': [
+            "   II  ",
+            "   II  ",
+            "   II  ",
+            "   II  ",
+            "   II  ",
+            "   II  ",
+            "   II  "
+        ]
+    }
+
+    # Target
+    word = "BUCTOOLKIT"
+
+    # 7 Lines to construct Letter Plot
+    art_lines = ["" for _ in range(7)]
+    for ch in word:
+        ch_art = letters.get(ch, letters['O'])
+        for i in range(7):
+            art_lines[i] += ch_art[i] + " "     # one space as a delimiter
+
+    # drop rest spaces
+    art_lines = [line.rstrip() for line in art_lines]
+    art_width = max(len(line) for line in art_lines)
+    art_height = len(art_lines)
+
+    # Monitor Shape
+    left_margin = 4
+    top_margin = 2
+    internal_width = art_width + 2 * left_margin
+    internal_height = art_height + 2 * top_margin
+
+    # Inner Letters
+    screen_lines = []
+    for _ in range(internal_height):
+        screen_lines.append([" "] * internal_width)
+
+    # ASCII plot
+    start_row = top_margin
+    start_col = left_margin
+    for i, line in enumerate(art_lines):
+        for j, ch in enumerate(line):
+            if start_row + i < internal_height and start_col + j < internal_width:
+                screen_lines[start_row + i][start_col + j] = ch
+
+    screen_content = ["".join(row) for row in screen_lines]
+
+    copyright_lines = (f"  BUCToolkit {__version__}. Copyright (c) 2024-{time.strftime("%Y")} "
+                       f"Authors: Pu Pengxin, Song Xin, etc.  " + " "*8)
+    screen_content.append(copyright_lines)
+
+    # Monitor Edges
+    top_border = "+" + "=" * internal_width + "+"
+    bottom_border = "+" + "=" * internal_width + "+"
+    bordered_lines = [top_border]
+    for line in screen_content:
+        bordered_lines.append("|" + line + "|")
+    bordered_lines.append(bottom_border)
+
+    # Monitor Steadier
+    base_width = internal_width - 4
+    if base_width < 6:
+        base_width = 6
+    base_pad = (internal_width - base_width) // 2 + 1
+    base_line = " " * base_pad + "|" + "_" * (base_width - 2) + "|" + " " * (internal_width - base_pad - base_width)
+    bordered_lines.append(base_line)
+    foot_width = base_width + 2
+    foot_pad = (internal_width - foot_width) // 2 + 1
+    foot_line = " " * foot_pad + "|" + "_" * (foot_width - 2) + "|" + " " * (internal_width - foot_pad - foot_width)
+    bordered_lines.append(foot_line)
+
+    # Copyright info
+    #copyright_lines = f"   BUCToolkit {__version__}. Copyright (c) 2024-{time.strftime("%Y")} Authors: Pu Pengxin, Song Xin, etc."
+    #bordered_lines.append(copyright_lines)
+
+    return "\n".join(bordered_lines)
+
+
+if __name__ == "__main__":
+    print(generate_display_art())

BUCToolkit/cli/template_model.py

@@ -0,0 +1,6 @@
+#  Copyright (c) 2026.3.28, BUCToolkit.
+#  Authors: Pu Pengxin, Song Xin
+#  Version: 1.0b
+#  File: template_model.py
+#  Environment: Python 3.12
+from EqV2.equiformer_v2.nets import EquiformerV2_OC20 as EqV2