molsysmt.basic.compare#

molsysmt.basic.compare(molecular_system, molecular_system_2, selection='all', structure_indices='all', selection_2='all', structure_indices_2='all', syntax='MolSysMT', rule='equal', output_type='boolean', attribute_type=None, include_none=False, redefine_indices=False, skip_digestion=False, **kwargs)[source]#

Comparing two molecular systems or selected subsets of them.

This function compares attributes of two molecular systems (or their selected subsets) using either equality ('equal') or containment ('in') rules. The scope of the comparison can be restricted with selection/structure_indices for the first system, and selection_2/structure_indices_2 for the second.

If no explicit attributes are provided via keyword arguments, a default set of attributes (or those filtered by attribute_type) is considered.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • molecular_system_2 (molecular system) – Second molecular system to compare with the first one.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • selection_2 (str, list, tuple, or numpy.ndarray, default='all') – Second selection string or boolean/integer array.

  • structure_indices_2 (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) for the second selection.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • rule ({'equal', 'in'}, default='equal') – Comparison rule applied to the requested attributes.

  • output_type (str, default='boolean') – Representation used for the returned result.

  • attribute_type (str or None, default=None) – Attribute category used to filter the comparison or result.

  • include_none (bool, default=False) – Whether to include attributes whose value is None.

  • redefine_indices (bool, default=False) – Whether to reassign contiguous 0-based indices.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

Returns:

True/False when output_type=’boolean’, or a dictionary mapping attribute names to booleans when output_type=’dictionary’.

Return type:

bool or dict

Raises:

  • NotSupportedFormError – If any molecular system is provided in an unsupported form.

  • ArgumentError – If arguments are inconsistent or invalid.

Notes

  • Supported forms are summarized in Items and Forms.

  • Selection syntaxes are described in Selection syntaxes.

  • Differences in array shapes or collection sizes are ordinary inequality results. They return False for the affected attribute without emitting a warning.

  • Matching missing metadata entries compare equal, including numeric NaN values. A missing entry and a populated entry compare unequal.

  • Backward compatibility: the alias attributes_type is accepted and normalized internally to attribute_type.

See also

molsysmt.basic.select()

Select elements of a molecular system.

molsysmt.get()

Retrieve attribute values.

molsysmt.info()

Display a concise system summary.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> A = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> B = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'], selection='molecule_type=="protein"')
>>> msm.compare(A, B)
False
>>> msm.compare(A, B, box=True)
True
>>> msm.compare(A, B, n_groups=False)
True
>>> msm.compare(A, B, selection='molecule_type=="protein"', n_groups=True)
True

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Compare.

Added in version 1.0.0.

On this page