# SPDX-License-Identifier: LGPL-3.0-or-later
# Copyright 2018-2022, East China Normal University
"""ReacNetGenerator is an automatic reaction network generator for
reactive molecular dynamics simulation.[1]_.
References
----------
.. [1] Jinzhe Zeng, Liqun Cao, Chih-Hao Chin, Haisheng Ren, John Z. H.
Zhang, Tong Zhu, ReacNetGenerator: an automatic reaction network
generator for reactive molecular dynamic simulations, Phys. Chem.
Chem. Phys., 2020, 22 (2): 683-691, doi: 10.1039/C9CP05091D.
"""
__date__ = "2018-03-11"
__author__ = "Jinzhe Zeng"
__email__ = "jinzhe.zeng@ustc.edu.cn"
__credits__ = ["Jinzhe Zeng", "Tong Zhu", "Liqun Cao", "Chih-Hao Chin", "John ZH Zhang"]
__copyright__ = (
"Copyright 2018-2024, East China Normal University; Copyright 2024, DeepModeling"
)
from typing import TYPE_CHECKING
from ._version import __version__
[docs]
class ReacNetGenerator:
"""Factory class for :class:`reacnetgenerator.reacnetgen.ReacNetGenerator`."""
def __new__(cls, *args, **kwargs):
"""Create a new ReacNetGenerator instance."""
from .reacnetgen import ReacNetGenerator as RealRNG
return RealRNG(*args, **kwargs)
if TYPE_CHECKING:
from .reacnetgen import ReacNetGenerator
[docs]
def run(
*,
input_path,
input_type,
atomname,
output_dir=None,
items=("species", "reactions", "network", "report"),
**kwargs,
):
"""Run ReacNetGenerator and return artifacts with parameter provenance.
Parameters
----------
input_path : str or pathlib.Path or sequence
Input trajectory or bond file(s).
output_dir : str or pathlib.Path
Directory receiving all default-generated artifacts.
input_type : str
ReacNetGenerator input type, such as "dump" or "bond".
atomname : sequence of str
Element names in the input trajectory.
items : sequence of str, optional
Requested stages. "species" and "reactions" are produced by
the core run; "network" and "report" control the optional
drawing/report stages.
**kwargs
Additional arguments forwarded to ReacNetGenerator.
Returns
-------
dict
``artifacts`` maps semantic names to output path strings.
``provenance`` contains the JSON-serializable normalized parameters,
explicitly supplied parameter names, and requested items.
"""
if isinstance(items, str):
items = (items,)
requested = set(items)
allowed = {"species", "reactions", "network", "report"}
unknown = requested - allowed
if unknown:
raise ValueError(f"Unsupported output items: {sorted(unknown)}")
if not requested:
raise ValueError("items must contain at least one output stage")
from .reacnetgen import ReacNetGenerator as RealRNG
generator_kwargs = dict(
inputfilename=input_path,
inputfiletype=input_type,
atomname=atomname,
**kwargs,
)
if output_dir is not None:
generator_kwargs["output_dir"] = output_dir
generator = RealRNG(**generator_kwargs)
artifacts = generator.runanddraw(
run=True,
draw="network" in requested or "report" in requested,
report="report" in requested,
)
provenance = generator.parameter_provenance()
provenance["items"] = list(items)
return {"artifacts": artifacts, "provenance": provenance}
__all__ = ["ReacNetGenerator", "__version__", "run"]
