molsysmt.basic.extract#

molsysmt.basic.extract(molecular_system, selection='all', structure_indices='all', to_form=None, output_filename=None, copy_if_all=True, syntax='MolSysMT', skip_digestion=False)[source]#

Extracting a subset of atoms and/or structures from a molecular system.

This function creates a new molecular system containing only the elements and structures specified by selection and structure_indices. Optionally, the result can be returned in another form using to_form.

Parameters:

  • molecular_system (molecular system) – Molecular system to extract from, in any of the supported forms.

  • selection (str, tuple, list or numpy.ndarray, default 'all') – Subset of atoms to extract. Either a 0-based index collection or a selection string parsed according to Selection syntaxes. The default ‘all’ selects all atoms.

  • structure_indices (int, tuple, list, numpy.ndarray or 'all', default 'all') – 0-based indices of the structures to extract. The default ‘all’ includes all structures.

  • to_form (str or None, default None) – Target form of the output system. If None, the output form matches the input system. See Supported conversions.

  • output_filename (str or None, optional) – Optional output target used by certain form handlers. When applicable, the underlying conversion/extraction backend may write to this location.

  • copy_if_all (bool, default True) – If both selection and structure_indices equal ‘all’: * True: return an independent copy of the system. * False: return a view/reference to the original data, if the backend supports it.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string. See Selection syntaxes.

  • 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.

Returns:

A new molecular system containing only the selected atoms and structures, in to_form if provided, otherwise in the input form.

Return type:

molecular system

Raises:

  • NotSupportedFormError – If the input or requested output form is not supported.

  • ArgumentError – If input arguments are invalid or inconsistent.

Notes

  • Supported molecular-system forms are summarized in Forms.

  • Selection strings must follow one of the syntaxes described in Selection syntaxes.

See also

molsysmt.basic.select()

Select elements from a molecular system without extracting them.

molsysmt.basic.copy()

Create an independent copy of a molecular system.

molsysmt.basic.convert()

Convert a molecular system into a different form.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['T4 lysozyme L99A']['181l.h5msm'])
>>> molsys_B = msm.extract(molsys_A, selection='molecule_type=="protein"')
>>> msm.contains(molsys_A, waters=True)
True
>>> msm.contains(molsys_B, waters=True)
False

Tutorial with more examples

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

Added in version 1.0.0.

On this page