# PlayMolecule

PlayMolecule is a Python API for running Acellera's containerized drug-discovery apps. You install one Python package, point it at a registry of apps (a Docker registry, an HTTP backend, or a local install), and call each app as a normal Python function. Each call produces a self-contained {py:class}`~playmolecule.ExecutableDirectory` you can {py:meth}`~playmolecule.ExecutableDirectory.run` locally, submit to SLURM, or execute on a remote PlayMolecule HTTP backend.

:::{important}
The `playmolecule` Python client (this package) is freely available, but the **apps** it runs — ProteinPrepare, DeepSite, Parameterize, and the rest — are commercial products that require an Acellera licence. [Contact Acellera](https://www.acellera.com/contact-us) to book a demo and obtain a quote tailored to your needs. See [Licensing](installation.md#licensing) for details.
:::

::::{grid} 2
:gutter: 3

:::{grid-item-card} 🎓 Tutorials
:link: tutorials/index
:link-type: doc

Step-by-step lessons. Start here if you're new.
:::

:::{grid-item-card} 🛠 How-to guides
:link: howto/index
:link-type: doc

Task-focused recipes. "How do I X?"
:::

:::{grid-item-card} 📖 Reference
:link: reference/index
:link-type: doc

API, CLI, and environment variables.
:::

:::{grid-item-card} 💡 Explanation
:link: explanation/index
:link-type: doc

Concepts and mental models.
:::

::::

## Installation

```bash
pip install playmolecule
```

See [Installation](installation.md) for the rest of the setup (registry credentials, container runtime). Cluster administrators rolling out PlayMolecule for a multi-user site should read [Install apps for a cluster](howto/install-apps-for-a-cluster.md).

## Quick start

```python
from playmolecule import describe_apps
from playmolecule.apps import proteinprepare

describe_apps()                                      # list what's available
ed = proteinprepare(outdir="out", pdbid="3ptb")      # build an ExecutableDirectory
ed.run()                                             # execute locally
print(ed.status)                                     # JobStatus.COMPLETED
```

The same `ed` can be submitted to SLURM instead:

```python
ed = proteinprepare(outdir="out", pdbid="3ptb")
ed.run(queue="slurm", partition="normalCPU", ncpu=1, ngpu=0)
```

## Citing

If you use PlayMolecule in published work, please cite Acellera. See <https://www.acellera.com/playmolecule>.

```{toctree}
:maxdepth: 1
:hidden:

installation
tutorials/index
howto/index
explanation/index
reference/index
```