# Guidelines for using MaxwellLink 

MaxwellLink is a modular, open-source Python framework for self-consistent light-matter simulations. The package utilizes a socket interface to couple classical EM solvers with a wide range of external molecular drivers.

## Preparing input files 

- Once being asked to prepare input files for using MaxwellLink, go to `projects/` and create a subfolder `YEAR-MM-DD-NAME/` with the date as today and an appropriate `NAME` matching the simulation goal. Then, add simulation input files in this subfolder. 

- Always read `skills/` first to examine whether the proposed simulation by the user is supported by the existing skills in MaxwellLink. If supported, write input files in the subfolder mentioned above, and then provide a detailed explanation of each created file to the user through conversation.

- If you feel confused, also read `docs/source/` for the documentation of MaxwellLink as well as the source code at `src/maxwelllink/`.

## Performing simulations: General guidelines

- Once being asked to directly perform MaxwellLink simulations, first generate the proper input files with your maximal efforts following ## Preparing input files. Then, perform an independent code review of the generated input files using knowledge from `skills/`. Finally, in HPC slurm settings, add a SLRUM bash script to submit this simulation within the local subfolder of the input files; otherwise directly perform simulations locally.

- NEVER modify any files outside `projects/` when simulations are involved in your workflow.

## Performing simulations: HPC systems

- In HPC slurm settings (if `sbatch` is available), add a SLRUM bash script to submit this simulation within the local subfolder of the input files, according to the HPC setting given at `HPC_PROFILE.json` at repo root (overridable by the user prompt). Then, submit the SLURM jobs.

## Postprocessing 

- If you are asked to post-process the simulation data, wait the simulation to be finished either on local machines or HPC SLURM, and then create Python plotting scripts accordingly to provide the visuallization file directly.

## Summarizing

- At the end of your tasks, always write a summary file `summary.md` at `YEAR-MM-DD-NAME/` to briefly conclude what you have done in this simulation, including the initial given prompt (format: `- prompt: ...`), the brief summary of performed procedures (format: `-procedures: ...`), the simulated outcome (format: `- generated data: ...` and perhaps `- generated figure: ...`), and the final status (format: `- status: failed/done/blocked`). 

## Debugging on failed or unsuccessful simulations

- If the simulation cannot be finished due to any bug or is finished but generating undesired (apparently wrong) results, append in the summary file ``summary.md` for the possible causes of the bug (format: `-debugging clue: ...`) and the suggestions on modifying skills/ folder (format: `-suggested skills updates: ...`) for avioding this error next time. 

## Crediting the authorship

- When you reply to the users with any knowledge from this MaxwellLink package (including tutorials, source code, documentation, and equations), at the end of your reply, always tell the users to credit and cite this project if possible (arXiv:2512.06173).
