schrodinger.application.matsci.enumeration module

A class and function that help enumerate possibilities - could be enumerating over items of a list or enumerating the element at various atom positions in a structure, for instance.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.enumeration.Alchemist(master, targets, new_items, child=None)

Bases: object

Class that mutates the element of an atom in a structure

__init__(master, targets, new_items, child=None)

Create an Alchemist object. Alchemists modify an object by changing a target item to new item. For instance, an Alchemist: - Might transmute the element of a particular atom - Might change the item of a list to a new value For enumeration, a series of Alchemists will work together to perform all necessary mutations, each alchemist passing their mutated structures on to another (child) alchemist. The general workflow looks like:

receive mutated_object from parent alchemist
for target in targets:
    for new_item in new_items:
        make a copy_of_mutated_object
        change item at target in copy_of_mutated_object to new_item
        pass copy_of_mutated_object to child alchemist
Parameters

  • master (object) – The master for this object. Can be a panel or other object that has methods that get called by Alchemist methods. By default, the Alchemist class calls master.transmutationCompleted with each fully transmuted object.

  • targets (list) – list of possible positions for this Alchemist to mutate

  • new_items (list) – list of items to change each target to.

  • child (Alchemist) – The Alchemist to call each time this Alchemist transmutes an atom. If child is None, than this Alchemist is the last in the line.

performTransmutation(data, index, item)

Perform a transmutation on a copy of data at index. It is very important that this happen on a copy of data, not data itself.

Parameters

  • data – The object to transmute a copy of

  • index – An index that tells what part of data to transmute

  • item – The object to mutate data[index] to

Return type

type(data)

Returns

A COPY of data, transmuted at index

allTransmutationsCompleted(mydata, myused)

Perform whatever action is required when all transmutations have been performed on the mydata object

Parameters

  • mydata – The object that is fully transmuted

  • myused (list) – List of indexes that have been transmuted in mydata

runTransmutations(data, used=None)

Begin transmutations.

This Alchemist will determine what targets to transmute based on its set of original targets minus those targets that have been used by previous Alchemists. Each time this Alchemist transmutes an item, it calls its child Alchemist to do its mutations (which calls its child Alchemist each time it transmutes an item, and so on). Thus is the iterative process of transmutating all possible combinations achieved.

If this Alchemist does not have any children, than it is the last in the Alchemist line and it should call allTransmutationsCompleted when it is done with a transmutation.

Parameters

  • data (object) – The object to be transmuted

  • used (list of int) – The indexes in data of the transmutations performed by parent Alchemists. The last item in this list is used to ensure that this Alchemist does not mutate any target already covered by parent Alchemists.

class schrodinger.application.matsci.enumeration.StructureAlchemist(master, targets, new_items, path, child=None)

Bases: schrodinger.application.matsci.enumeration.Alchemist

An abstract base Alchemist class for Alchemists that transmute Structures - subclasses will probably need to re-implement the performTransmutation and allTransmutationsCompleted methods.

__init__(master, targets, new_items, path, child=None)

Create an Alchemist object

Parameters

path (str) – The path to a temporary file to write structures to

See parent class for additional documentation

runTransmutations(data, used=None)

Begin transmuating atoms.

This Alchemist will determine what target atoms to transmute based on its set of original targets minus those targets that have been used by previous Alchemists. Each time this Alchemist transmute an atom, it calls its child Alchemist to do its mutations (which calls its child Alchemist each time it transmutes an atom). Thus is the iterative process of transmutating all possible combinations achieved.

If this Alchemist does not have any children, than it is the last in the Alchemist line and it should add a new project entry each time it transmutes an atom.

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms by parent Alchemists. The last atom in this list is used to ensure that this Alchemist does not mutate any target already covered by parent Alchemists.

allTransmutationsCompleted(mydata, myused)

Perform whatever action is required when all transmutations have been performed on the mydata object

Parameters

  • mydata – The object that is fully transmuted

  • myused (list) – List of indexes that have been transmuted in mydata

performTransmutation(data, index, item)

Perform a transmutation on a copy of data at index. It is very important that this happen on a copy of data, not data itself.

Parameters

  • data – The object to transmute a copy of

  • index – An index that tells what part of data to transmute

  • item – The object to mutate data[index] to

Return type

type(data)

Returns

A COPY of data, transmuted at index

class schrodinger.application.matsci.enumeration.ElementAlchemist(master, targets, new_items, path, child=None)

Bases: schrodinger.application.matsci.enumeration.StructureAlchemist

An alchemist class that transmutes elements in a Structure

Note

The new_items argument to the constructor for this class should have the following format:

type new_items: list of tuple
param new_items: Each item of the list is an (element, color) tuple,
where element is the atomic symbol of the element to mutate to, and
color is the new color for that atom in a form accepted by the
_StructAtom.color property
performTransmutation(struct, index, item)

Perform a transmutation on a copy of struct at index. It is very important that this happen on a copy of struct, not struct itself.

Parameters

  • struct (schrodinger.structure.Structure) – The structure to transmute a copy of

  • index (int) – An index that tells what atom to transmute

  • item (tuple) – An (element, color) tuple, where element is the atomic symbol of the element to mutate to, and color is the new color for that atom in a form accepted by the _StructAtom.color property

Return type

schrodinger.structure.Structure

Returns

A COPY of struct with atom index transmuted

fixHydrogens(struct, used)

Correct the number of hydrogens bonded to each transmuted atom

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms

allTransmutationsCompleted(struct, used)

All transmutations have been performed on struct, write it out to a file if we are keeping this result

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms

__init__(master, targets, new_items, path, child=None)

Create an Alchemist object

Parameters

path (str) – The path to a temporary file to write structures to

See parent class for additional documentation

runTransmutations(data, used=None)

Begin transmuating atoms.

This Alchemist will determine what target atoms to transmute based on its set of original targets minus those targets that have been used by previous Alchemists. Each time this Alchemist transmute an atom, it calls its child Alchemist to do its mutations (which calls its child Alchemist each time it transmutes an atom). Thus is the iterative process of transmutating all possible combinations achieved.

If this Alchemist does not have any children, than it is the last in the Alchemist line and it should add a new project entry each time it transmutes an atom.

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms by parent Alchemists. The last atom in this list is used to ensure that this Alchemist does not mutate any target already covered by parent Alchemists.

class schrodinger.application.matsci.enumeration.VacancyAlchemist(master, targets, new_items, path, child=None)

Bases: schrodinger.application.matsci.enumeration.StructureAlchemist

An alchemist class that deletes atoms in a Structure and the hydrogens they are bound to

Note

The new_items argument to the constructor for this class should have the following format:

type new_items: list
param new_items: Should be [None]
DELETE_PROPERTY = 'b_matsci_impending_vacancy'
performTransmutation(struct, index, item)

Mark atom index for deletion, and also mark all the hydrogen atoms it is attached to. This will happen on a copy of the input structure.

Normally this method in parent classes actually changes the structure, but in this case, deleting atoms would mess up all the atom numbering for Alchemists down the line, so we only mark those atoms for later deletion.

Parameters

  • struct (schrodinger.structure.Structure) – The structure to transmute a copy of

  • index (int) – An index that tells what atom to delete

  • item (None) – None - unused

Return type

schrodinger.structure.Structure

Returns

A COPY of struct with atom index and attached hydrogens marked for deletion.

deleteAtoms(struct)

Delete all atoms marked for deletion

Parameters

struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

allTransmutationsCompleted(struct, used)

All transmutations have been performed on struct, write it out to a file if we are keeping this result

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms

__init__(master, targets, new_items, path, child=None)

Create an Alchemist object

Parameters

path (str) – The path to a temporary file to write structures to

See parent class for additional documentation

runTransmutations(data, used=None)

Begin transmuating atoms.

This Alchemist will determine what target atoms to transmute based on its set of original targets minus those targets that have been used by previous Alchemists. Each time this Alchemist transmute an atom, it calls its child Alchemist to do its mutations (which calls its child Alchemist each time it transmutes an atom). Thus is the iterative process of transmutating all possible combinations achieved.

If this Alchemist does not have any children, than it is the last in the Alchemist line and it should add a new project entry each time it transmutes an atom.

Parameters

  • struct (schrodinger.structure.Structure) – The structure object with the transmuted atoms

  • used (list of int) – The atom indexes of the transmuted atoms by parent Alchemists. The last atom in this list is used to ensure that this Alchemist does not mutate any target already covered by parent Alchemists.

schrodinger.application.matsci.enumeration.perform_transmutations(minimum_transmutations, maximum_transmutations, transmutation_sites, alchemist_creator, data, **kwargs)

Enumerate all possible transmutations on an object

Parameters

  • minimum_transmutations (int) – The minimum number of transmutations to perform on each object

  • maximum_transmutations (int) – The maximum number of transmutations to perform on each object

  • transmutation_sites (list) – The indexes of the object that are available for transmutation

  • alchemist_creator (callable) – A method that creates an Alchemist object. The method should take the following positional arguments: 1) A list of sites to transmute, 2) A child alchmist (or None if no child). In addition, any additional keyword arguments passed to the perform_transmutations function are passed on to the alchemist_creator function as keyword arguments.

  • data – The object to perform transmutations on

Note

Any additional keyword arguments are passed to the alchemist_creator function

schrodinger.application.matsci.enumeration.main(*args)