shnitsel.filtering#

Submodules#

Attributes#

`FeatureDescriptor`
`StructureSelectionDescriptor`
`StateCombination`
`StateId`
`StateSelectionDescriptor`

Classes#

`StructureSelection`	Class to keep track of a (sub-)selection of structural features.
`StateSelection`	Class to keep track of a (sub-)selection of states and state transitions for analysis and plotting.

Package Contents#

class StructureSelection#

Class to keep track of a (sub-)selection of structural features.

mol: rdkit.Chem.rdchem.Mol | None#

atoms: set[AtomDescriptor]#

atoms_types: dict[AtomDescriptor, str]#

atoms_selected: set[AtomDescriptor]#

bonds: set[BondDescriptor]#

bonds_types: dict[BondDescriptor, float]#

bonds_selected: set[BondDescriptor]#

angles: set[AngleDescriptor]#

angles_types: dict[AngleDescriptor, bool]#

angles_selected: set[AngleDescriptor]#

dihedrals: set[DihedralDescriptor]#

dihedrals_types: dict[DihedralDescriptor, bool]#

dihedrals_selected: set[DihedralDescriptor]#

pyramids: set[PyramidsDescriptor]#

pyramids_types: dict[PyramidsDescriptor, bool]#

pyramids_selected: set[PyramidsDescriptor]#

feature_level_colors: dict[FeatureLevelType, str]#

copy_or_update(mol=None, atoms=None, atoms_selected=None, atoms_types=None, bonds=None, bonds_selected=None, bonds_types=None, angles=None, angles_selected=None, angles_types=None, dihedrals=None, dihedrals_selected=None, dihedrals_types=None, pyramids=None, pyramids_selected=None, pyramids_types=None, inplace=False)#

Function to create a copy with replaced member values.

Meant as a helper for the Frozen logic of the selection, i.e. method calls return a new instance instead of updating the existing instance.

Parameters:

mol (Mol | None, optional) – The new RDKit Mol object to assign to this selection. Should usually not be updated, but can be for completeness. Defaults to None.
atoms (set[AtomDescriptor] | None, optional) – New indices of atoms. Defaults to None.
atoms_selected (set[AtomDescriptor] | None, optional) – New indices of selected atoms. Defaults to None.
atoms_types (dict[AtomDescriptor, optional) – New metadata dict for atom indices. Defaults to None.
bonds (set[BondDescriptor] | None, optional) – Bond indices set. Defaults to None.
bonds_selected (set[BondDescriptor] | None, optional) – Set of bond indices that have been selected. Defaults to None.
bonds_types (dict[BondDescriptor, optional) – Dict with metadata for the bonds. Defaults to None.
angles (set[AngleDescriptor] | None, optional) – Set of all indices of angles. Defaults to None.
angles_selected (set[AngleDescriptor] | None, optional) – Set of selected indices of angles. Defaults to None.
angles_types (dict[AngleDescriptor, optional) – Dict with metadata about the angles. Defaults to None.
dihedrals (set[DihedralDescriptor] | None, optional) – Set of all indices of dihedrals in the structure. Defaults to None.
dihedrals_selected (set[DihedralDescriptor] | None, optional) – Set of selected indices of dihedrals. Defaults to None.
dihedrals_types (dict[DihedralDescriptor, optional) – Dict with metadata about dihedrals. Defaults to None.
pyramids (set[PyramidsDescriptor] | None, optional) – Set of all indices of pyramids in the structure. Defaults to None.
pyramids_selected (set[PyramidsDescriptor] | None, optional) – Set of selected indices of pyramids. Defaults to None.
pyramids_types (dict[PyramidsDescriptor, optional) – Dict with metadata about pyramids. Defaults to None.
inplace (bool, optional) – Flag to allow for in-place updates instead of returning a new cop. Defaults to False.

Returns:

The selection update with the new members set. Can either be a copy if inplace=False or the old instance with updated members otherwise.

Return type:

StructureSelection

classmethod init_from_dataset(frame, default_selection=['atoms', 'bonds'], to2D=True)#

Alternative constructor that creates an initial StructureSelection object from a dataset using the entire structural information in it.

Parameters:

cls (type[Self]) – The type of this StructureSelection so that we can create instances of it.
frame (xr.Dataset | ShnitselDataset) – The dataset (optionally a single frame) to extract the structure information out of. Must have at least atXYZ variable and a atom dimension. Ideally, an atom coordinate for feature selection is also provided. If multiple frames/timesteps are present within the data, a best-effort guess of a suitable frame from the data will be made.
default_selection (Sequence[FeatureLevelOptions], optional) – List of features to activate as selected by default. Defaults to [ ‘atoms’, ‘bonds’, ].
to2D (bool, optional) – Flag to control whether a mol representation is converted to a 2d projection before use for visualization.

Returns:

A structure selection object initially covering all atoms and structural features.

Return type:

StructureSelection

Raises:

ValueError – If no structural information could be extracted from the dataset

classmethod init_from_mol(mol, default_selection=['atoms', 'bonds'])#

Alternative constructor that creates an initial StructureSelection object from an RDKit Mol object

Parameters:

cls (type[StructureSelection]) – The type of this StructureSelection so that we can create instances of it.
mol (rdkit.rdchem.Mol) – The RDKit Mol object to extract all initial structural information out of
default_selection (Sequence[FeatureLevelOptions], optional) – List of features to activate as selected by default. Defaults to [ ‘atoms’, ‘bonds’, ].

Returns:

A structure selection object initially covering all atoms and structural features.

Return type:

StructureSelection

Raises:

ValueError – If no structural information could be extracted from the dataset.

derive_other_from_descriptor(descriptor_or_selection)#

Helper function to create another structure selection based on a StructureSelectionDescriptor

If the descriptor if already a selection, just return it. If the descriptor needs to be applied based on the current selection, construct the other selection and return the resulting selection.

Parameters:: descriptor_or_selection (StructureSelection | StructureSelectionDescriptor) – Either a complete selection or a set of descriptors to derive the new selection from the old one.
Returns:: The derived other selection or None if not enough information was provided.
Return type:: Self | None

only(feature_level, inplace=False)#

Only retain the selected features of the specified feature levels.

E.g. selection.only(‘bonds’) yields a selection where only bonds are selected as according to the previous selection. All selections for features not in feature_level will be set to an empty selection.

Parameters:

feature_level (FeatureLevelOptions | Sequence[FeatureLevelOptions] | None) – The desired feature levels to retain in the resulting selection. If set to None, all selections will be cleared.
inplace (bool, optional) – Whether to update the selection in-place. Defaults to False.

Returns:

The selection where only the chosen feature levels are still active.

Return type:

Self

select_all(feature_level=FEATURE_LEVELS, inplace=False)#

Helper function to set all entries of a certain feature level to selected.

By default marks all features as selected.

Parameters:

feature_level (FeatureLevelOptions | Sequence[FeatureLevelOptions], optional) – The set of feature levels to mark as within the selection. Defaults to all FEATURE_LEVELS.
inplace (bool, optional) – Whether to update the selection in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

select_atoms(smarts_or_selection=None, inplace=False)#

Select all atoms covered either by the smarts string(s) provided in smarts_or_selection or by either a single or multiple atom ids.

Parameters:

smarts_or_selection (str | Sequence[str] | AtomDescriptor | Sequence[AtomDescriptor] | None, optional) – Either one or multiple smart strings or a single or sequence of atom ids. Defaults to None meaning all atoms will be selected.
inplace (bool, optional) – Whether to update the selection in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

Raises:

ValueError – If self.mol is not set and SMARTS matching is attempted.

select_atoms_idx(selection=None, extend_selection=False, inplace=False)#

Function to update the selection of atoms by specifying atom indices directly.

Parameters:

selection (AtomDescriptor | Sequence[AtomDescriptor] | None, optional) – Either a single atom selector or a sequence of atom selectors. Defaults to None, which means that all available atoms will be considered.
extend_selection (bool, optional) – If set to True, the selection will be extended by the atoms denoted by selection. Otherwise, the new selection will be the intersection between the old selection and selection. Defaults to False.
inplace (bool, optional) – Whether to update this selection in-place. Defaults to False.

Returns:

The updated selection.

Return type:

StructureSelection

select_bonds(selection=None, inplace=False)#

Restrict the current selection of bonds by either specifying a SMARTS string (or sequence thereof) to specify substructures of the molecule to consider bonds in, or by providing one or more bond desciptor tuples.

Parameters:

selection (str | Sequence[str] | BondDescriptor | Sequence[BondDescriptor] | None, optional) – The criterion or criteria by which to retain bonds in the selection. Defaults to None meaning that all bonds will be added back into the selection.
inplace (bool, optional) – Whether to update the selection in-place or return an updated copy. Defaults to False.

Returns:

The updated selection object.

Return type:

Self

Raises:

ValueError – If no self.mol object is set and a SMARTS match is attempted

select_bonds_idx(selection, inplace=False)#

Helper function to select bonds by specifying the explicit Bond descriptors/tuples.

Restricts the selection further to this set.

Parameters:

selection (BondDescriptor | Sequence[BondDescriptor]) – Either an individual bond selector or a sequence of bonds to select.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selections

Return type:

StructureSelection

select_pw_dists(selected_only=True, inplace=False)#

Helper function to select all pairwise distances between atoms in the current selection, even if they are outside of our bonds.

Parameters:

selected_only (bool, optional) – Flag whether only pairwise distances in the selected atoms should be considered, by default True.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

StructureSelection

select_bonds_by_atoms(atoms=None, inplace=False)#

Helper function to select bonds by specifying a subset of atoms to consider for bonds between them.

Allows provision of a single list of atoms or multiple such lists and will iterate over them as needed.

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep bonds between or multiple sets within which the bonds should be kept. Defaults to None.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

StructureSelection

_new_bond_selection_from_atoms(atoms=None, consider_all=False)#

Internal helper to get bond selection instead of directly updating the selection

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep bonds between or multiple sets within which the bonds should be kept. Defaults to None.
consider_all (bool, optional) – Whether to use the entire set of features in the whole molecule as basis or just the selected set. Defaults to using only the currently selected set.

Returns:

The set of bond descriptors in current selection fully covered by these atoms

Return type:

set[BondDescriptor]

select_angles(selection=None, inplace=False)#

Function to restrict the angles selection by providing either providing SMARTS strings or explicit angles descriptors to retain.

Parameters:

selection (str | Sequence[str] | AngleDescriptor | Sequence[AngleDescriptor] | None, optional) – The criterion or criteria by which to retain angles in the selection. Defaults to None meaning that all angles will be added back into the selection.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

select_angles_by_atoms(atoms=None, inplace=False)#

Helper function to select angles by specifying a subset of atoms to consider angles between.

Allows provision of a single list of atoms or multiple such lists and will iterate over them as needed.

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep angles between or multiple sets within which the bonds should be kept. Defaults to None.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection.

Return type:

StructureSelection

_new_angle_selection_from_atoms(atoms=None, consider_all=False)#

Internal helper to get angle selection instead of directly updating the selection

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep angles between or multiple sets within which the bonds should be kept. Defaults to None.
consider_all (bool :) – Whether to use the entire set of features in the whole molecule as basis or just the selected set. Defaults to using only the currently selected set.

Returns:

The set of agnle descriptors in current selection fully covered by these atoms.

Return type:

set[AngleDescriptor]

select_dihedrals(selection=None, inplace=False)#

Function to restrict the dihedral selection by providing either providing SMARTS strings or explicit dihedral descriptors to retain.

Parameters:

selection (str| Sequence[str]| DihedralDescriptor| Sequence[DihedralDescriptor]| None, optional) – A SMARTS string, a sequence thereof or one or more index sets for dihedrals to be identified
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

Raises:

ValueError – If an invalid entry or selection was provided.

select_dihedrals_by_atoms(atoms=None, inplace=False)#

Helper function to select dihedrals by specifying a subset of atoms to consider dihedrals between.

Allows provision of a single list of atoms or multiple such lists and will iterate over them as needed.

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep angles between or multiple sets within which the bonds should be kept. Defaults to None.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection.

Return type:

StructureSelection

_new_dihedral_selection_from_atoms(atoms=None, consider_all=False)#

Internal helper to get dihedral selection instead of directly updating the selection

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep dihedrals between or multiple sets within which the dihedrals should be kept. Defaults to None.
consider_all (bool, optional) – Whether to use the entire set of features in the whole molecule as basis or just the selected set. Defaults to using only the currently selected set.

Returns:

The set of dihedral descriptors in current selection fully covered by these atoms

Return type:

set[DihedralDescriptor]

select_pyramids(selection=None, inplace=False)#

Function to restrict the pyramid selection by providing either SMARTS strings or explicit pyramids descriptors or sets of atoms between which to retain pyramids.

Parameters:

selection (str | Sequence[str] | PyramidsDescriptor | Sequence[PyramidsDescriptor] | None, optional) – The criterion or criteria by which to retain pyramids in the selection. Defaults to None meaning that all pyramids will be added back into the selection.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

Raises:

ValueError – If an invalid selector is provided.

select_pyramids_by_atoms(atoms=None, inplace=False)#

Helper function to select pyramids by specifying a subset of atoms to consider pyramids between.

Allows provision of a single list of atoms or multiple such lists and will iterate over them as needed.

Parameters:

atoms (Sequence[AtomDescriptor] | Sequence[Sequence[AtomDescriptor]] | None, optional) – Either a single set of atoms to keep angles between or multiple sets within which the bonds should be kept. Defaults to None.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection.

Return type:

StructureSelection

_new_pyramid_selection_from_atoms(atoms=None, consider_all=False)#

Internal helper to get pyramids selection instead of directly updating the selection

Parameters:

atoms (Sequence[AtomDescriptor]| Sequence[Sequence[AtomDescriptor]]| None :) – Either a single set of atoms to keep pyramids between or multiple sets within which the pyramids should be kept. Defaults to None.
atoms
consider_all (bool, optional) – Whether to use the entire set of features in the whole molecule as basis or just the selected set. Defaults to using only the currently selected set.

Returns:

The set of dihedral descriptors in current selection fully covered by these atoms

Return type:

set[Pyramid]

select_bats(smarts=None, subgraph_selection=None, idxs=None, mode=None, inplace=False)#

Update entire selection on this molecule to a subset of available atoms, bonds, angles or dihedrals.

Updates can be requested by providing smarts strings or by providing specific ids of features, where the feature type will be determined based on the length of the tuple.

Parameters:

smarts (str | Sequence[str] | None, optional) – One or more smarts to identify subsets of the molecule and the features therein. Defaults to None.
subgraph_selection (Sequence[AtomDescriptor], optional) – Only allow for results within the subgraph over these atoms to be retained. If not provided, no filtering will be performed. Can be used to select by the result of a SMARTS pattern match.
idxs (FeatureDescriptor | Sequence[FeatureDescriptor] | None, optional) – Either a single tuple or a sequence of tuples to use for the update. Will be assigned based on the length of the tuple. Defaults to None.
mode (Literal['repl', 'intersect', 'ext', 'sub'] | None, optional) – The mode for the update. The new selection can either be the intersection of the current selection and the features covered by the new update set, it can be extended to contain the new update set (‘ext’) or the new update set can be removed from the current selection (sub). Can also be ‘repl’ to indicate that we want to replace all indices with the provided idxs results. Defaults to ‘intersect’ if a SMARTS is provided, to ‘repl’ if only idxs is provided.
inplace (bool, optional) – Whether the selection should be updated in-place. Defaults to False.

Returns:

The updated selection

Return type:

Self

select#

static __match_pattern(mol, smarts)#

Find all substructure matches of a SMARTS pattern in a molecule.

Parameters:

mol (rdkit.Chem.rdchem.Mol|None) – RDKit molecule object.
smarts (str) – SMARTS pattern to search for.

Returns:

list of Sequence of AtomDescriptor – Each Entry contains all atom indices corresponding to one match of the SMARTS pattern. Returns an empty list if no match is found.
None – if the provided SMARTS string was invalid.
Raises
——-
ValueError (If no mol object is provided. Cannot match if not molecule object provided.)

Return type:

list[Sequence[AtomDescriptor]] | None

static _flatten(obj)#

Helper functiont to flatten nested lists

Parameters:: obj (list|Any) – A potentially nested set of lists.
Yields:: Iterator[Any] – The iterator to iterate over all entries in the flattened list.
Return type:: Iterator

draw(flag_level='bonds', highlight_color=None, width=300, height=300)#

Helper function to allow visualization of the structure represented in this selection.

Parameters:

flag_level (FeatureLevelOptions, optional) – Currently unused. Defaults to ‘bonds’.
highlight_color (tuple[float, float, float] | str, optional) – Color to use for highlights of the active parts. Defaults to a flag-level dependent color.
width (int, optional) – Width of the figure. Defaults to 300.
height (int, optional) – Height of the figure. Defaults to 300.

Returns:

The SVG representation of this selection’s figure.

Return type:

SVG

__get_active_atoms(flag_level='atoms')#

Helper function to get the list of atoms involved in the selection at feature level flag_level.

Parameters:: flag_level (Literal[1, 2, 3, 4], optional) – The level of selection that should be used for finding all involved bonds. Defaults to 1.
Returns:: The list of atom indices involved in the selection at the desired feature level.s
Return type:: list[AtomDescriptor]

__get_active_bonds(flag_level='bonds')#

Get the list of active bonds at a certain level of selection, i.e. in bonds, in angles, in dihedrals, or in pyramids.

Parameters:: flag_level (FeatureLevelOptions, optional) – The level of selection that should be used for finding all involved bonds. Needs to be at least 2 (bonds) to yield any bonds. Defaults to 2.
Returns:: The list of involved bond descriptors at that feature level.
Return type:: list[BondDescriptor]

bond_descriptor_to_mol_index(bond_descriptors)#

Helper function to translate a list of Bond descriptors into RDKit bond indices.

Parameters:

bond_descriptors (list[BondDescriptor]) – The list of BondDescriptor tuples that we want to translate into RDKit mol internal bond indices.

Returns:

list[int] – The mapped list of RDKit self.mol internal bond indices.
int – If a single bond descriptor was provided

Raises:

AssertionError – if self.mol is None, no mapping can be performed.

Return type:

int | list[int]

select_BLA_chromophor(BLA_smarts=None, num_double_bonds=None, allowed_chain_elements='#6,#7,#8,#15,#16', max_considered_BLA_double_bonds=50, inplace=False)#

Select the (maximum length) BLA chromophor in the system.

You can provide a SMARTS to match the BLA chromophor directly, specify the number of double bonds in the chromophor and the allowed elements in the BLA chain via allowed_chain_elements, which will be integrated directly into the SMARTS string or the function will automatically try to detect the maximum BLA system size.

This function assumes the BLA chromophor to be unique. If the maximum chromophor is not unique, an error will be raised. In that case, you can get all the matches by building the BLA SMARTS with __build_conjugated_smarts() and yield the entire chromophore match with select_bats() for that SMARTS.

Parameters:

BLA_smarts (str | None, optional) – The SMARTS string to match the maximum chromophor to. Defaults to None.
num_double_bonds (int | None, optional) – The number of double bonds in the maximum size chromophor to construct a SMARTS string if not provided. Defaults to None.
allowed_chain_elements (str, optional) – Allowed elements along the chromophor chain. Defaults to “#6,#7,#8,#15,#16”.
max_considered_BLA_double_bonds (int, optional) – Maximum number of double bonds in a BLA chromophor if automatic maximum size detection is performed. Defaults to 50.
inplace (bool, optional) – Whether to update the selection in-place. Defaults to False.

Returns:

The updated selection constrained to the unique BLA chromophor of maximum length

Return type:

StructureSelection

Raises:

ValueError – If the maximum BLA is not unique.

static __build_conjugated_smarts(num_double_bonds, allowed_chain_elements='#6,#7,#8,#15,#16')#

Build a SMARTS pattern for a linear conjugated system with n_double alternating double bonds.

Example (n_double=2): [#6,#7]=[#6,#7]-[#6,#7]=[#6,#7]

Parameters:

num_double_bonds (int) – Number of C=C-like double bonds. Must be positive, i.e. at least 1.
allowed_chain_elements (str) – SMARTS atomic specification, i.e. comma-separated list of element descriptors (default: C,N,O,P,S represented as ‘#6,#7,#8,#15,#16’).

Returns:

SMARTS string encoding the conjugated system.

Return type:

str

static _to_feature_level_str(ft)#

Convert arbitrary representations of feature levels (level ids or level names) to standardized level name.

Parameters:: ft (FeatureLevelOptions) – A representation of a feature level
Returns:: A string representing the feature level
Return type:: FeatureLevelType

static canonicalize_bond(bond)#

Impose a standardized index order in bonds.

Parameters:: bond (BondDescriptor) – The bond descriptor to canonicalize
Returns:: The bond descriptor with standardized index order
Return type:: BondDescriptor

static canonicalize_angle(angle)#

Impose a standardized index order in angles.

Parameters:: angle (AngleDescriptor) – The angle descriptor to canonicalize
Returns:: The bond descriptor with standardized index order
Return type:: AngleDescriptor

static canonicalize_dihedral(dihedral)#

Impose a standardized index order in dihedrals.

Parameters:: dihedral (DihedralDescriptor :) – The dihedral descriptor to canonicalize
Returns:: The dihedral descriptor with standardized index order
Return type:: DihedralDescriptor

static canonicalize_pyramid(pyramid)#

Impose a standardized index order in pyramids.

Parameters:: pyramid (PyramidsDescriptor :) – The pyramid descriptor to canonicalize
Returns:: The pyramid descriptor with standardized index order
Return type:: PyramidsDescriptor

get_bond_type(bond)#

Helper function to get the bond type between two atoms

Parameters:: bond (BondDescriptor) – The bond descriptor
Returns:: The bond type as a float
Return type:: float

static __get_smiles_order(mol, include_h=True)#

Returns the order in which atoms would appear in the canonical SMILES of mol, ignoring hydrogens

Parameters:

mol (Mol) – An rdkit.Chem.Mol object
include_h (bool, optional) – A flag to include the H atoms in the smiles order. If set to False, will return the set of original indices of all atoms but hydrogens. If set to True, will return the index set of all atoms in the molecule.

Returns:

A list of integers representing indices of the original mol object (as opposed to the integers assigned to the copy stripped of hydrogens)

Return type:

list[int]

Notes

Helper function for non_redundant() method to get the non-redundant subset of bonds, angles and dihedrals.

non_redundant(include_h=True, inplace=False)#

Compute a non-redundant set of bonds, angles, and dihedrals sufficient to uniquely determine the atoms of the input, given a fixed centre and whole-molecular orientation.

Parameters:

include_h (bool, optional) – Whether to include internal coordinates for hydrogen atoms
inplace (bool, optional) – Whether to update the selection in-place. Defaults to False, yielding a new object.

Returns:

The updated StructureSelection object with only non-redundant coordinates in bonds, angles and dihedrals.

Return type:

Self

Note

For many cases including methane, the internal coordinates returned by this function will not be complete (but should still be non-redundant). E.g. in the case of methane, 7 (distinct) coordinates will be returned where 5*3-6=9 would be expected. This should mostly affect the internal coordinates of hydrogens as opposed to those of heavy atoms.

__add__(other)#

Add the selected entries of the other structure selection to a shared selection.

For consistency reasons, the other StructureSelection (which can be provided as a descriptor instead), should be built upon the same base structure/molecule.

Warning

Metadata is not copied over, only the selection. The support for arithmetic or boolean operations is only meant as a helper to make combinations of selections easier.

Parameters:: other (Self | StructureSelectionDescriptor) – The selected features to add to this selection, either as another structure selection or as a description of features, SMARTS or FeatureLevels, that can be used in the various .select_*() methods on this class.
Returns:: A StructureSelection object representing the union of the selections
Return type:: Self

__or__#

__sub__(other)#

Remove the selected entries of the other structure selection to create a new selection.

For consistency reasons, the other StructureSelection (which can be provided as a descriptor instead), should be built upon the same base structure/molecule.

Warning

Metadata is not copied over, only the selection. The support for arithmetic or boolean operations is only meant as a helper to make combinations of selections easier.

Parameters:: other (Self | StructureSelectionDescriptor) – The selected features to remove from this selection, either as another structure selection or as a description of features, SMARTS or FeatureLevels, that can be used in the various .select_*() methods on this class.
Returns:: A StructureSelection object representing the difference of the selections (elements in the first but not the second)
Return type:: Self

__and__(other)#

Build the intersection of the selected entries of the other structure selection and this selection to create a new selection.

For consistency reasons, the other StructureSelection (which can be provided as a descriptor instead), should be built upon the same base structure/molecule.

Warning

Metadata is not copied over, only the selection. The support for arithmetic or boolean operations is only meant as a helper to make combinations of selections easier.

Parameters:: other (Self | StructureSelectionDescriptor) – The selected features to intersect with this selection, either as another structure selection or as a description of features, SMARTS or FeatureLevels, that can be used in the various .select_*() methods on this class.
Returns:: A StructureSelection object representing the intersection of the selections (elements in the first and the second).
Return type:: Self

__invert__()#

Get an inverted selection of the features within this selection

Returns:: A StructureSelection object representing the inverted selection in this object.
Return type:: Self

union#

intersect#

difference#

invert#

type FeatureDescriptor = AtomDescriptor | BondDescriptor | AngleDescriptor | DihedralDescriptor | PyramidsDescriptor#

type StructureSelectionDescriptor = SMARTSstring | FeatureLevelType | FeatureDescriptor | Collection[SMARTSstring | FeatureLevelType | FeatureDescriptor]#

class StateSelection#

Class to keep track of a (sub-)selection of states and state transitions for analysis and plotting.

is_directed: bool#

states_base: Sequence[shnitsel.core.typedefs.StateId]#

states: Sequence[shnitsel.core.typedefs.StateId]#

ground_state_id: shnitsel.core.typedefs.StateId#

state_types: dict[shnitsel.core.typedefs.StateId, int] | None#

state_names: dict[shnitsel.core.typedefs.StateId, str] | None#

state_charges: dict[shnitsel.core.typedefs.StateId, int] | None#

state_degeneracy_group: dict[shnitsel.core.typedefs.StateId, int] | None#

degeneracy_group_states: dict[int, list[shnitsel.core.typedefs.StateId]] | None#

state_combinations_base: list[shnitsel.core.typedefs.StateCombination]#

state_combinations: list[shnitsel.core.typedefs.StateCombination]#

state_combination_names: dict[shnitsel.core.typedefs.StateCombination, str] | None#

state_colors: dict[shnitsel.core.typedefs.StateId, str] | None = None#

state_combination_colors: dict[shnitsel.core.typedefs.StateCombination, str] | None = None#

copy_or_update(*, is_directed=None, ground_state_id=None, states=None, state_types=None, state_names=None, state_charges=None, state_combinations=None, state_combination_names=None, state_colors=None, state_combination_colors=None, state_degeneracy_group=None, degeneracy_group_states=None, inplace=False)#

Function to create a copy with replaced member values.

Meant as a helper for the Frozen logic of the selection, i.e. method calls return a new instance instead of updating the existing instance.

Parameters:

is_directed (bool, optional) – Potentially new flag whether state combinations are considered to be directed (i.e. (1,3) is different from (3,1)) or not. Defaults to None.
ground_state_id (StateId or None, optional) – Potentially new ground_state id. Defaults to None.
states (Sequence[StateId] or None, optional) – Potentially new state ids. Defaults to None.
state_types (dict[StateId, int] or None, optional) – Potentially new state types/multiplicities. Defaults to None.
state_names (dict[StateId, str] or None, optional) – Potentially new state names. Defaults to None.
state_degeneracy_group (dict[StateId, int] or None, optional) – Optional degeneracy group indices for states. Defaults to None.
degeneracy_group_states (dict[int, list[StateId]] or None, optional) – Optional mapping of degeneracy groups to the states they hold. Defaults to None.
state_charges (dict[StateId, int] or None, optional) – Potentially new state charges. Defaults to None.
state_combinations (list[StateCombination] or None, optional)) – Potentially new state combinations. Defaults to None.
state_combination_names (dict[StateCombination, str] or None, optional) – Potentially new names for state combinations. Defaults to None.
inplace (bool, optional) – A flag whether the existing instance should be updated or a new one should be created. Defaults to False, i.e. a new instance is created.
state_colors (dict[StateId, str] or None, optional) – An optional colormap for states. Defaults to None.
state_combination_colors (dict[StateCombination, str] or None, optional) – An optional colormap for state combinations. Defaults to None.

Returns:

The selection update with the new members set. Can either be a copy if inplace=False or the old instance with updated members otherwise.

Return type:

StateSelection

classmethod init_from_dataset(dataset, is_directed=False)#

Alternative constructor that creates an initial StateSelection object from a dataset using the entire state information in it.

Parameters:

cls (type[StateSelection]) – The type of this StateSelection so that we can create instances of it.
dataset (xr.Dataset or ShnitselDataset) – The dataset to extract the state information out of. Must have a state dimension and preferrably coordinates state, state_names, state_types, state_charges, and statecomb set. If state is not set as a coordinate, a potential dimension size of state is taken and states are enumerates 1 through 1+dataset.sizes[‘state’]. If statecomb is not set as a coordinate, all unordered pairs of states will be used as a default value for state_combinations.
is_directed (bool, default=False) – Flag whether state combinatons should be assumed different, i.e. (1,3) should be considered different from (3,1).

Returns:

A state selection object initially covering all states (and state combinations) present in the dataset.

Return type:

StateSelection

Raises:

ValueError – If no state information could be extracted from the dataset

classmethod init_from_descriptor(spec, is_directed=None)#

Build a (rather rudimentary) state selection and state combination selection from descriptors with no support for determination of multiplicity groups and others but to simplify the process of providing a state selection to function calls.

Parameters:

cls (type[Self]) – StateSelection class to use for construction.
spec (StateSelectionDescriptor) – Either a single spec string, a Sequence of state ids or state id pairs or a sequence of spec strings. A selection of [(1, 2), (2, 1), (3, 1)] means to select only transitions between states 1 and 2 as well as from 3 to 1 (but not from 1 to 3). Alternatively, combinations may be specified as a single string in the following style: '1<>2, 3->1' – this specification selects the same combinations as in the previous example, with <> selecting transitions in either direction and -> being one-directional.
is_directed (bool, optional) – Flag whether state combinatons should be assumed different, i.e. (1,3) should be considered different from (3,1). If not provided, will be set depending on whether there is a directed transition in the descriptors, i.e. i -> j.

Returns:

A StateSelection built from the state specification.

Return type:

Self

static _standard_state_comb_spec(spec)#

Support extracting states and state combinations from strings.

Parameters:: spec (str) – The spec string with a certain pattern. A state selection holding states or state transitions that should be used in analysis, e.g.: A selection of [(1, 2), (2, 1), (3, 1)] means to select only transitions between states 1 and 2 as well as from 3 to 1 (but not from 1 to 3). Alternatively, combinations may be specified as a single string in the following style: '1<>2, 3->1' – this specification selects the same hops as in the previous example, with <> selecting hops in either direction and -> being one- directional.
Returns:: First the list of StateIds mentioned in the selection descriptor, then the list of state combinations listed in the state combination mentioned in the state selection descriptor. Finally a flag whether there was at least one directed state combination specifier.
Return type:: tuple[list[StateId], list[StateCombination], bool]

static _abstract_state_comb_spec(spec, states_from_sc_statements=False)#

Support for abstract state combination description, allowing for inputs like T->S to specify transitions from a triplet to a singlet state in addition to the extraction of specific state ids in ._standard_state_comb_spec()

Parameters:

spec (str) – The spec string with a certain pattern. A state selection (optionally including patterns) holding states or state transitions that should be used in analysis, e.g.: A selection of [(1, 2), (2, 1), (3, 1)] means to select only transitions between states 1 and 2 as well as from 3 to 1 (but not from 1 to 3). Alternatively, combinations may be specified as a single string in the following style: '1<>2, 3->1' – this specification selects the same hops as in the previous example, with <> selecting hops in either direction and -> being one- directional. States can also be described using their names (if configured, e.g. ‘S0’) or a label describing their multiplicities (if configured, e.g. ‘T’ for all triplet states)
states_from_sc_statements (bool, default=False) – Flag whether states mentioned in state combination statements should be included in the resulting sets for explicit states and state patterns. E.g. if the selection is 1->2, normally, the state selection would be empty, but with states_from_sc_statements=True, the state selection would be [1,2].

Returns:

set[StateId], set[StateCombination], set[MultiplicityLabel | str], set[

tuple[
MultiplicityLabel | str | StateId, MultiplicityLabel | str | StateId,

]

], bool] First the set of explicit StateIds mentioned in the selection descriptor, then the set of explicit state combinations listed in the state combination mentioned in the state selection descriptor. Third the set of patterns for states, i.e. the set of multiplicity labels or state names, Fourth the set of patterns for state types, i.e. tuples involving at least one pattern for states. Finally a flag whether there was at least one directed state combination specifier.

Return type:

tuple[

as_directed_selection()#

Helper method to turn an undirected selection into a directed selection.

If the selection is already directed, it will be returned unmodified.

Returns:: Either the already directed selection or a copy with all mirrored transitions also initially included.
Return type:: Self

as_undirected_selection()#

Helper method to turn a directed selection into an undirected selection.

If the selection is already undirected, it will be returned unmodified.

Returns:: Either the already undirected selection or a copy with all transitions reduced to those with canonical order.
Return type:: Self

static _state_comb_canonicalized(comb, is_directed)#

Helper to turn transitions into a canonic order if the selection is not directed.

If the selection is directed, the combination is returned as-is.

Parameters:

comb (StateCombination) – The combination tuple to turn into a canonical order
is_directed (bool) – Flag whether the order should be canonical in a set with this is_directed flag

Returns:

The canonicalized combination tuple.

Return type:

StateCombination

_state_id_matches_pattern(state, pattern)#

Helper function to check whether a state Id matches a certain string pattern provided by a user.

Parameters:

state (StateId) – The state id to check for a match
pattern (MultiplicityLabel | str | StateId) – The pattern to compare the state to. Can be a multiplicity label or a state name. If the values for multiplicity labels or state names are not set, this may result in an exception being raised

Returns:

Whether the state matches the pattern

Return type:

bool

Raises:

RuntimeError – If matching for multiplicity or name is requested and type information or name data is missin.

_state_ids_match_pattern(base_selection, pattern)#

Helper function to check which states out of a collection matches a certain string pattern provided by a user.

Parameters:

base_selection (Iterable[StateId]s) – The state id to check for a match
pattern (MultiplicityLabel | str) – The pattern to compare the state to. Can be a multiplicity label or a state name. If the values for multiplicity labels or state names are not set, this may result in an error.

Returns:

The set of state ids from the selection that adhere to the pattern.

Return type:

set[StateId]

_state_combs_matches_pattern(state_comb, pattern)#

Helper function to check whether a specific state combinations matches a certain string pattern provided by a user.

Parameters:

state_comb (StateCombination) – The state combination to check for a match
pattern (tuple[MultiplicityLabel | str | StateId, MultiplicityLabel | str | StateId]) – The pattern to compare the state to. Each entry can be a multiplicity label or a state name and of of both entries can be an explicit state id.. If the values for multiplicity labels or state names are not set, this may result in an error.

Returns:

Boolean flag whether the state combinations matches the pattern

Return type:

boole

_state_combs_match_pattern(base_selection, pattern)#

Helper function to check which state combinations out of a collection matches a certain string pattern provided by a user.

Parameters:

base_selection (Iterable[StateCombination]) – The state combinations to check for a match
pattern (tuple[MultiplicityLabel | str, MultiplicityLabel | str]) – The pattern to compare the state to. Each entry can be a multiplicity label or a state name. If the values for multiplicity labels or state names are not set, this may result in an error.

Returns:

The set of state combination identifiers from the selection that adhere to the pattern.

Return type:

set[StateCombination]

select_states(selectors=None, *, exclude_ids=None, charge=None, exclude_charge=None, multiplicity=None, exclude_multiplicity=None, min_states_in_selection=0, states_from_sc=False, inplace=False)#

Method to get a new state selection only retaining the states satisfying the required inclusion criteria and not satisfying the exclusion criteria.

Will return a new StateSelection object with the resulting set of states.

Parameters:

selectors (Iterable[StateId or StateSelectionDescriptor] or StateId or StateSelectionDescriptor or None, optional) – Explicit ids of states to retain. Either a single id or an iterable collection of state ids can be provided. Defaults to None.
exclude_ids (Iterable[StateId] or StateId or None, optional)) – Explicit ids of states to exclude. Either a single id or an iterable collection of state ids can be provided. Defaults to None.
charge (Iterable[int] or int or None, optional) – Charges of states to retain. Defaults to None.
exclude_charge (Iterable[int] or int or None, optional) – Charges of states to exclude. Defaults to None.
multiplicity (Iterable[int] or int or None, optional) – Multiplicity of states to retain. Defaults to None.
exclude_multiplicity (Iterable[int] or int or None, optional) – Multiplicity of states to exclude. Defaults to None.
min_states_in_selection ({0, 1, 2}, optional) – Optional parameter to determine whether state combinations should be kept if states they include are no longer part of the selection. A state combination is retained if at least min_states_in_selection of their states are still within the state selection. Defaults to 0, meaning all combinations are kept.
states_from_sc (bool, default=False) – Flag, whether states should be included in the selection based on states mentioned in state combination selectors. By default False.
inplace (bool, optional) – Flag to update the selection in-place. Defaults to False, meaning a modified copy is returned.

Returns:

The resulting selection after applying all of the requested conditions.

Return type:

StateSelection

static _mult_label_transl(multipl: Iterable[int | shnitsel.core.typedefs.MultiplicityLabel]) → set[int]#

static _mult_label_transl(multipl: int | shnitsel.core.typedefs.MultiplicityLabel) → int

Function to translate potential string-based multiplicities to integers

Parameters:: multipl (int or MultiplicityLabel or Iterable[int or MultiplicityLabel]) – List of multiplicities, either ints or string labels
Returns:: A set representation of the numeric multiplicities or the single translated value
Return type:: int or set[int]

select_state_combinations(selectors=None, *, ids=None, min_states_in_selection=0, inplace=True)#

Method to get a new state selection with a potentially reduced set of state combinations.

Parameters:

selectors (StateSelectionDescriptor or Iterable[StateSelectionDescriptor], optional) – A textual or tuple-based description of the
ids (Iterable[StateCombination] or None, optional) – Explicit state transitions ids to retain. Defaults to None.
min_states_in_selection (Literal[0, 1, 2], optional) – Minimum number of states involved in the state combination that still need to be within the state selection to keep this combination. Defaults to 0, meaning no check will be performed.
inplace (bool, optional) – Flag to update the selection in-place. Defaults to False, meaning a modified copy is returned.

Returns:

A new state selection with potentially fewer state combinations considered.

Return type:

StateSelection

select(selectors=None, *, exclude=None, min_states_in_selection=0, states_from_sc=False)#

Method to select both states and state combinations in one go.

Internally calls .select_states() and .select_state_combinations(). Additionally, the exclude keyword parameter can be used to remove matched entries from the overall selection. If no parameters are provided, all states and state combinations will be provided. May implicitly convert to a directed selection if descriptors include directed transitions.

Parameters:

selectors (Iterable[StateId | StateCombination | StateSelectionDescriptor] | StateId | StateCombination | StateSelectionDescriptor | None, optional) –
The description of states and state combinations supposed to be included within the resulting selection. The description can be a state id (int), a transition id, (tuple[int,int]) or a str with comma-separated statements denoting either states or state combinations. The following statements are supported in selector strings:
- A str representation of a state id.
- A multiplicity label e.g. ‘S’ or ‘t’ (capitalization irrelevant, requires state types to be set)
- A state name, if state names are configured on this selection, e.g, ‘S0’
- A state combination representation as a str, of one of the following forms:
  
  ’<state_a> -> <state_b>’ (for directed transitions a to b)
  
  ’<state_a> <> <state_b>’ (for undirected/bidirectional transitions between a and b)
  All <state> expressions may take any statement of the state representations above.
By default, no states will be selected.
exclude (Iterable[StateId | StateSelectionDescriptor] | StateId | StateSelectionDescriptor | None, optional) – Same format at selectors. If set, the states and state combinations selected by this argument are excluded from the resulting selection. By default None, meaning no states will be removed.
min_states_in_selection (Literal[0, 1, 2], optional) – Optional parameter to denote, how many states of a state combination must be within the selection for the state combination to be included in a result, by default 0 E.g. if only states 1 and 3 are selected, and the selection would include 1->2, this parameter needs to be 1 or 0 for (1,2) to be included in the result.
states_from_sc (bool, default=False) – Flag, whether states should be included in the selection based on states mentioned in state combination selectors. By default False.

Returns:

The resulting selection with states and state combinations selected.

Return type:

Self

set_state_names(names, inplace=True)#

Helper function to assign new state names to the selection.

Will peform some sanity checks first.

Parameters:

names (Sequence[str] or dict[StateId, str]) – Either a list of state names aligned with self.states ids or a dictionary mapping state ids to names.
inplace (bool, optional) – Flag to determine whether this function should update the existing selection sequence or return a modified copy. Defaults to True, meaning the existing instance is updated.

Returns:

Either the existing selection with updated names or a new instance with modified names.

Return type:

Self

Raises:

ValueError – If a Sequence is provided that does not have enough values
ValueError – If a dict is provided that does not have mapping for all state ids in self.states

set_state_types(types, inplace=True)#

Helper function to assign new state types/multiplicites to the selection.

Will peform some sanity checks first.

Parameters:

types (Sequence[int] or dict[StateId, int]) – Either a list of state types/multiplicities aligned with self.states ids or a dictionary mapping state ids to types.
inplace (bool, optional) – Flag to determine whether this function should update the existing selection sequence or return a modified copy. Defaults to True, meaning the existing instance is updated.

Returns:

Either the existing selection with updated types or a new instance with modified types.

Return type:

Self

Raises:

ValueError – If a Sequence is provided that does not have enough values
ValueError – If a dict is provided that does not have mapping for all state ids in self.states

set_state_charges(charges, inplace=True)#

Helper function to assign new state charges to the selection.

Will peform some sanity checks first.

Parameters:

charges (int or Sequence[int] or dict[StateId, int]) – Either a single charge for all states or a list of state charges aligned with self.states ids or a dictionary mapping state ids to charges.
inplace (bool, optional) – Flag to determine whether this function should update the existing selection sequence or return a modified copy. Defaults to True, meaning the existing instance is updated.

Returns:

Either the existing selection with updated charges or a new instance with modified charges.

Return type:

Self

Raises:

ValueError – If a Sequence is provided that does not have enough charges
ValueError – If a dict is provided that does not have mapping for all state ids in self.states

set_state_combinations(combinations, inplace=True)#

Helper function to assign new state combinations to the selection.

Will peform some sanity checks first.

Parameters:

combinations (Sequence[StateCombination]) – A list of state combination tuples to set to the selection
inplace (bool, optional) – Flag to determine whether this function should update the existing selection or return a modified copy. Defaults to True, meaning the existing instance is updated.

Returns:

Either the existing selection with updated combinations or a new instance with modified combinations.

Return type:

Self

Raises:

ValueError – If an entry in the combinations sequence has a non-positive state entry.

set_state_combination_names(names, inplace=True)#

Helper function to assign new state combination labels to the selection.

Will peform some sanity checks first.

Parameters:

names (Sequence[str] | dict[StateCombination) – Either a list of state combination names aligned with self.state_combinations or a dictionary mapping state combination ids to names.
inplace (bool, optional) – Flag to determine whether this function should update the existing selection or return a modified copy. Defaults to True, meaning the existing instance is updated.

Returns:

Either the existing selection with updated names or a new instance with modified names.

Return type:

Self

Raises:

ValueError – If a Sequence is provided that does not have enough values
ValueError – If a dict is provided that does not have mapping for all state combination ids in self.state_combinations

singlets_only(inplace=False)#

Helper function to immediately filter only singlet states. Does not affect state combinations.

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.
Returns:: the updated selection only containing singlet states.
Return type:: StateSelection

triplets_only(inplace=False)#

Helper function to immediately filter only triplet states. Does not affect state combinations.

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.
Returns:: the updated selection only containing triplet states.
Return type:: StateSelection

same_multiplicity_transitions(inplace=False)#

Helper function to only retain combinations between states of the same multiplicities (e.g. for NACs)

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.
Returns:: the updated selection only containing transitions between states of same multiplicity (i.e. singlet-singlet, triplet-tiplet).
Return type:: StateSelection

different_multiplicity_transitions(inplace=False)#

Helper function to only retain combinations between states of the different multiplicities (e.g. for SOCs)

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.
Returns:: the updated selection only containing transitions between states of different multiplicity (i.e. singlet-triplet).
Return type:: StateSelection

ground_state_transitions(ground_state_id=None, inplace=False)#

Helper function to only retain combinations between states containing the lowest-level state id.

Parameters:

ground_state_id (StateId, optional) – Id of the state to be considered the ground state. Defaults to the lowest id of the selected states.
inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.

Returns:

the updated selection only containing transitions between ground state and other states.

Return type:

StateSelection

excited_state_transitions(ground_state_id=None, inplace=False)#

Helper function to only retain combinations between states not involving the ground state.

Parameters:

ground_state_id (StateId, optional) – Id of the state to be considered the ground state. Defaults to the lowest id of the selected states.
inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.

Returns:

the updated selection only containing transitions between non-ground states.

Return type:

StateSelection

non_degenerate(inplace=False)#

Helper function to remove all degenerate states and combinations identical except for degeneracy.

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to False.
Returns:: the updated selection only containing non-degenerate states and non-degenerate-equivalent combinations.
Return type:: StateSelection

state_info()#

Get an iterator over the states in this selection.

Yields:: Iterable[StateInfo] – An iterator over the available state info
Return type:: Iterable[shnitsel.core.typedefs.StateInfo]

get_state_name_or_default(id)#

Helper method to either get registered state name or a default string to identify the state

Parameters:: id (StateId) – Id of the state to get the name for.
Returns:: Label of the state
Return type:: str

get_state_combination_name_or_default(comb)#

Helper method to either get registered state combination name or a default string to identify the state combination.

Parameters:: comb (StateCombination) – Id of the state combination to get the name for.
Returns:: Label of the state combination
Return type:: str

get_state_tex_label(id)#

Function to get a nice tex-printable label with super- and subscripts for the denoted state.

Parameters:: id (StateId) – Id of the state to get the label for
Returns:: Tex-label that needs to be enclosed in a math environment to not cause issues.
Return type:: str

get_state_combination_tex_label(comb)#

Function to get a nice tex-printable label with super- and subscripts for a state combination in this selection

Parameters:: comb (StateCombination) – Combination identifier to get the label for
Returns:: Tex-label that needs to be enclosed in a math environment to not cause issues.
Return type:: str

combination_info(degeneracy_free=False)#

Get an iterator over the state combinations in this selection.

Parameters:: degeneracy_free (bool, optional) – If set to true, combinations with already covered degeneracy-groups will be skipped
Yields:: Iterable[StateCombInfo] – An iterator over the available state combination info
Return type:: Iterable[shnitsel.core.typedefs.StateCombInfo]

has_state(id)#

Function to check whether a state is in the selection

Parameters:: id (StateId) – The state id to check whether it has been selected
Returns:: True if in the selection, False otherwise.
Return type:: bool

has_state_combination(comb)#

Function to check whether a state combination is in the selection

Parameters:: comb (StateCombination) – The combination to check whether it has been selected
Returns:: True if in the selection, False otherwise.
Return type:: bool

auto_assign_colors(inplace=True)#

Function to automatically generate colors for states and state combinations

Parameters:: inplace (bool, optional) – Flag whether the operation should update the selection in-place. Defaults to True because setting colors is not a big issue.
Returns:: Returns the updated instance.
Return type:: Self

get_state_color(id)#

Function to get a the state color or a default color value

Parameters:: id (StateId) – Id of the state to get the color for
Returns:: Hex-str color code
Return type:: str

get_state_combination_color(comb)#

Function to get a the state combination color or a default color value

Parameters:: comb (StateCombination) – Id of the state combination to get the color for
Returns:: Hex-str color code
Return type:: str

get_state_combination_degeneracy(comb)#

Function to get the combined degeneracy classes of the two states.

Helpful for not plotting too degenerate entries.

Parameters:: comb (StateCombination) – Id of the state combination to get the color for
Returns:: Degeneracy groups of either state
Return type:: tuple[int, int]

get_state_degeneracy(state)#

Function to get the combined degeneracy classes of the two states.

Helpful for not plotting too degenerate entries.

Parameters:

comb (StateCombination) – Id of the state combination to get the color for
state (shnitsel.core.typedefs.StateId)

Returns:

Hex-str color code

Return type:

str

__add__(other)#

Add the states and state combinations of another state selection into the selection represented by this selection.

For consistency reasons, the other StateSelection (which can be provided as a descriptor instead), should be built upon the same base state and state combination ground set.

Parameters:: other (Self | StateSelectionDescriptor) – The states and state combinations to add to this selection, either as another state selection or as a description of states and state combinations that can be passed to StateSelection.init_from_descriptor().
Returns:: A StateSelection object representing the union of the selections
Return type:: Self

__or__#

__sub__(other)#

Remove the states and state combinations of another state selection from the selection represented by this selection.

For consistency reasons, the other StateSelection (which can be provided as a descriptor instead), should be built upon the same base state and state combination ground set.

Parameters:: other (Self | StateSelectionDescriptor) – The states and state combinations to remove to this selection, either as another state selection or as a description of states and state combinations that can be passed to StateSelection.init_from_descriptor().
Returns:: A StateSelection object representing the difference of the selections
Return type:: Self

__and__(other)#

Get a selection of the states and state combinations shared between this and another state selection.

For consistency reasons, the other StateSelection (which can be provided as a descriptor instead), should be built upon the same base state and state combination ground set.

Parameters:: other (Self | StateSelectionDescriptor) – The states and state combinations to intersect with this this selection, either as another state selection or as a description of states and state combinations that can be passed to StateSelection.init_from_descriptor().
Returns:: A StateSelection object representing the intersection of the selections
Return type:: Self

__invert__()#

Get an inverted selection of the states and state combinations in this state selection.

Warning

The result of this operation will only be as expected, if the selection was built from a full dataset such that states_base and state_combinations_base have been set correctly. If the selection was built from a textual or tuple representation, the inverted selection will only consider the states listed in the original description.

Returns:: A StateSelection object representing the inverted selection in this object
Return type:: Self

union#

intersect#

difference#

invert#

type StateCombination = tuple[StateId, StateId]#

type StateId = int#

type StateSelectionDescriptor = Sequence[StateId | StateCombination] | Sequence[str] | str#

shnitsel.filtering#

Submodules#

Attributes#

Classes#

Package Contents#

This Page