Metadata-Version: 2.5
Name: syzygy-chem
Version: 2026.1.1
Summary: A Python ecosystem for computational chemistry.
Author-email: Mitul Al Salin <mitulalsalin@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# 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:

```bash
conda activate vina
vina --version
```

a researcher can use:

```bash
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:

```bash
syzygy software detect vina
```

can identify an available Vina installation and its environment.

Execution can then be performed through:

```bash
syzygy software run vina -- --version
```

or through the shorter launcher:

```bash
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:

```bash
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:

```bash
szg.vina --help
```

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

```text
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:

```python
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:

```python
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:

```text
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:

```text
                              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:

```bash
python -m pip install syzygy-chem
```

Verify the installation:

```bash
syzygy --version
```

Example:

```text
syzygy, version 2026.1.1
```

A registered software launcher can then be used directly:

```bash
szg.vina --version
```

---

# Development

Clone the repository:

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

Install the project in editable mode:

```bash
python -m pip install -e .
```

Build the distribution:

```bash
python -m build
```

The resulting source distribution and wheel are written to:

```text
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`](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.
