molsysmt.physchem.get_sasa#

molsysmt.physchem.get_sasa(molecular_system, element='atom', selection='all', structure_indices='all', syntax='MolSysMT', engine='MolSysMT', probe_radius='1.4 angstroms', n_sphere_points=240, use_cell_list='auto', use_gpu=None, gpu_backend=None, parallel=None, num_threads=None, skip_digestion=False)[source]#

Solvent-accessible surface area (SASA) per atom or residue group.

Uses the Shrake–Rupley rolling-sphere algorithm. The default engine computes SASA with the bundled Rust kernels.

Parameters:

  • molecular_system (molecular system) – Input system in any supported form.

  • element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity'}, default 'atom') – Hierarchical element over which SASA is accumulated. When element='atom', the raw per-atom SASA is returned. For any other element, per-atom values are summed within each element.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Selection of elements to return. The full system is always used for the SASA calculation; this parameter only filters the output.

  • structure_indices ('all' or array-like, default 'all') – Structures/frames to include.

  • syntax (str, default 'MolSysMT') – Selection syntax.

  • engine ({'MolSysMT', 'MDTraj'}, default 'MolSysMT') – Backend used for the SASA calculation.

  • probe_radius (quantity or str, default '1.4 angstroms') – Radius of the rolling solvent probe as a unit-aware length quantity (e.g. puw.quantity(1.4, 'angstroms') or '0.14 nm'). The default is the standard water-probe radius of 1.4 Å. Both the 'MolSysMT' and 'MDTraj' engines honour it.

  • n_sphere_points (int, default 240) – Number of points of the Shrake–Rupley test sphere used to sample each atom’s surface. More points reduce the angular quantization error at a proportional cost (the occlusion cost scales linearly with this number). The default of 240 is a balance between FreeSASA’s default of 100 (faster, ~1–2% error) and MDTraj’s default of 960 (slower, <0.5% error); both engines use this value so their results agree closely.

  • use_cell_list (bool or 'auto', default 'auto') – Only for the native 'MolSysMT' CPU path. When enabled, the O(N²) occlusion scan is restricted to a cell-list of candidate neighbours, reducing the per-frame cost to roughly O(N) for large systems with numerically identical results. 'auto' enables it above CELL_LIST_MIN_ATOMS atoms, where the neighbour-list build pays off. Ignored by the GPU kernels and the 'MDTraj' engine.

  • use_gpu (bool or 'auto' or None, default None) – Whether to run calculation on GPU.

  • gpu_backend ({'cuda', 'taichi'} or None, default None) – The preferred GPU framework to execute calculations on.

  • parallel (bool or str, optional) – Parallel mode override: True | False | ‘auto’.

  • num_threads (int, optional) – Number of threads override.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

SASA values as a PyUnitWizard quantity in area units (nm²). Shape: (n_structures, n_elements).

Return type:

quantity

Raises:

NotImplementedMethodError – If an unsupported engine is requested.

Notes

Non-protein atoms (e.g. solvent) are included in the SASA calculation but their contribution to neighbouring atoms is accounted for.

Added in version 1.0.0.

On this page