SQQ: Python Joint Toolkit for Water-Shell Topology Analysis

Abstract

Order parameters are essential for molecular dynamics structures of crystalline water, as they provide quantitative measures of phase change. Yet conventional descriptors cannot directly resolve water-ring connectivity, face adjacency, or cage closure. Here, we develop the Graph-guided Ring Overlap Workflow (GROW) algorithm and its open-source implementation, Shell Quant Qualifier (SQQ), to connect molecular coordinates with cage and phase topology. SQQ constructs hydrogen-bond or oxygen–oxygen water graphs, identifies chordless rings as faces, and reconstructs cages by expanding connected face sets along exposed edges. Since GROW tests branches without predefining the final face arrangement, it can distinguish standard cages, uncommon cage compositions, and isomers that share the same face counts. SQQ maps cage occupancy, face-sharing clusters, hydrate domains, and phase boundaries while preserving the molecular identities behind each result. Tests on standard, perturbed, and periodically translated sI, sII, and sH crystals recover the expected network edges, cage types, and cage–water assignments. Comparisons on a hydrate-growth trajectory show close population agreement with GRADE and TRACE when graph definitions and ring ranges are aligned, while examples explain differences caused by recognition rules. In the benchmark, SQQ completed the system containing more than one million waters within 3 min. Through its Python and C++ engine, SQQ provides an end-to-end workflow for multiframe cage detection, phase analysis, visualization, and traceable structural reporting.