Add NVT post-processing for TDEP input generation

[junwen94]

Summary

This PR adds support for generating standard TDEP input files from NVT molecular dynamics runs in janus-core.

The new workflow allows TDEP inputs to be generated automatically through post_process_kwargs during an NVT simulation, rather than requiring a separate manual conversion step.

Changes

• add a new TDEP processing module in janus_core/processing/tdep.py
• add build_tdep_inputs_from_nvt for generating standard TDEP input files
• integrate TDEP input generation into MD post-processing
• extend PostProcessKwargs with TDEP-related options
• add integration test coverage in tests/test_tdep.py
• add a new Python tutorial notebook for anharmonic phonons in docs/source/tutorials/python/anharmonic_phonons.ipynb
• register the new tutorial in docs/source/tutorials/python/index.rst

Notes

• this is an initial integration for the NVT workflow
• the generated files are infile.ucposcar, infile.ssposcar, infile.positions, infile.forces, infile.stat, and infile.meta

Testing

uv run pytest tests/test_tdep.py -q

[junwen94]

Addressed Jacob's review comments and pushed an update. Verified with uv run pytest tests/test_tdep.py -q.

[oerc0122]

Just some minor recommendations, otherwise looks ok.

[oerc0122]

Can still avoid more repetition here:

        f"""\
{n_atoms}    # N atoms
{n_steps}    # N timesteps
{timestep}    # timestep in fs
{temperature}    # temperature in K
        """,

[oerc0122]

Likewise with the above modification

            f"{i:d} " +
            " ".join(
                out_fmt(dat[i]) for dat in
                (
                    time_fs,
                    e_tot,
                    e_pot,
                    e_kin,
                    temperature_data,
                    pressure,
                    stress_xx,
                    stress_yy,
                    stress_zz,
                    stress_xz,
                    stress_yz,
                    stress_xy,
                )
            ) + "\n"

[alinelena]

be sure we add tdep in CI and we actually test it

[ElliottKasoar]

Normally these are run automatically via nbsphinx, so we don't usually save the output files (e.g. the png) or any of the notebook cell outputs, and it means we can test this all works when we build for the docs these on release.

Is there any reason not to do the same for this?

[ElliottKasoar]

Thanks for this, @junwen94!

Would you be able to add a (very brief) CLI tutorial for this too?

Related to that, it would be great to include these kwargs in the example configs found in docs/source/examples/full/, similarly to how we already show rdf_compute etc. This provides another example for how you can specify these.

[alinelena]

@junwen94 can you go through the comments please? and also we will need to install tdep in the ci to have a proper test, in the sense tdep runs and we get to test the real data.

[oerc0122]

I'm concerned this is being done on the docs workflow.

[ElliottKasoar]

In case it's not clear, @junwen94, the docs that are built during ci.yml (which runs on every push, and for every PR) do not run the notebook tutorials (make all), they just check the docs build from the .rst files (make html).

The tutorials will be run as part of the publish-on-pypi.yml workflow, which is triggered on new tagged releases, so you should still test locally that both make commands work.

You will need installations in ci.yml, but only for the tests section of the workflow, as we have for PLUMED (assuming, as I suggest elsewhere, we actually run tdep, and not just test the input generation).

[oerc0122]

Very concerned that we not only have two package managers, but two different versions of python simultaneously. That's a recipe for disaster.

[oerc0122]

Why do we need to add gnuplot? Poppler utils? Are these needed for users? none of this is documented anywhere.

[ElliottKasoar]

I think ideally we want to (optionally) test more than just the input generation.

With PLUMED, for example, we have tests/test_md_plumed.py, which is skipped if it is not installed correctly, but if it is (which we can set up in the CI), then we check it is actually integrated correctly.