feature request: average across multiple samples

[ltalirz]

Our current workflow only runs a single melt-quench, producing a single glass sample.

It would be nice to have the option to run the workflow multiple times with different random seedsin order to collect statistics across different glass samples
Already n=2 would give some indication of scatter of the various computed properties

[Atilaac]

Is there a way to submit the simulations at the same time? like if we set n to 3 then 3 simulations of the same composition with different strating structures are submitted at the same time and not in serial.

[ltalirz]

Yes, of course.

This is a rather trivial feature request (to myself): we would just add something like a n_replica to the API input, submit in parallel, and then make sure to average results at the end

[ltalirz]

One may also consider in addition (or instead) a sampling of different cooling rates for extrapolation purposes.
The nice thing is that this does not cost time, just compute.

[ltalirz]

Here is a preliminary plan for how to implement this, postponing for the moment

• a /visualize that combines all the data
• more complex sampling strategies like different cooling rates, which would in effect be yet another layer on top

Plan: Add n_samples with Glass Sample Entity

A single JobSubmission with n_samples=N produces N independent glass samples, each with its own UUID, seed (1, 2, ..., N), structure, melt-quench, and analyses. Caching operates at the sample level: submitting n_samples=5 after n_samples=3 reuses the 3 cached samples (via executorlib's HDF5 caching) and only computes 2 new ones. Results endpoints accept ?sample=<sample_id> to select which sample to view (default: first).

---

Phase 1: Database Schema — New GlassSample Table

1. Add GlassSample model to database.py: sample_id (UUID PK), job_id (FK), sample_index (0-based), seed (= sample_index + 1), status, progress (JSON), result_data (JSON), errors (JSON), elemental_vector (JSON), timestamps. Unique constraint on (job_id, sample_index).
2. Update Job table: remove result_data and elemental_vector (moved to sample), add n_samples column (Integer, default=1).
3. Add JobStore methods: create_sample, get_sample, get_samples_for_job, update_sample. Update search_by_composition, list_compositions, list_completed_vectors to operate on samples.

Phase 2: Pydantic Models (parallel with Phase 1)

4. Add n_samples: int = 1 (ge=1, le=20) to JobSubmission.
5. Add SampleSummary model (sample_id, sample_index, seed, status).
6. Update responses: JobStatusResponse gets n_samples + samples: list[SampleSummary]; JobResultsResponse gets sample_id + sample_index; JobCreatedResponse gets n_samples.
7. Update glasses models: GlassSummary.n_samples (count samples not jobs), AvailableStructure.sample_id, properties sourced from samples.

Phase 3: Pipeline Orchestration (depends on Phases 1 & 2)

8. Update submit_pipeline() to accept seed: int, thread it into generate_structure(), run_melt_quench(), and all analysis wrappers. Key fix: run_viscosity() currently hardcodes seed=12345 — must use passed seed.
9. Each analysis wrapper (run_viscosity, run_cte, run_elastic) forwards seed to the corresponding core function.

Phase 4: Sample-Level Caching (depends on Phase 3)

10. Update _job_hash() to exclude n_samples from the hash — same (composition + potential + params + analyses) → same hash regardless of n_samples.
11. Each sample gets cache_key = f"{request_hash}_s{sample_index}". Executorlib's HDF5 caching handles dedup: when n_samples=5 is submitted after n_samples=3, the first 3 pipelines hit executor cache ({hash}_s0_o.h5 already exists) and return instantly; only samples 3 and 4 compute fresh.
12. Update _clear_executor_cache() to clear {hash}_s* patterns on force=True.
13. Job-level cache check: if a completed job with same hash and n_samples >= requested exists → return it. Otherwise create new job and submit all N pipelines (executorlib handles per-sample dedup).

Phase 5: API Endpoints (depends on Phase 4)

14. POST /jobs: create Job + N GlassSample records, submit N pipelines with seed=i+1 and cache_key=f"{hash}_s{i}", collect results into each sample's result_data.
15. GET /jobs/{id}: return n_samples + sample-level status. Aggregate job status: completed=all done, failed=any failed, running=any running.
16. GET /jobs/{id}/results[/{analysis}], /structure, /visualize: add ?sample=<sample_id> query param (default = sample_index=0).
17. GET /glasses and POST /glasses:lookup: count/reference samples instead of jobs.

Phase 6: Core Library Seed Fix (parallel with Phases 1-2)

18. Fix viscosity_simulation() in viscosity.py to accept seed parameter instead of hardcoding 12345.
19. Verify seed propagation in melt_quench_simulation().

Phase 7: Data Migration Script (independent)

20. Create amorphouspy_api/migrate_jobs_to_samples.py: for each existing Job with result_data, create a GlassSample (sample_index=0, seed=1) with the job's data. Include dry-run flag. Designed to be copy-pasted and run on the production machine via Copilot.

---

Verification

1. Unit tests: GlassSample CRUD, _job_hash() ignores n_samples
2. API tests: n_samples=3 creates 3 samples; default results returns sample 0; ?sample=<id> selects correctly
3. Cache test: n_samples=5 after n_samples=3 reuses first 3 from cache
4. Backward compat: n_samples=1 behaves identically to current code
5. Migration: run on existing DB, verify each job gets 1 sample with correct data

Decisions

• n_samples terminology throughout (not replicas)
• Seeds: deterministic 1, 2, 3, ...
• request_hash excludes n_samples for cross-job sample caching
• Aggregate/average views deferred to follow-up

[Gitdowski]

One comment on this:
I think there are two places where random seeds play a role. One is in the velocity initialization (for Shik and Teter/Du this can be in the first short NVE simulation), the other in the initial generation of the structures. To me, one could use the same seed at both places. Or one seperates them into structure_seed and velocity_seed.

[Gitdowski]

Currently, all replica jobs with the same system size and composition will start with the same initial random structure, because the default of 42 is used in create_random_atoms() if get_structure_dict() is called.

[Gitdowski]

@Atilaac introduced the seed in PR #332. I added it to the API in #336. Now, replica simulations can be executed with different seeds for the initial random structure generation and will get an individual hash.