Tactical Scheduling

A Python library for optimizing chemical reaction scheduling on automated synthesis platforms. This tool clusters reactions and optimizes temperature and duration parameters to minimize the number of experimental batches while respecting container and volume constraints.

Features

• Reaction Clustering: Intelligently groups reactions based on chemical compatibility and resource constraints
• Parameter Optimization: Automatically selects optimal temperature and duration for each cluster
• Resource Management: Respects container capacity limits for substrates, solutions, solvents, and powders
• Volume Constraints: Handles maximum volume per slot for each container type
• Batch Minimization: Reduces the number of experimental runs needed

Requirements

• Python 3.12 or higher
• uv package manager (install uv)

Installation

1. Install uv (if not already installed)

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository

git clone https://github.com/iktos/tactical-scheduling.git
cd tactical-scheduling

3. Set up the project with uv

# Create a virtual environment and install dependencies
uv sync

This command will:

• Create a virtual environment
• Install all project dependencies (pulp, pandas, numpy, ipykernel)
• Set up the package in development mode

Quick Start

Running the Web Interface

The easiest way to use the scheduler is through the Streamlit web interface:

# Start the Streamlit app
uv run streamlit run app.py

The app will open in your browser at http://localhost:8501. You can:

• Upload your reaction data as JSON
• Configure optimization parameters
• Run the optimization (may take 1-2 minutes for large datasets)
• View and export results

Note: The optimization uses an integer linear programming solver that can take several minutes to complete. The app will display a progress message while solving. The solver has a 5-minute timeout to prevent indefinite hanging.

Running the Example Notebook

The project includes a Jupyter notebook example demonstrating the scheduling optimization:

# Start Jupyter with the example notebook
uv run jupyter notebook example/test_tactical_schedule.ipynb

Basic Usage

from iktos.tactical_scheduling import run_tactical

# Prepare your reactions and configuration
reactions = [...]  # List of reaction dictionaries
config = {
    "containers": [...],  # Container specifications
    "config": {
        "actions": {
            "dispenseSolvent": {"extraVolume": 10},
            "dispenseSolution": {"extraVolume": 5},
            "dispensePowder": {"extraWeight": 0.1},
        }
    }
}

# Run the optimization
clusters = run_tactical(reactions, config)

# Process results
for (pair, cluster_id), reactions_in_cluster in clusters.items():
    print(f"Pair {pair}, Cluster {cluster_id}: {len(reactions_in_cluster)} reactions")

Configuration

The config parameter should include:

• containers: List of container specifications with:

  • type: Container type (SUBSTRATE, SOLUTION, SOLVENT, POWDER)
  • slots: Number of available slots
  • maxVolumePerSlot: Maximum volume per slot

• config.actions: Extra volume/weight parameters for each dispense action

Project Structure

tactical-scheduling/
├── iktos/
│   └── tactical_scheduling/
│       ├── tactical_schedule.py    # Main scheduling function
│       └── utils.py                # Optimization utilities
├── example/
│   ├── test_tactical_schedule.ipynb # Example notebook
│   └── data/                        # Example data files
├── pyproject.toml                  # Project configuration
└── README.md                       # This file

Development

Running Tests

# Run the example notebook
uv run jupyter notebook example/test_tactical_schedule.ipynb

Dependencies

• pulp: Linear programming solver for optimization
• pandas: Data manipulation and analysis
• numpy: Numerical computing
• ipykernel: Jupyter kernel for interactive notebooks
• streamlit: Web interface framework for interactive applications

Citation

If you use this project in your research, please cite it appropriately.

Support

For issues, questions, or contributions, please contact the development team or open an issue in the repository.

Disclaimer

This source code project is provided as an example for educational and illustrative purposes only. While efforts have been made to ensure the accuracy and reliability of the code, no guarantee is made regarding its suitability for any specific purpose.

By accessing and using this source code, you agree that:

1. The code is provided "as is" without warranty of any kind, express or implied.
2. You acknowledge that you are solely responsible for any consequences resulting from the use of this code.
3. The author(s) and contributors of this code shall not be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) arising in any way out of the use of this code, even if advised of the possibility of such damage.
4. Copyright © 2025 Iktos. All rights reserved.

This disclaimer does not limit or exclude any liability for death or personal injury resulting from negligence, fraud, or any other liability that cannot be excluded or limited under applicable law.

Use of this source code project implies acceptance of these terms.