feat(phaseshifts): add helper CLI

[Liam-Deacon]

Problem

Issue #44 asks for a reproducible phaseshifts integration so users can generate phase shift files and run CLEED without manual file munging.

Solution

• Add src/scripts/cleed_phaseshifts.py, a wrapper around phsh.py that writes output to CLEED_PHASE (or --output-dir) and records a JSON manifest with hashes + versions.
• Document the helper and a full workflow in doc/aux_programs/phsh.rst.

Testing

• Not run (script and documentation only).

Follow-ups

• Decide whether to wire caching or a session directory layout into the helper.
• Clarify if we should add a Python API wrapper once cleed ships as a package.

Summary by Sourcery

Add a command-line helper to generate CLEED phase shift files using the phaseshifts package and record outputs in a JSON manifest.

New Features:

• Introduce the cleed_phaseshifts.py CLI script to wrap phaseshifts/phsh.py and write phase shift files into a chosen output directory with a JSON manifest of inputs and outputs.

Documentation:

• Document the new phaseshifts helper script and describe an end-to-end workflow for generating CLEED phase shift files.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Adds a new cleed_phaseshifts helper CLI that wraps the phaseshifts phsh.py script to generate CLEED phase shift files into CLEED_PHASE (or a specified output directory) while writing a JSON manifest with metadata and hashes, and documents the workflow in the phaseshifts auxiliary program docs.

Sequence diagram for cleed_phaseshifts CLI execution flow

sequenceDiagram
  actor User
  participant cleed_phaseshifts as cleed_phaseshifts_py
  participant phsh_py as phsh_py
  participant filesystem as FileSystem

  User->>cleed_phaseshifts: Invoke with --bulk, --slab, --output-dir
  cleed_phaseshifts->>cleed_phaseshifts: build_parser
  cleed_phaseshifts->>cleed_phaseshifts: parse_args
  cleed_phaseshifts->>filesystem: Check bulk file exists
  filesystem-->>cleed_phaseshifts: Exists or error
  cleed_phaseshifts->>filesystem: Check slab file exists
  filesystem-->>cleed_phaseshifts: Exists or error
  cleed_phaseshifts->>filesystem: Create output_dir if missing
  cleed_phaseshifts->>cleed_phaseshifts: resolve_phsh(phsh)
  cleed_phaseshifts->>filesystem: Check phsh_py in PATH or at given path
  filesystem-->>cleed_phaseshifts: Found or error

  cleed_phaseshifts->>phsh_py: subprocess.run(-g -b bulk -i slab -f format ...)
  phsh_py->>filesystem: Read bulk and slab
  phsh_py->>filesystem: Write *.phs to CLEED_PHASE
  phsh_py-->>cleed_phaseshifts: Exit code

  cleed_phaseshifts->>filesystem: List *.phs in output_dir
  cleed_phaseshifts->>filesystem: Read bulk for sha256sum
  cleed_phaseshifts->>filesystem: Read slab for sha256sum
  cleed_phaseshifts->>filesystem: Write phaseshifts_manifest_json
  cleed_phaseshifts-->>User: Print paths and exit status

Loading

Class diagram for cleed_phaseshifts helper module structure

classDiagram
  class cleed_phaseshifts_module {
    +sha256sum(path Path) str
    +phaseshifts_version() str
    +resolve_phsh(binary str) str
    +build_parser() ArgumentParser
    +main() int
  }

  class Path
  class ArgumentParser

  cleed_phaseshifts_module ..> Path : uses
  cleed_phaseshifts_module ..> ArgumentParser : builds

Loading

File-Level Changes

Change	Details	Files
Introduce cleed_phaseshifts CLI wrapper around phaseshifts/phsh.py for generating CLEED phase shift files and writing a JSON manifest.	Implement argument parsing for bulk/slab inputs, output directory, lmax, format, tmpdir, phsh path, and optional manifest path Resolve the phsh.py binary, ensuring it is discoverable via PATH or given path, and construct the underlying phsh.py command line including environment setup for CLEED_PHASE Execute phsh.py via subprocess with error handling for missing binary or non-zero exit codes Scan the output directory for generated .phs files and compute a JSON manifest including creation time, phaseshifts version, input file paths and SHA-256 hashes, command invocation, output directory, and output filenames Write the manifest JSON file to the specified path and emit basic summary messages to stdout	src/scripts/cleed_phaseshifts.py
Extend documentation to describe the phaseshifts helper CLI and an end-to-end workflow for generating phase shift files for CLEED.	Document the new cleed_phaseshifts helper, its arguments, and expected environment variables/output layout Describe a reproducible workflow integrating phaseshifts with CLEED using the helper script	doc/aux_programs/phsh.rst

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Liam-Deacon]

Clarifications for #44:

• Do you want the helper to parse elements directly from .inp/.bul, or is wrapping phsh.py sufficient for now?
• Should we add a caching policy beyond the manifest (e.g., reuse when inputs/hashes match), or keep the script as a thin wrapper?
• Any preferred CLI name (e.g., cleed-phaseshifts) before we lock it in?

[codacy-production]

Codacy's Analysis Summary

4 new issues (≤ 0 issue)
2 new security issues
20 complexity
0 duplications

Review Pull Request in Codacy →

✨ AI Reviewer available: add the codacy-review label to get contextual insights without leaving GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud