Source code for stk.molecular.functional_groups.factories.functional_group_factory

"""
Functional Group Factory
========================

.. toctree::
    :maxdepth: 2

    Alcohol Factory <\
stk.molecular.functional_groups.factories.alcohol_factory\
>
    Aldehyde Factory <\
stk.molecular.functional_groups.factories.aldehyde_factory\
>
    Amide Factory <\
stk.molecular.functional_groups.factories.amide_factory\
>
    Boronic Acid Factory <\
stk.molecular.functional_groups.factories.boronic_acid_factory\
>
    Bromo Factory <\
stk.molecular.functional_groups.factories.bromo_factory\
>
    Carboxylic Acid Factory <\
stk.molecular.functional_groups.factories.carboxylic_acid_factory\
>
    Dibromo Factory <\
stk.molecular.functional_groups.factories.dibromo_factory\
>
    Difluoro Factory <\
stk.molecular.functional_groups.factories.difluoro_factory\
>
    Diol Factory <\
stk.molecular.functional_groups.factories.diol_factory\
>
    Fluoro Factory <\
stk.molecular.functional_groups.factories.fluoro_factory\
>
    Iodo Factory <\
stk.molecular.functional_groups.factories.iodo_factory\
>
    Primary Amino Factory <\
stk.molecular.functional_groups.factories.primary_amino_factory\
>
    Ring Amine Factory <\
stk.molecular.functional_groups.factories.ring_amine_factory\
>
    Secondary Amino Factory <\
stk.molecular.functional_groups.factories.secondary_amino_factory\
>
    SMARTS Functional Group Factory <\
stk.molecular.functional_groups.factories.smarts_functional_group_factory\
>
    Terminal Alkene Factory <\
stk.molecular.functional_groups.factories.terminal_alkene_factory\
>
    Terminal Alkyne Factory <\
stk.molecular.functional_groups.factories.terminal_alkyne_factory\
>
    Thioacid Factory <\
stk.molecular.functional_groups.factories.thioacid_factory\
>
    Thiol Factory <\
stk.molecular.functional_groups.factories.thiol_factory\
>

"""


[docs]class FunctionalGroupFactory: """ An abstract base class for functional group factories. The purpose of a functional group factory is to create :class:`.FunctionalGroup` instances. It allows the user to avoid creating :class:`.FunctionalGroup` instances manually. The user will use :meth:`.get_functional_groups` to achieve this. Subclasses of this class are made to customize the automatic creation process. Examples -------- *Using a Single Functional Group From a Factory* You have a building block with two functional groups, but you want to use just one. .. testcode:: using-a-single-functional-group-factory import stk amino_factory = stk.PrimaryAminoFactory() building_block = stk.BuildingBlock('NCCN') amino_group1, *rest = amino_factory.get_functional_groups( molecule=building_block, ) building_block = building_block.with_functional_groups( functional_groups=(amino_group1, ), ) .. testcode:: using-a-single-functional-group-factory :hide: assert all( isinstance(functional_group, stk.PrimaryAmino) for functional_group in building_block.get_functional_groups() ) assert building_block.get_num_functional_groups() == 1 *Using a Subset of Functional Groups From a Factory* You have multiple functional groups, but you want the building block to use a specific subset. .. testcode:: using-a-subset-of-functional-groups-from-a-factory import stk bromo_factory = stk.BromoFactory() building_block = stk.BuildingBlock('BrCC(Br)CC(Br)CC(Br)CCBr') bromo_groups = tuple(bromo_factory.get_functional_groups( molecule=building_block, )) building_block = building_block.with_functional_groups( functional_groups=( bromo_groups[0], bromo_groups[3], bromo_groups[4], ), ) .. testcode:: using-a-subset-of-functional-groups-from-a-factory :hide: assert all( isinstance(functional_group, stk.Bromo) for functional_group in building_block.get_functional_groups() ) assert building_block.get_num_functional_groups() == 3 More usage examples can be found in the docstrings of the various subclasses. *Subclass Implementation* The source of the subclasses, listed in :mod:`.functional_group_factory`, can serve as good examples. """
[docs] def get_functional_groups(self, molecule): """ Yield functional groups in `molecule`. Parameters ---------- molecule : :class:`.Molecule` The molecule, whose functional groups are to be found. Yields ------ :class:`.FunctionalGroup` A functional group in `molecule`. Examples -------- See :class:`.FunctionalGroupFactory`. """ raise NotImplementedError()