geom.functions.general ====================== .. py:module:: geom.functions.general Functions --------- .. autoapisummary:: geom.functions.general.read_command_line geom.functions.general.print_help geom.functions.general.parse_translation geom.functions.general.parse_rotation geom.functions.general.parse_mirror geom.functions.general.parse_merge geom.functions.general.parse_rdkit geom.functions.general.parse_min geom.functions.general.parse_center geom.functions.general.parse_create geom.functions.general.parse_dimer_argument geom.functions.general.parse_bowtie_argument geom.functions.general.parse_alloy_arguments geom.functions.general.check_file_exists geom.functions.general.check_FCC geom.functions.general.check_FCC_or_BCC geom.functions.general.check_file_extension geom.functions.general.check_file_extension_rdkit geom.functions.general.check_accepted_parameters geom.functions.general.check_dir_axis geom.functions.general.create_results_geom geom.functions.general.extract_string_or_list geom.functions.general.extract_value geom.functions.general.extract_value_or_default geom.functions.general.check_equal_extensions Module Contents --------------- .. py:function:: read_command_line(argv, inp) Parses command-line arguments and determines the operation mode. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Calls the appropriate parsing function or displays help. :rtype: None .. rubric:: Notes - If no arguments are provided, an error is raised. - Recognizes different command-line options and triggers the corresponding function. - Prints help if `-h` or `-help` is passed. .. py:function:: print_help() Prints the help message with usage instructions and exits the program. :returns: Displays the help text and terminates execution. :rtype: None .. py:function:: parse_translation(argv, inp) Parses translation-related command-line arguments. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets translation-related attributes in `inp`. :rtype: None .. rubric:: Notes - Handles both controlled distance translation (`-t`), simple shift translation (`-t1`), and translation of geometrical center to the center of coordinates (`-tc`). - Extracts input filenames, translation parameters, and verbosity settings. .. py:function:: parse_rotation(argv, inp) Parses rotation-related command-line arguments. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets rotation-related attributes in `inp`. :rtype: None .. rubric:: Notes - Handles both list-based rotation (`-r`) and single-angle rotation (`-r1`). - Extracts input filenames and rotation parameters. .. py:function:: parse_mirror(argv, inp) Parses command-line arguments for performing a mirror reflection. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets mirroring attributes in `inp`. :rtype: None .. py:function:: parse_merge(argv, inp) Parses command-line arguments for merging geometries. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets merging attributes in `inp`. :rtype: None .. rubric:: Notes - Requires two geometry files and a cutoff distance. .. py:function:: parse_rdkit(argv, inp) TO DO .. py:function:: parse_min(argv, inp) Parses command-line arguments for calculating the minimum distance between two geometries. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets minimum distance calculation attributes in `inp`. :rtype: None .. py:function:: parse_center(argv, inp) Parses command-line arguments for computing the geometric center of a structure. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets geometric centering attributes in `inp`. :rtype: None .. py:function:: parse_create(argv, inp) Parses command-line arguments for generating different types of geometries. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance containing input parameters. :type inp: input_class :returns: Sets attributes in `inp` for geometry generation. :rtype: None .. rubric:: Notes - Handles the creation of graphene structures, nanoparticles, and bulk metal structures. - Validates input parameters and extracts atomic and structural properties. .. py:function:: parse_dimer_argument(argv, inp, output) Parses dimer-related command-line arguments and updates the `inp` object. :param argv: Command-line arguments list. :type argv: list[str] :param inp: The input class instance where dimer attributes are stored. :type inp: input_class :param output: The output module for error handling. :type output: module :returns: Updates inp.create_dimer, inp.distances, and inp.dir_axis_input. :rtype: None .. rubric:: Notes - Searches for "-dimer" in argv. - Reads the next argument as a float and stores it in inp.distances as a list. - Reads the following argument as an axis specification (+x, -y, +z, etc.). - Ensures the extracted values are valid. .. py:function:: parse_bowtie_argument(argv, inp, output) Parses bowtie-related command-line arguments and updates the `inp` object. :param argv: List of command-line arguments. :type argv: list[str] :param inp: An instance of the input class where bowtie attributes are stored. :type inp: input_class :param output: The output module used for error handling. :type output: module :returns: This function does not return a value but updates `inp.create_bowtie`, `inp.distances`, and `inp.dir_axis_input`. :rtype: None :raises ValueError: If bowtie arguments are missing or contain invalid values. .. rubric:: Notes - This function checks if "-bowtie" is present in `argv`. - If found, it ensures that the bowtie structure is only available for tip, pyramid (square/pentagonal base) , cone, and microscope structures. - The function then extracts the bowtie distance (must be a positive float). - If any validation fails, it calls `output.error()` to handle errors. .. py:function:: parse_alloy_arguments(argv, inp, output) Parses alloy-related command-line arguments and updates the `inp` object. :param argv: Command-line arguments list. :type argv: list[str] :param inp: The input class instance where alloy attributes are stored. :type inp: input_class :param output: The output module for error handling. :type output: module :returns: Updates `inp` attributes based on the parsed alloy arguments. :rtype: None .. rubric:: Notes - Handles both cases: 1. `-alloy atom_type -percentual float` 2. `-alloy -percentual float` - Ensures `inp.alloy_perc` is a **valid float** and **between 0 and 100**. - If atom type is omitted, it defaults to `inp.atomtype`. .. py:function:: check_file_exists(infile) Checks if a given file exists. :param infile: Path to the input file. :type infile: str :returns: Raises an error if the file is not found. :rtype: None .. py:function:: check_FCC(atomtype, string) Checks if the given metallic atom type follows an FCC arrangement. :param atomtype: Type of metal atom. :type atomtype: str :param string: Structure name being validated. :type string: str :returns: Raises an error if the atom type is not FCC. :rtype: None .. py:function:: check_FCC_or_BCC(atomtype) Checks if the given metallic atom type follows either an FCC or BCC arrangement. :param atomtype: Type of metal atom. :type atomtype: str :returns: Raises an error if the atom type is not FCC or BCC. :rtype: None .. py:function:: check_file_extension(infile, extension) Checks if the input file has the correct extension. :param infile: Path to the input file. :type infile: str :param extension: Expected file extension. :type extension: str :returns: Raises an error if the file does not have the expected extension. :rtype: None .. py:function:: check_file_extension_rdkit(infile, accepted_extensions) Checks if the input file has a RDKit-supported extension. :param infile: Path to the input file. :type infile: str :param accepted_extensions: List of accepted file extensions for RDKit. :type accepted_extensions: list :returns: Raises an error if the file extension is not supported. :rtype: None .. py:function:: check_accepted_parameters(param, accepted_params, label='Parameter') Checks if a parameter is in the list of accepted parameters. :param param: Parameter value to check. :type param: str :param accepted_params: List of accepted parameter values. :type accepted_params: list :param label: Label for the parameter in error messages. :type label: str, optional :returns: Raises an error if the parameter is not in accepted parameters. :rtype: None .. py:function:: check_dir_axis(inp) Validates the direction axis input for translation or rotation. :param inp: An instance containing input parameters. :type inp: input_class :returns: Updated `inp` with validated direction axis settings. :rtype: input_class .. rubric:: Notes - Ensures that the axis is properly formatted (e.g., `+x`, `-y`). - Assigns the corresponding numerical translation factor. .. py:function:: create_results_geom() Creates the `results_geom` directory if it does not already exist. :returns: Ensures that output files can be stored in the correct location. :rtype: None .. py:function:: extract_string_or_list(argv, flag) Extract the argument(s) that follow a CLI flag. Accepts: - CO -> ["CO"] - "CO" -> ["CO"] - CO,OH -> ["CO","OH"] - ["CO","OH"] -> ["CO","OH"] (quoted or unquoted list) - [CO, OH] -> ["CO","OH"] (bare items) Returns a list of strings. .. py:function:: extract_value(argv, flag, value_type) Extract the argument that follows a CLI flag and cast it to a given type. :param argv: Command-line arguments. :type argv: list :param flag: Flag to search for (case-insensitive). :type flag: str :param value_type: Expected Python type (e.g., str, int, float). :type value_type: type :returns: The value converted to the expected type. :raises ValueError: If the flag is present but has no value, or if the value cannot be converted to the expected type. :raises SystemExit: If the flag is not found (via output.error()). .. py:function:: extract_value_or_default(argv, flag, value_type=str, default=None) Extract the argument that follows a CLI flag and cast it to a given type. If the flag is absent or has no following value, return the provided default. If the flag is present but the value is not convertible to the requested type, raise ValueError. :param argv: Command-line arguments. :type argv: list[str] :param flag: Flag to search for (case-insensitive). :type flag: str :param value_type: One of {str, int, float}. :type value_type: type :param default: Default value if the flag is missing or has no argument. If not None, its type must match `value_type`. :type default: Any :returns: The value converted to `value_type`, or `default` when appropriate. :rtype: Any :raises TypeError: If `value_type` is unsupported, or `default`'s type doesn't match `value_type`. :raises ValueError: If the flag is present but the following token can't be converted to `value_type`. .. py:function:: check_equal_extensions(infile1, infile2) Checks if two input files have the same extension. If yes, raises an error. :param infile1: Path to the first input file. :type infile1: str :param infile2: Path to the second input file. :type infile2: str