Adding a Selection Scheme

SelectionScheme is an abstract base class (ABC) used to prescribe concrete selection scheme classes. Please note, if you submit a GitHub Pull Request to include a new selection scheme you will need to have also added appropriate tests in the QMzyme/tests directory. The docstring of the SelectionScheme base class describes how you can create your own subclass:

class QMzyme.SelectionSchemes.SelectionScheme(model, name)

SelectionScheme is the abstract base class used to prescribe concrete selection scheme sub classes. Fork QMzyme to build your own concrete selection scheme class and submit a Pull Request (PR) on github to have your scheme added to QMzyme! You will need to create comprehensive tests before the PR is accepted. See the documentation on contributing for more information.

Below is a template that you can use to implement your own selection scheme class:

class InformativeName(SelectionScheme):

This is an example docstring.

Include a detailed description of how the scheme works in the class level doc string. Also include any parameters the __init__() method of your class accepts.

Parameters:

model:

(QMzymeModel) QMzymeModel to provide starting structure that selection will be performed on. When using the main GenerateModel class, the QMzyme model is automatically passed as an argument to the selection scheme. It is recommended you use the Universe (universe attribute) representing the starting structure to perform the selection on.

name:

(str, required) Name of the region generated.

The return should always be a QMzyme region.

Returns:

QMzymeRegion

Note

Include any notes you want users to be aware of.

Assign any key word arguments as attributes to self. Then in your select_atoms() method you can pull any necessary args from self attributes, instead of relying on passing them.

Every concrete scheme __init__() method should include this line at the very end:

super().__init__(model, name)

This will automatically run your select_atoms() method and return the resulting region.

abstractmethod select_atoms()

Write your code to perform the selection.

At the end of your code you should set self.region = {region}.

The product of your selection scheme needs to be a QMzymeRegion in order for it to work with GenerateModel().set_region().

This method is automatically called in the super().__init__(model, name) line of your __init__() method.

method_name()

You can add whatever other methods you want in your class, but you should call those methods as necessary in __init__() otherwise your scheme will be automated in GenerateModel.set_region()

return_region()

This method belongs to the base class and is automatically called in the super().__init__(model, name) line of your __init__() method. All you have to do is make sure you have created a class attribute called region.

abstractmethod reference()

This method needs to be included in your class. All it should do is create an attribute called reference that provides a citable reference of the scheme, to give credit where credit is due. The reference will be automatically printed when the class is instantiated. This is taken care of in the the super().__init__(model, name) line of your __init__() method.

Example:

self.reference = "1. Alegre‐Requena, J. V., Sowndarya S. V., S., Pérez‐Soto, R., Alturaifi, T. M. & Paton, R. S. AQME: Automated quantum mechanical environments for researchers and educators. WIREs Comput Mol Sci 13, e1663 (2023)."

In some cases, there might not be a direct reference (see DistanceCutoff class), but there might be relevant work a user might be interested in. Please only refer to the work of interest in the class doc string, not in the reference method.

If there are no references, please only include the line:

self.reference = None