Examples

This page showcases common usage patterns with slurptuna.

Distributed_Argv_Example

See run_distributed_argv_example.py in the repository.

Shared Fitting Across Participants

Fit shared alpha/beta across participants by averaging losses

Use Case

When you want one set of parameters that works well for all participants, measuring success as the average loss across participants.

Single Mode (Local)

# LOCAL / single-mode run:
    # result = optimize_run(
    #     participant_average_demo,
    #     mode=execution_mode("single"),
    #     n_trials=20,
    #     n_seeds=200,
    # )

Distributed Mode (Slurm Arrays)

# DISTRIBUTED run with explicit seed/chunk controls:
    result = optimize_run(
        participant_average_demo,
        mode=execution_mode("distributed"),
        n_trials=20,
        n_seeds=800,      # total seeds evaluated per trial
        chunk_size=40,    # seeds handled by each array task
        worker_time_limit=timedelta(minutes=30),
        # num_chunks is optional; if omitted it is derived from n_seeds/chunk_size
        # num_chunks=20,
    )

    print("best value:", result.best_value)
    print("best params:", result.best_params)
    print("run dir:", result.run_dir)

See run_participant_average.py in the repository.

Participant_From_Csv

Fit one alpha/beta set per participant loaded from CSV

Single Mode (Local)

# LOCAL / single-mode example.
    # result = optimize_entries(
    #     participant_from_csv_demo,
    #     entry_ids=PARTICIPANTS.keys(),
    #     mode=execution_mode("single"),
    #     n_trials=20,
    #     n_seeds=200,
    #     run_name_prefix="participant_from_csv_single",
    # )

Distributed Mode (Slurm Arrays)

# DISTRIBUTED example.
    result = optimize_entries(
        participant_from_csv_demo,
        entry_ids=PARTICIPANTS.keys(),
        mode=execution_mode("distributed"),
        n_trials=4,
        n_seeds=80,
        chunk_size=20,
        run_name_prefix="participant_from_csv_distributed",
        max_concurrent_entries=4,
        max_concurrent_trials=2,
        worker_parallelism=2,
        cpus_per_task=2,
        worker_time_limit=timedelta(minutes=30),
    )

    print("mode:", result.mode.value)
    print("best params by participant:")
    for pid in result.entries:
        print(pid, result.best_params_by_entry[pid])

See run_participant_from_csv.py in the repository.

Participant-wise Fitting

Fit participant-wise: separate optimization per participant

Use Case

When participants have different characteristics and you want individualized parameters for each (e.g., personalized model fits in psychology or medicine).

Single Mode (Local)

# LOCAL / single-mode example.
    # result = optimize_entries(
    #     participant_individual_demo,
    #     entry_ids=PARTICIPANTS.keys(),
    #     mode=execution_mode("single"),
    #     n_trials=20,
    #     n_seeds=200,
    #     run_name_prefix="participant_individual_single",
    # )

Distributed Mode (Slurm Arrays)

# DISTRIBUTED example (one study per participant, each using Slurm chunk arrays).
    result = optimize_entries(
        participant_individual_demo,
        entry_ids=PARTICIPANTS.keys(),
        mode=execution_mode("distributed"),
        n_trials=6,
        n_seeds=120,
        chunk_size=20,
        run_name_prefix="participant_individual_distributed",
        max_concurrent_entries=4,
        max_concurrent_trials=2,
        worker_parallelism=2,
        cpus_per_task=2,
        worker_time_limit=timedelta(minutes=30),
    )

    print("mode:", result.mode.value)
    print("best params by participant:")
    for pid, params in result.best_params_by_entry.items():
        print(pid, params)

See run_participant_individual.py in the repository.

Basic Optimization (Toy Loss)

Recover two parameters

Single Mode (Local)

# LOCAL / single-mode example.
    # result = optimize_run(
    #     my_model,
    #     mode=execution_mode("single"),
    #     n_trials=20,
    #     n_seeds=200,
    #     run_name="toy_single_local",
    # )

Distributed Mode (Slurm Arrays)

# DISTRIBUTED example (Slurm array + reduce jobs).
    result = optimize_run(
        my_model,
        mode=execution_mode("distributed"),
        n_trials=3,
        n_seeds=6,
        chunk_size=2,
        run_name=run_name,
        loss_module="examples.run_toy_loss",
        max_concurrent_trials=1,
        worker_parallelism=1,
        cpus_per_task=1,
        slurm_poll_seconds=2,
        slurm_timeout_minutes=5,
        worker_time_limit=timedelta(minutes=5),
        trial_retry_attempts=1,
    )

    print("mode:", result.mode.value)
    print("true  :", TRUE)
    print("found :", result.best_params)
    print("best value:", result.best_value)
    print("run dir:", result.run_dir)

See run_toy_loss.py in the repository.

Reading Results

All runs produce:

• summary.json: Best parameters and best value (updated progressively as trials complete)
• meta.json: Run configuration and metadata
• optuna.db: SQLite database with full trial history
• trials/: Individual trial directories with chunk results

Example:

import json
from pathlib import Path

run_dir = Path(result.run_dir)
summary = json.loads((run_dir / 'summary.json').read_text())
print(f'Best value: {summary["best_value"]}')
print(f'Best params: {summary["best_params"]}')

More Information

For details on distributed execution with Slurm, see Distributed Mode.