docs/dev/DEPLOYMENT.md

Development and deployment guide

Runtime profile

The repository is ready for a standard CPU Hugging Face Gradio Space. The Space configuration is the YAML block at the top of README.md; it selects app.py, Python 3.10, and the pinned Gradio version. Runtime packages are in requirements.txt:

gradio==5.50.0
matplotlib>=3.7,<4
numpy>=1.23,<3
seekpath==2.1.0
spglib>=2.0,<3

app.py adds the local src/ directory to the import path, so a source-layout checkout runs directly without a separate package-install step.

Local development

Create an environment, install the application dependencies, and run the test suite from the repository root:

python -m pip install -r requirements.txt
PYTHONPATH=src pytest -q
python app.py

Open the local Gradio URL and load a bundled example before changing analysis behaviour. The package should also remain usable without Gradio:

python -m pip install -e .
induced-exchange-uppasd examples/fept_style/inpsd.dat

Keep scientific calculations in src/induced_exchange/; app.py and src/induced_exchange/space.py should remain orchestration and presentation layers. Add or update tests with any behavioural change, especially one that affects input conventions, units, Fourier phases, conditioning diagnostics, or the magnetic model.

Deploy to Hugging Face Spaces

1. Create a Hugging Face Space with the Gradio SDK and a CPU hardware tier appropriate for the intended datasets.
2. Push this repository's release contents to the Space repository. Keep the README YAML metadata, app.py, requirements.txt, src/, and any examples you want visible in the deployed app.
3. Wait for the Space build to complete, then open its public URL. Hugging Face provides the public endpoint, so the application does not use share=True.
4. Verify an upload containing separate inpsd.dat, posfile, momfile, and exchange files, as well as a bundled example.

Operational notes

• The application keeps analysis artifacts in temporary storage and cleans prior session artifacts when a new input is loaded. Do not treat Space local disk as durable user storage.
• Uploaded inputs are scientific data. Set Space visibility, access controls, and repository history according to the sensitivity of the material.
• The interactive mesh selector is limited to CPU-friendly resolutions. Users needing large reciprocal meshes should use the library in their own compute environment.
• spglib expansion is opt-in in the UI. It should be enabled only for symmetry-reduced exchange files, not complete neighbour lists.
• Pinning Gradio matters because the app contains a small compatibility layer for Gradio's 5-to-6 launch/theme API transition. Test a deliberate dependency upgrade locally before publishing it.

Release checklist

• PYTHONPATH=src pytest -q passes.
• python app.py starts without import or Gradio warnings that affect use.
• A bundled example completes through download creation.
• README metadata and requirements.txt match the intended runtime.
• No private input data, credentials, AI prompts, or local build artifacts are included in the commit.