molsysmt.basic.convert#

molsysmt.basic.convert(molecular_system, to_form='molsysmt.MolSys', selection='all', structure_indices='all', syntax='MolSysMT', strict=False, return_report=False, skip_digestion=False, **kwargs)[source]#

Converting a molecular system into another form or set of forms.

This function converts a molecular system from its current form into one target form, or into multiple target forms. Optionally, a subset of atoms and/or structures can be selected using selection and structure_indices before the conversion takes place.

Parameters:

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

  • to_form (str, list of str, or None, default='molsysmt.MolSys') – Target form or forms for the conversion output.

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

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

  • strict (bool, default=False) – Whether conversion warnings and fidelity losses are promoted to errors.

  • return_report (bool, default=False) – Whether to return the conversion report together with the converted system.

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

Returns:

The converted molecular system in the requested to_form. If to_form is a list, a list of converted systems is returned. With return_report=True, returns (output, report) or (outputs, reports) for multiple targets.

Return type:

molecular system or list of molecular systems or tuple

Raises:

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

  • NotCompatibleConversionError – If strict=True and the preflight classifies the conversion as lossy.

  • ArgumentError – If any input argument is invalid or inconsistent, including an out-of-range structure index.

Notes

  • Supported molecular-system forms are summarized in Items and Forms.

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

  • Explicit structure indices are validated before a conversion adapter is called.

  • Reports classify semantics only within their audited_scopes. Inspect is_exhaustive before treating an equivalent outcome as a claim about the complete represented source state. Strict lossy conversions are rejected before target creation.

  • Missing source information is not a loss. A report issue is created only for an attribute available on the source instance or for an audited adapter limitation.

  • Ordinary conversions do not construct a preflight report. This keeps the reporting layer opt-in when neither strict nor return_report is used.

  • Converting to file:h5msm writes H5MSM 0.5. Legacy 0.3 and 0.4 files remain readable and can be migrated with molsysmt.h5msm.migrate_to_05().

  • A native ChemicalStates (or ChemicalStatesDict) and Structures pair can compose a topology-free MolSys, in either item order. Supplying the pair declares that their atom indices correspond; full axis counts must agree. Atom and structure index selections remap the two domains together. The reference chemical state is preserved, but multiple states acquire no inferred per-structure assignment. The default result is independent; copy_if_all=False shares native domains only for full-axis conversion.

  • Complementary partial MolSys objects or H5MSM 0.5 files are composed before selections. Supplying their list declares positional atom and structure correspondence; matching counts do not establish origin. Each topology, chemistry and Structures domain must have one provider; interaction names must be distinct and full axes must agree. Missing domains and unknown structure-to-state assignments stay absent/unknown. The default output is independent. Topology is always copied for its single-owner contract, even with copy_if_all=False. This route loads stored arrays and rejects molecular mechanics rather than discarding it.

See also

molsysmt.basic.select()

Select elements of a molecular system.

molsysmt.basic.get_form()

Retrieve the form of a molecular system.

molsysmt.basic.extract()

Extract a subset of a molecular system.

Examples

>>> import molsysmt as msm
>>> molsys_A = msm.systems['T4 lysozyme L99A']['181l.bcif.gz']
>>> msm.get_form(molsys_A)
'file:bcif.gz'
>>> molsys_B = msm.convert(molsys_A, to_form='molsysmt.MolSys')
>>> msm.get_form(molsys_B)
'molsysmt.MolSys'
>>> _, report = msm.convert(molsys_B, to_form='molsysmt.Topology', return_report=True)
>>> report.outcome in {'exact', 'equivalent', 'lossy'}
True

Composing separately held chemical and structural domains:

>>> import numpy as np
>>> from molsysmt.native import ChemicalStates, Structures
>>> states = ChemicalStates(n_atoms=2)
>>> states.append_state()
0
>>> structures = Structures()
>>> structures.append(coordinates=msm.pyunitwizard.quantity(np.zeros((1, 2, 3)), 'nm'))
>>> partial = msm.convert([states, structures], selection=[1, 0])
>>> partial.topology is None
True
>>> msm.get(partial, n_atoms=True, n_structures=True)
[2, 1]

Tutorial with more examples

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

Added in version 1.0.0.

On this page