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, 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) – First molecular system to compare. Accepted in any of the supported forms.

  • molecular_system_2 (molecular system) – Second molecular system to compare. Accepted in any of the supported forms.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Elements to include from the first system. Either a selection string following the supported syntaxes or a 0-based sequence of atom indices.

  • structure_indices (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of structures to include from the first system.

  • selection_2 (str, list, tuple or numpy.ndarray, default 'all') – Elements to include from the second system. Same semantics as selection.

  • structure_indices_2 (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of structures to include from the second system.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection/selection_2 are strings. See Selection syntaxes.

  • rule ({'equal', 'in'}, default 'equal') – Comparison rule: * 'equal' — checks that values are numerically or exactly identical (see Notes). * 'in' — checks that values from the first system are contained in the second

  • output_type ({'boolean', 'dictionary'}, default 'boolean') – Output format: * 'boolean' — a single True/False indicating overall success. * 'dictionary' — a per-attribute dictionary with individual results.

  • attribute_type ({'topological', 'structural', 'mechanical', 'all', None}, default None) – Attribute subset to compare. If None, attributes specified in **kwargs are used (if any). Otherwise, a default list for the given subset is applied.

  • include_none (bool, default False) – Whether to include attributes with None values when inferring comparable attributes.

  • skip_digestion (bool, default False) –

    Whether to skip MolSysMT’s internal argument digestion mechanism.

    MolSysMT includes a built-in digestion system that validates and normalizes function arguments. This process checks types, shapes, and values, and automatically adjusts them when possible to meet expected formats.

    Setting skip_digestion=True disables this process, which may improve performance in workflows where inputs are already validated. Use with caution: only set this to True if you are certain all input arguments are correct and consistent.

  • **kwargs – Attribute names to compare as keyword booleans indicating the expected outcome under rule: * True — the rule should hold (e.g., equality expected). * False — the negation should hold (e.g., inequality expected).

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

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