atomate.qchem.firetasks package — atomate 0.9.2 documentation

# atomate.qchem.firetasks package

## Subpackages

- atomate.qchem.firetasks.tests package
  - Submodules
  - atomate.qchem.firetasks.tests.test_fragmenter module
  - atomate.qchem.firetasks.tests.test_geo_transformations module
  - atomate.qchem.firetasks.tests.test_run_calc module
  - atomate.qchem.firetasks.tests.test_write_inputs module
  - Module contents

## Submodules

## atomate.qchem.firetasks.fragmenter module

class `atomate.qchem.firetasks.fragmenter.` `FragmentMolecule`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Simulate all unique fragments of a molecule relevant for realistic fragmentation of the molecule itself or of its subfragments.

  Realistic fragmentation of a neutral molecule will almost always be one of the following:

    molecule(charge=0) -> fragment1(charge=0) + fragment2(charge=0) molecule(charge=0) -> fragment1(charge=1) + fragment2(charge=-1) molecule(charge=0) -> fragment1(charge=-1) + fragment2(charge=1)

  Thus, we want to simulate charges -1, 0, and 1 of each fragment.

  Realistic fragmentation of a positively charged molecule (using charge=1 as an example here) will almost always be one of the following:

  > molecule(charge=1) -> fragment1(charge=0) + fragment2(charge=1) molecule(charge=1) -> fragment1(charge=1) + fragment2(charge=0)

  Thus, we want to simulate charges 0 and 1 of each fragment, given charge=1. Generalizing to any positively charged principle with charge P, we simulate P and P-1.

  Realistic fragmentation of a negatively charged molecule (using charge=-1 as an example here) will almost always be one of the following:

  > molecule(charge=-1) -> fragment1(charge=0) + fragment2(charge=-1) molecule(charge=-1) -> fragment1(charge=-1) + fragment2(charge=0)

  Thus, we want to simulate charges -1 and 0 of each fragment, given charge=-1. Generalizing to any positively charged principle with charge P, we simulate P and P+1.

  If additional charges are desired by the user, they can be specified with the additional_charges input parameter as described below.

  Optional params:

    molecule (Molecule): The molecule to fragment edges (list): List of index pairs that define graph edges, aka molecule bonds. If not

    > set, edges will be determined with OpenBabel.

    depth (int): The number of levels of iterative fragmentation to perform, where each

      level will include fragments obtained by breaking one bond of a fragment one level up. Defaults to 1. However, if set to 0, instead all possible fragments are generated using an alternative, non-iterative scheme.

    open_rings (bool): Whether or not to open any rings encountered during fragmentation.

      Defaults to True. If true, any bond that fails to yield disconnected graphs when broken is instead removed and the entire structure is optimized with OpenBabel in order to obtain a good initial guess for an opened geometry that can then be put back into QChem to be optimized without the ring just reforming.

    opt_steps (int): Number of optimization steps when opening rings. Defaults to 10000. additional_charges (list): List of additional charges besides the defaults described

    > above. For example, if a principle molecule with a +2 charge is provided, by default all fragments will be calculated with +1 and +2 charges as explained above. If the user includes additional_charges=[0] then all fragments will be calculated with 0, +1, and +2 charges. Additional charge values of 1 or 2 would not cause any new charges to be calculated as they are already done. Defaults to [].

    do_triplets (bool): Whether to simulate triplets as well as singlets for molecules with

      an even number of electrons. Defaults to True.

    qchem_input_params (dict): Specify kwargs for instantiating the input set parameters.

      Basic uses would be to modify the default inputs of the set, such as dft_rung, basis_set, pcm_dielectric, scf_algorithm, or max_scf_cycles. See pymatgen/io/qchem/sets.py for default values of all input parameters. For instance, if a user wanted to use a more advanced DFT functional, include a pcm with a dielectric of 30, and use a larger basis, the user would set qchem_input_params = {“dft_rung”: 5, “pcm_dielectric”: 30, “basis_set”: “6-311++g**”}. However, more advanced customization of the input is also possible through the overwrite_inputs key which allows the user to directly modify the rem, pcm, smd, and solvent dictionaries that QChemDictSet passes to inputs.py to print an actual input file. For instance, if a user wanted to set the sym_ignore flag in the rem section of the input file to true, then they would set qchem_input_params = {“overwrite_inputs”: “rem”: {“sym_ignore”: “true”}}. Of course, overwrite_inputs could be used in conjuction with more typical modifications, as seen in the test_double_FF_opt workflow test.

    db_file (str): Path to file containing the database credentials. Supports env_chk. check_db (bool): Whether or not to check if fragments are present in the database.

    > Defaults to bool(db_file), aka true if a db_file is present and false if db_file is None.

  `optional_params` = ['molecule', 'edges', 'depth', 'open_rings', 'opt_steps', 'additional_charges', 'do_triplets', 'qchem_input_params', 'db_file', 'check_db']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

## atomate.qchem.firetasks.geo_transformations module

class `atomate.qchem.firetasks.geo_transformations.` `RotateTorsion`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Writes QChem Input files from input sets. A dictionary is passed to WriteInputFromIOSet where parameters are given as keys in the dictionary.

  required_params:

    atom_indexes (list): This should be a list of the pymatgen molecule indexes of the four atoms in torsion angle to be rotated angle (float): This is the desired torsion angle in degrees (the value should be between -180 and 180)

  optional_params:

    molecule (Molecule): Specify a pymatgen molecule to be rotated. A molecule is optional because molecules can be inherited from previous fireworks

  `optional_params` = ['molecule']
  `required_params` = ['atom_indexes', 'angle']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

## atomate.qchem.firetasks.parse_outputs module

class `atomate.qchem.firetasks.parse_outputs.` `QChemToDb`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Enter a QChem run into the database. Uses current directory unless you specify calc_dir or calc_loc.

  Optional params:
    calc_dir (str): path to dir (on current filesystem) that contains QChem

      input and output files. Default: use current working directory.

    calc_loc (str OR bool): if True will set most recent calc_loc. If str

      search for the most recent calc_loc with the matching name

    input_file (str): name of the QChem input file output_file (str): name of the QChem output file additional_fields (dict): dict of additional fields to add db_file (str): path to file containing the database credentials.

    > Supports env_chk. Default: write data to JSON file.

    fw_spec_field (str): if set, will update the task doc with the contents

      of this key in the fw_spec.

    multirun (bool): Whether the job to parse includes multiple

      calculations in one input / output pair.

  `optional_params` = ['calc_dir', 'calc_loc', 'input_file', 'output_file', 'additional_fields', 'db_file', 'fw_spec_field', 'multirun']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

## atomate.qchem.firetasks.run_calc module

class `atomate.qchem.firetasks.run_calc.` `RunNoQChem`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Do NOT run QChem. Do nothing.

  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

class `atomate.qchem.firetasks.run_calc.` `RunQChemCustodian`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Run QChem using custodian “on rails”, i.e. in a simple way that supports most common options.

  Required params:
    qchem_cmd (str): The name of the full executable for running QChem. Note that this is

      explicitly different from qchem_cmd in RunQChemDirect because it does not include any flags and should only be the call to the executable. Supports env_chk.

  Optional params:
    multimode (str): Parallelization scheme, either openmp or mpi. Defaults to openmp.

      Supports env_chk.

    input_file (str): Name of the QChem input file. Defaults to “mol.qin”. output_file (str): Name of the QChem output file. Defaults to “mol.qout” max_cores (int): Maximum number of cores to parallelize over. Supports env_chk. qclog_file (str): Name of the file to redirect the standard output to. None means

    > not to record the standard output. Defaults to None.

    suffix (str): String to append to the file in postprocess. scratch_dir (str): QCSCRATCH directory. Defaults to “/dev/shm/qcscratch/”.

    > Supports env_chk.

    save_scratch (bool): Whether to save scratch directory contents. Defaults to False. save_name (str): Name of the saved scratch directory. Defaults to “default_save_name”. max_errors (int): Maximum # of errors to fix before giving up (default=5) job_type (str): Choose from “normal” (default) and “opt_with_frequency_flattener” handler_group (str): Group of handlers to use. See handler_groups dict in the code

    > for the groups and complete list of handlers in each group.

    gzip_output (bool): gzip output (default=T)

    * Just for opt_with_frequency_flattener * max_iterations (int): Number of perturbation -> optimization -> frequency iterations

    > to perform. Defaults to 10.

    max_molecule_perturb_scale (float): The maximum scaled perturbation that can be

      applied to the molecule. Defaults to 0.3.

    reversed_direction (bool): Whether to reverse the direction of the vibrational

      frequency vectors. Defaults to False.

  `optional_params` = ['multimode', 'input_file', 'output_file', 'max_cores', 'qclog_file', 'suffix', 'scratch_dir', 'save_scratch', 'save_name', 'max_errors', 'max_iterations', 'max_molecule_perturb_scale', 'reversed_direction', 'job_type', 'handler_group', 'gzipped_output']
  `required_params` = ['qchem_cmd']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

class `atomate.qchem.firetasks.run_calc.` `RunQChemDirect`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Execute a command directly (no custodian).

  Required params:
    qchem_cmd (str): The name of the full command line call to run. This should include any

      flags for parallelization, saving scratch, and input / output files. Does NOT support env_chk.

  Optional params:
    scratch_dir (str): Path to the scratch directory. Defaults to “/dev/shm/qcscratch/”.

      Supports env_chk.

  `optional_params` = ['scratch_dir']
  `required_params` = ['qchem_cmd']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

class `atomate.qchem.firetasks.run_calc.` `RunQChemFake`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  QChem Emulator

  Required params:
    ref_dir (string): Path to reference qchem run directory with input file in the folder

      named “mol.qin” and output file in the folder named “mol.qout”.

  `required_params` = ['ref_dir']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

## atomate.qchem.firetasks.write_inputs module

class `atomate.qchem.firetasks.write_inputs.` `WriteCustomInput`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Writes QChem Input files from custom input sets. This firetask gives the maximum flexibility when trying to define custom input parameters.

  required_params:

    qchem_input_custom (dict): Define custom input parameters to generate a qchem input file. This should be a dictionary of dictionaries (i.e. {{“rem”: {“method”: “b3lyp”, basis”: “6-31*G++”, …} Each QChem section should be a key with its own dictionary as the value. For more details on how the input should be structured look at pymatgen.io.qchem.inputs * *

  optional_params:

    molecule (Molecule): input_file (str): Name of the QChem input file. Defaults to mol.qin write_to_dir (str): Path of the directory where the QChem input file will be written, the default is to write to the current working directory

  `optional_params` = ['molecule', 'opt', 'pcm', 'solvent', 'input_file', 'write_to_dir']
  `required_params` = ['rem']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

class `atomate.qchem.firetasks.write_inputs.` `WriteInput`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Writes QChem input file from QCInput object.

  required_params:

    qc_input (QCInput): QCInput object

  optional_params:

    input_file (str): Name of the QChem input file. Defaults to mol.qin write_to_dir (str): Path of the directory where the QChem input file will be written, the default is to write to the current working directory

  `optional_params` = ['input_file', 'write_to_dir']
  `required_params` = ['qc_input']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

class `atomate.qchem.firetasks.write_inputs.` `WriteInputFromIOSet`(*args, **kwargs)

  Bases: `fireworks.core.firework.FiretaskBase`

  Writes QChem Input files from input sets. A dictionary is passed to WriteInputFromIOSet where parameters are given as keys in the dictionary.

  required_params:

    qc_input_set (QChemDictSet or str): Either a QChemDictSet object or a string name for the QChem input set (e.g., “OptSet”). * Note that if the molecule is to be inherited through fw_spec qc_input_set must be a string name for the QChem input set. *

  optional_params:
    qchem_input_params (dict): When using a string name for QChem input set, use this as a dict

      to specify kwargs for instantiating the input set parameters. This setting is ignored if you provide the full object representation of a QChemDictSet. Basic uses would be to modify the default inputs of the set, such as dft_rung, basis_set, pcm_dielectric, scf_algorithm, or max_scf_cycles. See pymatgen/io/qchem/sets.py for default values of all input parameters. For instance, if a user wanted to use a more advanced DFT functional, include a pcm with a dielectric of 30, and use a larger basis, the user would set qchem_input_params = {“dft_rung”: 5, “pcm_dielectric”: 30, “basis_set”: “6-311++g**”}. However, more advanced customization of the input is also possible through the overwrite_inputs key which allows the user to directly modify the rem, pcm, smd, and solvent dictionaries that QChemDictSet passes to inputs.py to print an actual input file. For instance, if a user wanted to set the sym_ignore flag in the rem section of the input file to true, then they would set qchem_input_params = {“overwrite_inputs”: “rem”: {“sym_ignore”: “true”}}. Of course, overwrite_inputs could be used in conjuction with more typical modifications, as seen in the test_double_FF_opt workflow test.

    molecule (Molecule): input_file (str): Name of the QChem input file. Defaults to mol.qin write_to_dir (str): Path of the directory where the QChem input file will be written, the default is to write to the current working directory

  `optional_params` = ['molecule', 'qchem_input_params', 'input_file', 'write_to_dir']
  `required_params` = ['qchem_input_set']
  `run_task`(fw_spec)

    This method gets called when the Firetask is run. It can take in a Firework spec, perform some task using that data, and then return an output in the form of a FWAction.

    Args:
      fw_spec (dict): A Firework spec. This comes from the master spec.

        In addition, this spec contains a special “_fw_env” key that contains the env settings of the FWorker calling this method. This provides for abstracting out certain commands or settings. For example, “foo” may be named “foo1” in resource 1 and “foo2” in resource 2. The FWorker env can specify { “foo”: “foo1”}, which maps an abstract variable “foo” to the relevant “foo1” or “foo2”. You can then write a task that uses fw_spec[“_fw_env”][“foo”] that will work across all these multiple resources.

    Returns:

      (FWAction)

## Module contents