Feat/seed for structure generation

[Gitdowski]

Following PR #332, where a random seed to the get_structure_dict() has been added, this PR adds the new input argument structure_seed to the API workflow. If now a replica simulation is started with the same composition, system size and settings, but with a different structure_seed it will trigger a new simulation.
Also, the structure_seed is also part of the hashing. Therefore, an existing database needs to be migrated.

• added structure_seed to the MeltQuenchParams class and the generate_structure()
• added tests

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Gitdowski]

For reference, at the current stage, a database can be migrated (requires write access) using:

# run once with app env
from amorphouspy_api.database import get_job_store, Job
from amorphouspy_api.models import JobSubmission
from amorphouspy_api.routers.jobs_helpers import _job_hash

store = get_job_store()
with store.session() as s:
    rows = s.query(Job).filter(Job.status == "completed").all()
    for row in rows:
        req = row.request_data or {}
        sim = req.get("simulation", {})
        if "structure_seed" not in sim:
            sim["structure_seed"] = 42
            req["simulation"] = sim
            sub = JobSubmission(**req)
            new_hash = _job_hash(sub, row.composition)
            row.request_hash = new_hash
            row.request_data = req
    s.commit()

[Copilot]

Pull request overview

This PR extends the API workflow to accept a structure_seed parameter for structure generation, ensuring that identical compositions/settings can produce different initial structures (and thus distinct jobs) when the seed changes, and that the seed is included in job hashing for caching/deduplication.

Changes:

• Add structure_seed to MeltQuenchParams and include it in the job hash via submission.simulation.model_dump().
• Forward structure_seed to core structure generation as random_seed in generate_structure().
• Add API and workflow tests to verify hashing, forwarding, and request acceptance.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
amorphouspy_api/src/amorphouspy_api/models.py	Adds structure_seed to the simulation parameter model exposed by the API.
amorphouspy_api/src/amorphouspy_api/workflows/meltquench.py	Passes the new seed through to get_structure_dict(..., random_seed=...) during structure generation.
amorphouspy_api/src/tests/test_jobs.py	Adds tests covering hash changes, seed forwarding, and POST acceptance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Atilaac]

Thanks @Gitdowski, can you add this to the documentation as well!

[Gitdowski]

@Atilaac: Good catch. Is this another place in the documentation where you would add a word on this, or is this fine?

[ltalirz]

Can you check: at the moment, if I specify the same structure_seed, do I get the same structure?
My suspicion would be: yes, on the same computer; maybe not on different computers.

What you may want to communicate here is: if you use a fixed structure_seed , you may get the same structure (not guaranteed). If you use a different structure_seed, you are guaranteed to get a different structure

[Gitdowski]

I changed the RNG to explicitely call the PCG64, PreComputed Generator, instead of relying on the default_rng() (which currently is the PCG64). Therefore, we are safe in case numpy decides to switch to a different RNG for a future release.
Furthermore, PCG64 is frozen and designed to be reproducible across different CPU achitectures and operating systems.

I just checked this for a small system on two different machines. With the default seed the same structures are generated on both machines. Also using a non-default seed produces the same structures on both machines (and of course different from the structures generated by the default seed).

[ltalirz]

Great, thanks! So is it still true that the result depends on Python/numpy version or no longer?

In any case, good to merge from my side

[Gitdowski]

Yes, if I undersand it correctly, this should be reproducible even across different python/numpy versions, as long as numpy version is 1.17 or newer. They explicitely fixed this.

From Copilot: Caveats (that we are currently not using in our code):

1. If the call order of commands is changed, this changes the results. Eg,

rng.random()
rng.normal()

is not the same as

rng.normal()
rng.random()

2. If we employ parallel or distributed usage. For example when using:

• SeedSequence.spawn
• multiprocessing
• joblib
• MPI

Reproducibility then depends on:

• stable process count
• stable spawning order

This is deterministic but configuration‑sensitive.