SYZYGY

A Python-native infrastructure layer for computational chemistry.

SYZYGY is an open-source Python ecosystem designed to provide a common interface to computational chemistry software, execution environments, installation systems, scientific databases, projects, and HPC infrastructure.

Rather than replacing existing scientific software or imposing a predefined workflow, SYZYGY provides the infrastructure required to discover, connect, and execute heterogeneous computational tools through a consistent interface.

---

The Problem

Computational chemistry rarely depends on a single program.

A practical research workflow may combine molecular docking, structure preparation, cheminformatics, molecular dynamics, quantum chemistry, visualization, and database resources. These tools are often distributed through different package managers and installed into different environments.

As a result, the computational layer of a research project can become tightly coupled to:

• environment activation
• executable locations
• package managers
• platform-specific conventions
• installation methods
• HPC module systems
• individual software interfaces

SYZYGY introduces an abstraction layer between the researcher and this infrastructure.

For example, instead of explicitly managing the environment containing a program:

conda activate vina
vina --version

a researcher can use:

szg.vina --version

SYZYGY resolves the registered software and its available installation and delegates execution to the underlying program.

The scientific software itself remains unchanged.

---

Design Principles

SYZYGY is built around a small number of architectural principles.

Software remains independent

SYZYGY does not attempt to replace or reimplement established computational chemistry software.

It provides a common infrastructure layer around existing tools.

Workflows remain user-defined

SYZYGY does not impose a mandatory docking, molecular dynamics, quantum chemistry, or analysis workflow.

Researchers remain free to combine tools according to their own methodology.

Environment details remain below the interface

Software may be installed in Conda, Python, virtual environments, Homebrew, Spack, system locations, containers, Java environments, or HPC infrastructures.

The execution layer should not need to know how an environment was created in order to use it.

Components remain replaceable

Environment discovery, software metadata, installation, execution, databases, projects, and HPC integration are separated into distinct layers.

New implementations should be able to extend the ecosystem without requiring changes to unrelated components.

---

What SYZYGY Provides

Layer	Purpose
Environment	Discover and represent execution environments
Software	Describe, detect, resolve, and execute scientific software
Installation	Integrate software installation mechanisms
Databases	Provide programmatic access to scientific data resources
Projects	Provide a consistent computational project structure
HPC	Represent clusters, resources, environments, jobs, and schedulers

These components are designed to operate independently while sharing common abstractions.

---

Software Execution

Software is represented through metadata rather than hard-coded execution logic.

A software definition may describe:

• executable
• Python package
• runtime dependencies
• version command
• version pattern
• aliases
• capabilities
• installation providers

For example:

syzygy software detect vina

can identify an available Vina installation and its environment.

Execution can then be performed through:

syzygy software run vina -- --version

or through the shorter launcher:

szg.vina --version

Both ultimately execute the underlying software rather than providing a separate implementation of it.

---

szg.<software>

SYZYGY can generate command launchers for registered software.

Examples:

szg.vina
szg.obabel
szg.psi4
szg.prank
szg.pymol

The launcher is intentionally thin.

Its responsibility is to identify the requested software and delegate execution to SYZYGY's software resolution layer.

For example:

szg.vina --help

is conceptually equivalent to asking SYZYGY to locate the appropriate Vina installation and execute:

vina --help

This allows the underlying installation to remain in its original environment.

---

Environment Abstraction

Environment discovery is independent of software detection.

SYZYGY currently provides representations for environments including:

• Conda
• Python
• virtual environments
• Homebrew
• Spack
• Docker
• Java
• system environments
• HPC/module-based environments

An environment is represented through a common model containing information such as:

• name
• prefix
• environment kind
• manager
• executable paths
• capabilities
• metadata

This allows higher-level components to operate on environments without embedding provider-specific assumptions.

---

Python API

SYZYGY is designed as a Python ecosystem first, with the CLI acting as one interface to the underlying API.

Software can be inspected programmatically:

import syzygy

vina = syzygy.tools.get("vina")

installation = syzygy.tools.detector.detect(vina)

if installation:
    print(installation.version)
    print(installation.path)
    print(installation.environment)

Software can also be executed through the API:

import syzygy

result = syzygy.tools.run(
    "vina",
    args=["--version"],
)

print(result.stdout)

This makes the same infrastructure available to interactive shell workflows, Python scripts, and larger computational pipelines.

---

Databases

SYZYGY provides interfaces for computational chemistry and structural biology data resources, including:

• RCSB PDB
• PubChem
• ChEMBL

The database layer is intended to provide a consistent programmatic interface without coupling the rest of the ecosystem to a particular database implementation.

---

Installation

SYZYGY separates software discovery, software installation, and software execution.

Installation providers can include:

• Conda
• pip
• Homebrew
• Spack
• source installations
• binary installations

The installation architecture is provider-oriented so that additional package managers and installation mechanisms can be integrated independently of the software registry.

---

Projects

SYZYGY can create a standardized computational project structure.

A project may contain:

Project/
├── Proteins/
├── Ligands/
├── Results/
└── Analysis/

The structure provides organization without dictating how a researcher performs the actual computation.

---

HPC

Computational chemistry frequently extends beyond a local workstation.

SYZYGY therefore includes an HPC subsystem designed to represent and interact with heterogeneous computational infrastructure.

The architecture includes abstractions for:

• clusters
• connections
• resources
• environments
• software
• installations
• execution
• jobs
• schedulers

Scheduler and environment integrations are designed as separate components so that the core model is not tied to a particular HPC implementation.

---

Architecture

At a conceptual level:

                              SYZYGY
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
   Environments              Software                Databases
        │                        │                        │
        │                  ┌─────┴─────┐                  │
        │                  │           │                  │
        │             Detection    Execution             │
        │                  │           │                  │
        └──────────────────┼───────────┼──────────────────┘
                           │           │
                      Installation   Projects
                           │           │
                           └─────┬─────┘
                                 │
                                HPC
                                 │
                   ┌─────────────┼─────────────┐
                   │             │             │
                Resources    Schedulers    Execution

The important distinction is that these are layers of infrastructure, not stages of a fixed scientific workflow.

A researcher can use one component without adopting the others.

---

Cross-Platform Design

SYZYGY is not designed exclusively around Conda.

Its environment architecture provides a common representation for different execution mechanisms and operating-system conventions.

The project is intended to operate across:

• macOS
• Linux
• Windows
• local environments
• containers
• HPC systems

Actual software availability remains dependent on whether the underlying scientific software supports the target platform and environment.

---

Installation

Install SYZYGY from PyPI:

python -m pip install syzygy-chem

Verify the installation:

syzygy --version

Example:

syzygy, version 2026.1.1

A registered software launcher can then be used directly:

szg.vina --version

---

Development

Clone the repository:

git clone https://github.com/mitulalsalin/SYZYGY.git
cd SYZYGY

Install the project in editable mode:

python -m pip install -e .

Build the distribution:

python -m build

The resulting source distribution and wheel are written to:

dist/

---

Contributing

Contributions are welcome in areas including:

• software integrations
• environment providers
• installation providers
• database interfaces
• HPC integrations
• testing
• documentation
• portability and platform support

For substantial architectural changes, opening an issue before implementation is recommended so that the proposed direction can be discussed.

---

License

SYZYGY is distributed under the license included in this repository.

See LICENSE for the complete terms.

---

Acknowledgments

SYZYGY was developed by Mitul Al Salin.

During development, OpenAI's ChatGPT was used as an AI-assisted development tool for:

• code review
• debugging
• implementation assistance
• documentation
• testing and troubleshooting
• exploration of alternative implementation approaches
• technical explanations and programming guidance

The project's architecture, design principles, implementation direction, and technical decisions were defined and made by the author.

---

Author

Mitul Al Salin

GitHub: https://github.com/mitulalsalin/SYZYGY

PyPI: https://pypi.org/project/syzygy-chem/

---

Project Status

SYZYGY is under active development.

The current architecture establishes the foundation for a broader computational chemistry ecosystem connecting scientific software, execution environments, installation systems, databases, computational projects, Python interfaces, and HPC infrastructure.

The project is being developed incrementally, with emphasis on modularity, interoperability, platform independence, and preservation of researcher control.