2.2. Generators

The Generator classes are not meant to be directly accessed by the user. Instead, they are used as components of the UniqueConformer classes.

There are two main generator classes, RDKitGenerator and CRESTGenerator, which have roughly the same interface, but different settings. All generators accept an instance of one of the UniqueConformers classes upon initiation. This conformer set is generally expected to be empty, but is not required to be so.

The CREST method combines three separate methods to generate conformers: 1. CREST metadynamics 2. High temperature MD 3. A genetic combinatorial method that extends an existing conformer set. Each of these methods can be used separately, via their additional expert generator classes.

2.2.1. RDKitGenerator

This generator fills the conformer set of a molecule, using RDKit to call the ETKDG conformer generation approach, followed by geometry optimization with a specified AMS engine.

class RDKitGenerator(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Machine that generates a set of unique conformers using RDKit

DOI: 10.1021/acs.jcim.5b00654

A simple example of (parallel) use:

>>> from scm.plams import Molecule
>>> from scm.plams import init, finish
>>> from scm.conformers import UniqueConformersAMS, RDKitGenerator

>>> # Set up the molecular data
>>> mol = Molecule('mol.xyz')
>>> conformers = UniqueConformersAMS()
>>> conformers.prepare_state(mol)

>>> # Set up PLAMS settings
>>> init()

>>> # Create the generator and run
>>> generator = RDKitGenerator(conformers, nproc=1, maxjobs=12)
>>> generator.generate()

>>> finish()

>>> # Write the results to file
>>> print(conformers)
>>> conformers.write()

The default AMS engine used is the GFN1-xTB engine. A different engine can be provided upon initiation.

>>> engine_settings = Settings()
>>> engine_settings.ForceField.Type = 'UFF'
>>> generator = RDKitGenerator(conformers, engine_settings=engine, nproc=1, maxjobs=12)
__init__(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Initiates an instance of the RDKitGenerator class

  • conformers – A UniqueConformers object

  • engine_settings – PLAMS Settings object:
    >>> engine_settings = Settings()
>>> engine_settings.DFTB.Model = 'GFN1-xTB'

  • nproc – Number of processors used for each single call to AMS

  • energy_threshold – Maximum accepted energy difference from lowest energy conformer

  • maxjobs – Maximum number of parallel AMS processes

set_number_initial_conformers(ngeoms=None, min_confs=10, max_confs=5000)

Set the number of conformers created by RDKit, before geometry optimization and filtering

  • ngeoms – The number of initial conformers created by RDKit. If not provided, this number will be generated based on the number of rotational bonds \(n\): \(3^n*self.factor\)
  • min_confs – A minimum to the number of initial conformers, in case ngeoms is not provided
  • max_geoms – A maximum to the number of initial conformers, in case ngeoms is not provided
generate()

Generate the conformer set

_estimate_runtime()

Estimate the runtime based on the already stored timings for GO

_set_gotimes(factor=1)

Run some geometry optimizations to make a reasonable estimate of the time and iteration

are_geometries_local_minima(molecules)

Perform a PES point characterization for the molecules and return a list of booleans indicating whether the geometry is a local minimum or not

estimate_runtime(factor=1)

Provides a reasonable estimate of the runtime, based on several geometry optimizations

  • factor – Determines the number of GO optimizations that are performerd. The higher the value, the more accurate the estimate.
    The number of GOs will be 2*factor*maxjobs It converges, but generally to a value that is still a bit too high
optimize_and_filter(geometries, conformers=None, level=None, name='go')

Run the geometry optimizations for the provided geometries and add to conformer set

  • geometries – List of “math:n numpy arrays containing coordinates (n*(nats,3))
  • level – The level of the geometry optimizations, as defined in the ConformerOptimizer class
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
optimize_conformers(convergence_level, name='go')

(Re)-Optimize the conformers currently in the set

  • convergence_level – One of the convergence options (‘tight’, ‘vtight’, ‘loose’, etc’)
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
set_jobrunner(jobrunner)

Pass a PLAMS JobRunner object to organize parallelization

  • jobrunner – Instance of the PLAMS Jobrunner class
set_optimizer(optimizer)

Change the optimizer of the generator object

  • optimizer – ConformerOptimizer object
set_preoptimizer(engine_settings)

Set a lower level optimizer, to be used for preoptimization

A selection will be made based on the energies, but the preoptimized geometries will not be used, so as not to rely on the low-level engine too much

set_printing_level(verbose)

Set the printing level (verbose is True of False)

static time_time_timestring(time)

Convert time in seconds to a time string

write_geometries(geometries, name='unoptimized', filetype='xyz')

Write a set of geometries at any point

2.2.2. CRESTGenerator

This generator fills the conformer set of a molecule using the CREST method.

class CRESTGenerator(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Machine that generates a set of conformers using the CREST workflow

A simple example of (parallel) use:

>>> from scm.plams import Molecule
>>> from scm.plams import init, finish
>>> from scm.conformers import UniqueConformersCrest, CRESTGenerator

>>> # Set up the molecular data
>>> mol = Molecule('mol.xyz')
>>> conformers = UniqueConformersCrest()
>>> conformers.prepare_state(mol)

>>> # Set up PLAMS settings
>>> init()

>>> # Create the generator and run
>>> generator = CRESTGenerator(conformers, nproc=1, maxjobs=12)
>>> generator.generate()

>>> finish()

>>> # Write the results to file
>>> print(conformers)
>>> conformers.write()

The default AMS engine used is the GFN1-xTB engine. A different engine can be provided upon initiation.

>>> engine_settings = Settings()
>>> engine_settings.ForceField.Type = 'UFF'
>>> generator = CRESTGenerator(conformers, engine_settings=engine, nproc=1, maxjobs=12)
__init__(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Initiates an instance of the Optimizer class

  • conformers – A UniqueConformers object

  • engine_settings – PLAMS Settings object:
    >>> engine_settings = Settings()
>>> engine_settings.DFTB.Model = 'GFN1-xTB'

  • nproc – Number of processors used for each single call to AMS

  • energy_threshold – Maximum accepted energy difference from lowest energy conformer

  • maxjobs – Maximum number of parallel AMS processes

set_optimizer(optimizer)

Change the optimizer of the generator object

  • optimizer – ConformerOptimizer object
set_printing_level(verbose)

Set the printing level (verbose is True of False)

set_shake(shake=True)

Determine if SHAKE will be used

generate()

Generate the conformer set

_estimate_runtime()

Estimate the runtime based on the already stored timings for GO

_set_gotimes(factor=1)

Run some geometry optimizations to make a reasonable estimate of the time and iteration

_generate_geometries(ngeoms)

Call RDKit to generate a set of conformers

are_geometries_local_minima(molecules)

Perform a PES point characterization for the molecules and return a list of booleans indicating whether the geometry is a local minimum or not

estimate_runtime(factor=1)

Provides a reasonable estimate of the runtime, based on several geometry optimizations

  • factor – Determines the number of GO optimizations that are performerd. The higher the value, the more accurate the estimate.
    The number of GOs will be 2*factor*maxjobs It converges, but generally to a value that is still a bit too high
optimize_and_filter(geometries, conformers=None, level=None, name='go')

Run the geometry optimizations for the provided geometries and add to conformer set

  • geometries – List of “math:n numpy arrays containing coordinates (n*(nats,3))
  • level – The level of the geometry optimizations, as defined in the ConformerOptimizer class
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
optimize_conformers(convergence_level, name='go')

(Re)-Optimize the conformers currently in the set

  • convergence_level – One of the convergence options (‘tight’, ‘vtight’, ‘loose’, etc’)
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
set_jobrunner(jobrunner)

Pass a PLAMS JobRunner object to organize parallelization

  • jobrunner – Instance of the PLAMS Jobrunner class
set_preoptimizer(engine_settings)

Set a lower level optimizer, to be used for preoptimization

A selection will be made based on the energies, but the preoptimized geometries will not be used, so as not to rely on the low-level engine too much

static time_time_timestring(time)

Convert time in seconds to a time string

2.2.3. MetadynamicsGenerator

This generator fills the conformer set of a molecule using only CREST metadynanics, followed by geometry optimization of the stored shapshots (step 1 of the CREST approach).

class MetadynamicsGenerator(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Machine that produces a set of conformers from CREST metadynamics simulations

A simple example of (parallel) use:

>>> from scm.plams import Molecule
>>> from scm.plams import init, finish
>>> from scm.conformers import UniqueConformersCrest, MetadynamicsGenerator

>>> # Set up the molecular data
>>> mol = Molecule('mol.xyz')
>>> conformers = UniqueConformersCrest()
>>> conformers.prepare_state(mol)

>>> # Set up PLAMS settings
>>> init()

>>> # Create the generator and run
>>> generator = MetadynamicsGenerator(conformers, nproc=1, maxjobs=12)
>>> generator.generate()

>>> finish()

>>> # Write the results to file
>>> print(conformers)
>>> conformers.write()

The default AMS engine used is the GFN1-xTB engine. A different engine can be provided upon initiation.

>>> engine_settings = Settings()
>>> engine_settings.ForceField.Type = 'UFF'
>>> generator = MetadynamicsGenerator(conformers, engine_settings=engine, nproc=1, maxjobs=12)
__init__(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Initiates an instance of the MetadynamicsGenerator class

  • conformers – A UniqueConformers object

  • engine_settings – PLAMS Settings object:
    >>> engine_settings = Settings()
>>> engine_settings.DFTB.Model = 'GFN1-xTB'

  • nproc – Number of processors used for each single call to AMS

  • energy_threshold – Maximum accepted energy difference from lowest energy conformer

  • maxjobs – Maximum number of parallel AMS processes

set_shake(shake=True)

Determine if SHAKE will be used

generate()

Generate the conformer set

optimize_and_filter(geometries)

Run dual-level geometry optimizations for the provided geometries and add to conformer set

  • geometries – List of “math:n numpy arrays containing coordinates (n*(nats,3))
_estimate_runtime()

Estimate the runtime based on the already stored timings for GO

_generate_geometries(ngeoms)

Call RDKit to generate a set of conformers

_set_gotimes(factor=1)

Run some geometry optimizations to make a reasonable estimate of the time and iteration

are_geometries_local_minima(molecules)

Perform a PES point characterization for the molecules and return a list of booleans indicating whether the geometry is a local minimum or not

estimate_runtime(factor=1)

Provides a reasonable estimate of the runtime, based on several geometry optimizations

  • factor – Determines the number of GO optimizations that are performerd. The higher the value, the more accurate the estimate.
    The number of GOs will be 2*factor*maxjobs It converges, but generally to a value that is still a bit too high
optimize_conformers(convergence_level, name='go')

(Re)-Optimize the conformers currently in the set

  • convergence_level – One of the convergence options (‘tight’, ‘vtight’, ‘loose’, etc’)
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
set_jobrunner(jobrunner)

Pass a PLAMS JobRunner object to organize parallelization

  • jobrunner – Instance of the PLAMS Jobrunner class
set_optimizer(optimizer)

Change the optimizer of the generator object

  • optimizer – ConformerOptimizer object
set_preoptimizer(engine_settings)

Set a lower level optimizer, to be used for preoptimization

A selection will be made based on the energies, but the preoptimized geometries will not be used, so as not to rely on the low-level engine too much

set_printing_level(verbose)

Set the printing level (verbose is True of False)

static time_time_timestring(time)

Convert time in seconds to a time string

2.2.4. MDGenerator

This generator fills the conformer set of a molecule using only regular molecular dynamics, followed by geometry optimization of the stored shapshots (step 2 of the CREST approach).

class MDGenerator(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Machine that produces a set of conformers from molecular dynamics simulations (Step 2 of CREST approach)

A simple example of (parallel) use:

>>> from scm.plams import Molecule
>>> from scm.plams import init, finish
>>> from scm.conformers import UniqueConformersCrest, MDGenerator

>>> # Set up the molecular data
>>> mol = Molecule('mol.xyz')
>>> conformers = UniqueConformersCrest()
>>> conformers.prepare_state(mol)

>>> # Set up PLAMS settings
>>> init()

>>> # Create the generator and run
>>> generator = MDGenerator(conformers, nproc=1, maxjobs=12)
>>> generator.generate()

>>> finish()

>>> # Write the results to file
>>> print(conformers)
>>> conformers.write()

The default AMS engine used is the GFN1-xTB engine. A different engine can be provided upon initiation.

>>> engine_settings = Settings()
>>> engine_settings.ForceField.Type = 'UFF'
>>> generator = MDGenerator(conformers, engine_settings=engine, nproc=1, maxjobs=12)
__init__(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Initiates an instance of the MDGenerator class

  • engine_settings – PLAMS Settings object:
    >>> engine_settings = Settings()
>>> engine_settings.DFTB.Model = 'GFN1-xTB'

  • nproc – Number of processors used for each single call to AMS

  • energy_threshold – Maximum accepted energy difference from lowest energy conformer

  • maxjobs – Maximum number of parallel AMS processes

set_jobrunner(jobrunner)

Pass a PLAMS JobRunner object to organize parallelization

  • jobrunner – Instance of the PLAMS Jobrunner class
set_shake(shake=True)

Determine if SHAKE will be used

set_number_of_identical_mdruns()

Sets the number of MD runs of each temperature (default=1)

set_number_of_starting_geometries()

Set the number of conformers used to start the MD runs from (default=4)

generate()

Generate the conformer set

_estimate_runtime()

Estimate the runtime based on the already stored timings for GO

_generate_geometries(ngeoms)

Call RDKit to generate a set of conformers

_set_gotimes(factor=1)

Run some geometry optimizations to make a reasonable estimate of the time and iteration

are_geometries_local_minima(molecules)

Perform a PES point characterization for the molecules and return a list of booleans indicating whether the geometry is a local minimum or not

estimate_runtime(factor=1)

Provides a reasonable estimate of the runtime, based on several geometry optimizations

  • factor – Determines the number of GO optimizations that are performerd. The higher the value, the more accurate the estimate.
    The number of GOs will be 2*factor*maxjobs It converges, but generally to a value that is still a bit too high
optimize_and_filter(geometries, conformers=None, level=None, name='go')

Run the geometry optimizations for the provided geometries and add to conformer set

  • geometries – List of “math:n numpy arrays containing coordinates (n*(nats,3))
  • level – The level of the geometry optimizations, as defined in the ConformerOptimizer class
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
optimize_conformers(convergence_level, name='go')

(Re)-Optimize the conformers currently in the set

  • convergence_level – One of the convergence options (‘tight’, ‘vtight’, ‘loose’, etc’)
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
set_optimizer(optimizer)

Change the optimizer of the generator object

  • optimizer – ConformerOptimizer object
set_preoptimizer(engine_settings)

Set a lower level optimizer, to be used for preoptimization

A selection will be made based on the energies, but the preoptimized geometries will not be used, so as not to rely on the low-level engine too much

set_printing_level(verbose)

Set the printing level (verbose is True of False)

static time_time_timestring(time)

Convert time in seconds to a time string

2.2.5. GCGenerator

This generator extends a conformer set of a molecule using only the CREST genetic combinatorial method (GC), followed by geometry optimization of the stored shapshots (step 3 of the CREST approach).

class GCGenerator(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Machine that extends a set of conformers using genetic structure crossing

DOI: 10.1002/anie.201708266 (Supporting Information)

A simple example of (parallel) use:

>>> from scm.plams import Molecule
>>> from scm.plams import init, finish
>>> from scm.conformers import UniqueConformersCrest, GCGenerator

>>> # Set up the molecular data
>>> mol = Molecule('mol.xyz')
>>> conformers = UniqueConformersCrest()
>>> conformers.prepare_state(mol)

>>> # Set up PLAMS settings
>>> init()

>>> # Create the generator and run
>>> generator = GCGenerator(conformers, nproc=1, maxjobs=12)
>>> generator.generate()

>>> finish()

>>> # Write the results to file
>>> print(conformers)
>>> conformers.write()

The default AMS engine used is the GFN1-xTB engine. A different engine can be provided upon initiation.

>>> engine_settings = Settings()
>>> engine_settings.ForceField.Type = 'UFF'
>>> generator = GCGenerator(conformers, engine_settings=engine, nproc=1, maxjobs=12)
__init__(conformers, engine_settings=None, nproc=1, energy_threshold=6.0, maxjobs=1)

Initiates an instance of the GCGenerator class

  • conformers – A UniqueConformers object

  • engine_settings – PLAMS Settings object:
    >>> engine_settings = Settings()
>>> engine_settings.DFTB.Model = 'GFN1-xTB'

  • nproc – Number of processors used for each single call to AMS

  • energy_threshold – Maximum accepted energy difference from lowest energy conformer

  • maxjobs – Maximum number of parallel AMS processes

generate()

Generate a conformer set, based on the CREST method

set_maxgeoms(mtd_generator=None)

Set the maximum number of geometries that can be produced, based on the molecules flexibility

_get_rmsds(geometries, row_indices=None, col_indices=None, no_first_column=False)

Get the pairwise RMSD values, in order to prune

  • rmsds – The RMSD values for each geometry to the first reference geometry (can be used to save time)
_get_rmsds_double_loop(geometries, row_indices=None, col_indices=None, no_first_column=False)

Get the pairwise RMSD values, in order to prune, using double loop over rowns and columns

  • rmsds – The RMSD values for each geometry to the first reference geometry (can be used to save time)

Note: Alternative to _get_rmsds(). Currently not used. Load-balancing is less good than _get_rmsds()

_get_rmsds_parallel(geometries, no_first_column=False)

Run _prune_geometries in a parallel fashion

_estimate_runtime()

Estimate the runtime based on the already stored timings for GO

_generate_geometries(ngeoms)

Call RDKit to generate a set of conformers

_set_gotimes(factor=1)

Run some geometry optimizations to make a reasonable estimate of the time and iteration

are_geometries_local_minima(molecules)

Perform a PES point characterization for the molecules and return a list of booleans indicating whether the geometry is a local minimum or not

estimate_runtime(factor=1)

Provides a reasonable estimate of the runtime, based on several geometry optimizations

  • factor – Determines the number of GO optimizations that are performerd. The higher the value, the more accurate the estimate.
    The number of GOs will be 2*factor*maxjobs It converges, but generally to a value that is still a bit too high
optimize_and_filter(geometries, conformers=None, level=None, name='go')

Run the geometry optimizations for the provided geometries and add to conformer set

  • geometries – List of “math:n numpy arrays containing coordinates (n*(nats,3))
  • level – The level of the geometry optimizations, as defined in the ConformerOptimizer class
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
optimize_conformers(convergence_level, name='go')

(Re)-Optimize the conformers currently in the set

  • convergence_level – One of the convergence options (‘tight’, ‘vtight’, ‘loose’, etc’)
  • name – The base name of the PLAMS directories in which the geometry optimizations are performed
set_jobrunner(jobrunner)

Pass a PLAMS JobRunner object to organize parallelization

  • jobrunner – Instance of the PLAMS Jobrunner class
set_optimizer(optimizer)

Change the optimizer of the generator object

  • optimizer – ConformerOptimizer object
set_preoptimizer(engine_settings)

Set a lower level optimizer, to be used for preoptimization

A selection will be made based on the energies, but the preoptimized geometries will not be used, so as not to rely on the low-level engine too much

set_printing_level(verbose)

Set the printing level (verbose is True of False)

static time_time_timestring(time)

Convert time in seconds to a time string