Gibbs Model

GibbsModel fragmentation module.

class GibbsModel(subgroups: DataFrame, subgroups_info: DataFrame | None = None, calculate_r_q: bool = True)[source]

Bases: FragmentationModel

GibbsModel it’s a fragmentation model dedicated to Gibbs excess models.

unifac, psrk, dortmund are instances of this class.

Parameters:

  • subgroups (pd.DataFrame) – Model’s subgroups. Index: ‘group’ (subgroups names). Mandatory columns: ‘smarts’ (SMARTS representations of the group to detect its presense in the molecule).

  • subgroups_info (Union[pd.DataFrame, None], optional) – Information of the model’s subgroups (R, Q, subgroup_number, main_group), by default None

  • calculate_r_q (bool, optional) – Whether calculate R and Q values or not, by default True

subgroups

Model’s subgroups. Index: ‘group’ (subgroups names). Columns: ‘smarts’ (SMARTS representations of the group to detect its presense in the molecule).

Type:

pd.DataFrame

detection_mols

Dictionary containing all the rdkit Mol object from the detection_smarts subgroups column

Type:

dict

subgroups_info

Information of the model’s subgroups. Columns: R, Q, subgroup_number, main_group. Index: ‘group’ (subgroups names)

Type:

pd.DataFrame

get_groups(identifier: str | Mol, identifier_type: str = 'name', solver: ILPSolver = <class 'ugropy.core.ilp_solvers.default_solver.DefaultSolver'>, search_multiple_solutions: bool = False, search_nonoptimal: bool = False, solver_arguments: dict = {}) → GibbsFragmentationResult | List[GibbsFragmentationResult][source]

Get the groups of a molecule.

Parameters:

  • identifier (Union[str, Chem.rdchem.Mol]) – Identifier of the molecule. You can use either the name of the molecule, the SMILEs of the molecule or a rdkit Mol object.

  • identifier_type (str, optional) – Identifier type of the molecule. Use “name” if you are providing the molecules’ name, “smiles” if you are providing the SMILES or “mol” if you are providing a rdkir mol object, by default “name”

  • solver (ILPSolver, optional) – ILP solver class, by default DefaultSolver

  • search_multiple_solutions (bool, optional) – Whether search for multiple solutions or not, by default False If False the return will be a FragmentationResult object, if True the return will be a list of FragmentationResult objects.

  • search_nonoptimal (bool, optional) – If True, the solver will search for non-optimal solutions along with the optimal ones. This is useful when the user wants to find all possible combinations of fragments that cover the universe. By default False. If search_multiple_solutions is False, this parameter will be ignored.

  • solver_arguments (dict, optional) – Dictionary with the arguments to be passed to the solver. For the DefaultSolver of ugropy you can change de PulP solver passing a dictionary like {“solver”: “PULP_CBC_CMD”} and change the PulP solver. If empty it will use the default solver arguments, by default {}.

Returns:

Fragmentation result. If search_multiple_solutions is False the return will be a FragmentationResult object, if True the return will be a list of FragmentationResult objects.

Return type:

Union[GibbsFragmentationResult, List[GibbsFragmentationResult]]

filter_bigger_polyatomics(solutions: List[GibbsFragmentationResult], criteria: str = 'Q') → List[GibbsFragmentationResult][source]

Filter multiple solutions based on the R or Q values of the groups.

The method analyzes all provided solutions and filters them according to the cumulative contribution of the R or Q values of their polyatomic groups. The returned solutions are those with the maximum sum of the selected R or Q parameter weighted by the occurrence of each polyatomic group. The user can choose to filter based on either R or Q values by setting the criteria parameter to “R” or “Q”, respectively. The solution with bigger polyatomics occurrences (R or Q) will be selected.

Parameters:

  • solutions (List[GibbsFragmentationResult]) – List of Gibbs fragmentation results to filter.

  • criteria ({"R", "Q"}, optional) – The criteria to use for filtering, either “R” or “Q”, by default “Q”

Returns:

Filtered list of Gibbs fragmentation results.

Return type:

List[GibbsFragmentationResult]

Raises:

ValueError – If criteria is not “R” or “Q”.

filter_polarity_contribution(solutions: List[GibbsFragmentationResult], criteria: str = 'Q', polarity: str = 'polar') → List[GibbsFragmentationResult][source]

Filter solutions based on R or Q and desired polarity.

Filter solutions according to the cumulative R or Q contribution of polar or nonpolar groups.

The method analyzes all provided solutions and computes the cumulative contribution of the selected UNIFAC parameter (R or Q) over groups classified according to their polarity. A group is considered polar if its SMARTS pattern contains at least one of the following atoms:

{“O”, “N”, “S”, “P”, “F”, “Cl”, “Br”, “I”}.

For each solution, the selected parameter is multiplied by the occurrence of each matching group and summed over all groups satisfying the selected polarity criterion. The solutions with the maximum cumulative contribution are returned.

Parameters:

  • solutions (List[GibbsFragmentationResult]) – List of Gibbs fragmentation results to filter.

  • criteria ({"R", "Q"}, optional) – UNIFAC parameter used to compute the contribution score, by default “Q”.

  • polarity ({"polar", "apolar"}, optional) – Type of groups to consider during filtering, by default “polar”.

Returns:

Solutions with the maximum cumulative contribution of the selected parameter for the selected polarity type.

Return type:

List[GibbsFragmentationResult]

Raises:

  • ValueError – If criteria is not “R” or “Q”.

  • ValueError – If polarity is not “polar” or “nonpolar”.