Installation¶

Prerequisites¶

Requirement	Details
Operating System	Linux or macOS
Windows	WSL2 with Ubuntu required (see below)
Python	3.9 or higher
Git	Any recent version
RAM	4 GB minimum
Disk	~500 MB (including virtual environment)

Step 1 — Windows Users: Install WSL2¶

Skip this step if you are on Linux or macOS.

Open PowerShell as Administrator and run:
```
wsl --install -d Ubuntu
```
Restart your computer
After restart, Ubuntu opens — create a username and password
Continue all remaining steps inside the Ubuntu terminal

Step 2 — Clone the Repository¶

git clone https://github.com/DanaResearchGroup/AdsPro.git
cd AdsPro

Step 3 — Run the Install Script¶

chmod +x install.sh
./install.sh

The script will:

Detect your OS (Linux, WSL, macOS)
Install system dependencies (python3, git) if missing
Create a Python virtual environment at ~/adspro-venv
Install all Python packages (numpy, scipy, biopython, pyyaml, pytest)
Install AdsPro in editable mode (pip install -e .)
Run the full test suite to verify the installation

A successful install ends with:

╔══════════════════════════════╗
║  AdsPro Installation Complete ║
╚══════════════════════════════╝

Step 4 — Activate the Environment¶

Before every session, activate the virtual environment:

source ~/adspro-venv/bin/activate

You will see (adspro-venv) at the start of your prompt.

Step 5 — Verify¶

python3 -m pytest tests/ -q

Expected output:

95 passed in X.Xs

Manual Installation¶

If you prefer to install into an existing environment:

python3 -m venv ~/adspro-venv
source ~/adspro-venv/bin/activate

pip install -r requirements.txt
pip install -e .

python3 -m pytest tests/ -q

Directory Structure After Installation¶

AdsPro/
├── adspro/               # Python package (source code)
│   ├── __main__.py       # CLI entry point
│   ├── config_manager.py
│   ├── grainer.py        # Coarse-graining (one bead per residue)
│   ├── surface_builder.py
│   ├── physics_engine.py
│   ├── energy_calculator.py
│   ├── bond_detector.py
│   ├── orientation_sampler.py
│   ├── pmf_calculator.py
│   ├── runner.py
│   ├── reporter.py
│   ├── validator.py
│   └── visualizer.py
├── data/                 # Force-field and amino acid parameter files
│   └── aa_parameters/
│       ├── aa_surface_energies.json    # Morse ε per residue (silica)
│       ├── aa_vdw_radii.json
│       ├── aa_masses.json
│       ├── aa_pka_values.json
│       └── SOURCES.md                 # Full bibliography
├── input/                # Your simulation input folders
├── projects/             # Simulation outputs (auto-created)
├── tests/                # Test suite (95 tests)
├── install.sh
├── requirements.txt
└── pyproject.toml

Troubleshooting¶

`ModuleNotFoundError: No module named 'Bio'`¶

pip install biopython

`python` not found (only `python3`)¶

Use python3 -m adspro instead of python -m adspro.

Permission denied on install.sh¶

chmod +x install.sh
./install.sh

PDB file parsing errors¶

Make sure your PDB file contains standard ATOM records. Files from AlphaFold work well. Avoid files with only HETATM records.

Tests fail after re-install¶

Re-run pip install -e . to make sure the installed package reflects your local source.

Uninstallation¶

rm -rf ~/adspro-venv
cd ..
rm -rf AdsPro