Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
3f6f877
Gstore method for debugging purpose
gmatteo Jul 31, 2026
95f6d08
GWAN file
gmatteo Aug 3, 2026
5337d8f
Fix wannier interpolation with exclude_bands and outer window
gmatteo Sep 5, 2026
bed2b95
new version of pip_all.sh
gmatteo Sep 5, 2026
6b75fe8
Merge branch 'master' into gmatteo
gmatteo Sep 5, 2026
17fe684
Support old gstore files when comparing matrix elements
gmatteo Sep 17, 2026
bc88908
Change needed to support phonopy4
gmatteo Sep 27, 2026
6864910
Remove requirements files, move to pyproject.toml
gmatteo Sep 27, 2026
69b61a8
Require phonopy < 4.0
gmatteo Sep 27, 2026
4c23b37
Merge remote-tracking branch 'origin/develop' into gmatteo
gmatteo Sep 27, 2026
e058817
Continue to fix deprecation warnings
gmatteo Sep 27, 2026
e4f32bd
Fix race condition in Ebands.from_string
gmatteo Sep 27, 2026
37ccb41
Fix numpy deprecation warnings
gmatteo Sep 28, 2026
ecbd927
Execute ruff check . --fix
gmatteo Sep 28, 2026
5615d44
ISOME should not be imported
gmatteo Sep 28, 2026
2b1317d
Restrict UCX to shared memory and TCP
gmatteo Sep 28, 2026
2c66d53
Skip test_cod_api
gmatteo Sep 28, 2026
fe05761
Improve integration tests
gmatteo Sep 29, 2026
a11f60e
Merge branch 'develop' of https://github.com/abinit/abipy into gmatteo
gmatteo Sep 29, 2026
4339404
Revert panel widget label=/color= rename: panel.widgets uses name=/bu…
gmatteo Sep 29, 2026
8bec764
Merge branch 'develop' into gmatteo
gmatteo Sep 29, 2026
412b19d
Update vars database
gmatteo Sep 30, 2026
fc4db41
Deactivate test_cod
gmatteo Sep 30, 2026
909c823
Fox warnings in doc
gmatteo Sep 30, 2026
7b5e638
Fix warnings in docs
gmatteo Oct 1, 2026
ba87482
Fix warnings in docs
gmatteo Oct 1, 2026
789db56
Add skills
gmatteo Oct 3, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 152 additions & 0 deletions .agents/skills/abipy-cli/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
---
name: abipy-cli
description: Add or modify AbiPy command-line tools and subcommands, preserving parser, dispatch, output, exit-code, optional-dependency, safety, packaging, and subprocess-test conventions. Use for scripts under abipy/scripts and their shared CLI helpers; not for domain logic that belongs in library modules.
---

# Develop AbiPy command-line tools

Keep the CLI thin: parse user intent, validate boundaries, call reusable AbiPy APIs, format results, and return a
meaningful exit code. Put scientific algorithms, readers, input construction, and workflow mechanics in their domain
modules so they are usable without a subprocess.

Use `abipy-navigate` to locate the underlying API, `python-virtual-env` before running commands, and
`abipy-run-tests` for focused validation. Use `abipy-flowtk` when a command inspects or mutates a flow.

## Match the command's existing framework

Most modules in `abipy/scripts` use `argparse`, a `get_parser(with_epilog=False)` function, and
`@abipy.tools.cli_parsers.prof_main`. `abiml.py` uses Click and its decorator helpers. Extend the framework already
used by the command; do not mix Click and argparse inside one command merely for a new subcommand.

For argparse commands:

- keep reusable parent parsers for options shared by several subcommands;
- use `dest="command"` dispatch consistently with neighboring branches;
- provide actionable positional and option help, defaults, units, and constrained `choices` where appropriate;
- include examples in the raw-text epilog when syntax is not obvious;
- configure logging through `cli_parsers.set_loglevel` or the established local equivalent;
- reuse `EnumAction`, `range_from_str`, Panel-serving, plotting, and profiling helpers instead of duplicating them.

For Click commands, follow the established option decorators, context usage, configuration callbacks, and
Click-native path/type validation.

All top-level tools should support useful `--help` and `--version` behavior. Preserve profiling through `prof`,
`tuna`, and `snakeviz` when the script uses `@prof_main`.

## Packaging and entry points

AbiPy currently packages every Python file under `abipy/scripts` through the `scripts=` mechanism in `setup.py`, not
through `[project.scripts]` console entry points. A new top-level command therefore needs a script file with the
project shebang/main convention and an executable installation path. Do not add a second packaging mechanism for a
single command without an intentional project-wide migration.

Prefer adding a subcommand to the tool that already owns the domain. Create a new top-level script only when its
purpose and option space are distinct enough to be discoverable independently.

## Dispatch and exit codes

Keep parsing, dispatch, and command implementation visibly separated. A command handler should return an integer:

- `0` for success;
- nonzero for an expected failure the caller can act on;
- argparse/Click usage errors for invalid syntax.

`@prof_main` ultimately calls `sys.exit(main())`, so returned values become process exit codes. Do not print an error
and then return success. Avoid catching broad exceptions solely to turn every defect into an uninformative message;
when handling an expected exception, preserve enough context for diagnosis and return nonzero.

Write primary command results to stdout and warnings/errors to stderr when practical. Keep ordinary output stable
enough for shell use, and do not add decorative text to a branch intended to emit JSON, CSV, YAML, or another
machine-readable format. Respect existing no-color/no-logo options and avoid terminal control codes when output is
redirected.

## Paths, files, and AbiPy objects

Use `abilab.abiopen` or the appropriate domain loader rather than reproducing suffix dispatch. Close file-backed
objects deterministically, preferably with a context manager. Use `abipy.data` only for bundled examples/tests, not
as an implicit substitute for a missing user path.

Resolve and validate input paths before expensive work. For output paths:

- distinguish printing to stdout from writing a file;
- state the selected format and destination;
- do not overwrite an existing file or directory silently unless overwrite behavior is already explicit in that
command;
- create parent directories only when the command contract promises it;
- report partial output if a later operation fails.

Treat pickles as trusted-input formats. Do not imply that arbitrary pickle files are safe to open.

## Optional and interactive features

Import optional dependencies inside the branch that needs them so `--help`, `--version`, and unrelated subcommands
remain usable. On a missing optional package, identify both the requested feature and dependency; do not mask an
unrelated import or runtime error as an installation problem.

Plotting, IPython, Jupyter, Panel servers, clipboard operations, web browsers, and GUI viewers require interactive
resources. Keep noninteractive commands headless, honor options such as `--no-browser`, and configure Matplotlib
before importing plotting backends when the existing helper expects that order.

Network-backed identifiers or downloads must be explicit in the command and should produce actionable failures
when credentials or connectivity are missing. Do not introduce network access into a formerly local operation as an
implicit fallback.

## Mutating and external operations

Classify each subcommand before implementing it:

- inspection/formatting;
- local file creation or modification;
- external process execution;
- flow or scheduler mutation;
- destructive cleanup.

The latter categories need clear help text and explicit flags. Before deleting, overwriting, submitting, cancelling,
restarting, or modifying a persisted flow, resolve the exact target and use the confirmation/dry-run convention of
the parent command. A `--yes` or force option is authorization for the documented target only, not broader cleanup.

Do not prompt from commands intended for pipelines unless the user selected an interactive mode. In noninteractive
contexts, a missing required confirmation should fail rather than assume yes. Keep analysis commands read-only even
when an underlying object exposes mutating methods.

## Reuse shared behavior

Place a helper in `abipy/tools/cli_parsers.py` only when multiple commands genuinely share it. Keep domain-specific
formatting or dispatch near its command or, preferably, in the domain library if useful programmatically.

Common reusable facilities already include:

- log-level setup;
- Panel server options and keyword conversion;
- Matplotlib/seaborn and figure-exposure options;
- enum parsing and range parsing;
- OpenMP thread normalization;
- profiling of `main`.

Do not broaden a shared helper with command-specific assumptions that could change other scripts.

## Tests

Add subprocess-level coverage in `abipy/scripts/tests/test_scripts.py` or a focused neighboring test module. The
existing `ScriptTest` pattern uses `scripttest.TestFileEnvironment`, an isolated working directory, and a headless
Matplotlib backend.

At minimum, test:

- `--help` and `--version` for a new top-level tool;
- the new subcommand's smallest successful invocation;
- return code and relevant stdout/stderr content;
- invalid syntax or a representative expected failure;
- output-file creation and overwrite behavior when applicable;
- missing optional dependency behavior if the branch can be isolated reliably.

Use small files from `abipy.data` and `abipy/test_files`. Do not open browsers, GUIs, notebooks, or Panel servers in
unit tests. Mock external services and scheduler mutations; skip only when the test genuinely requires an optional
executable or dependency.

Also test the underlying library function directly in its domain test module. CLI tests should prove parsing,
dispatch, formatting, and process semantics, not duplicate an entire scientific test suite.

Run the script through the same path users exercise, not only by calling `main()` in process. Report the exact
invocation, exit code, important output, and whether the command created files, launched a process, accessed the
network, or mutated a flow.
169 changes: 169 additions & 0 deletions .agents/skills/abipy-docs-examples/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
name: abipy-docs-examples
description: Add and maintain AbiPy Sphinx documentation, API pages, CLI references, and executable Sphinx-Gallery plot or flow examples. Use for docs and examples under docs/ and abipy/examples; distinguish generated API/gallery output from maintained sources.
---

# Develop AbiPy documentation and examples

Document the public behavior implemented in code and keep examples executable, small, and scientifically honest.
Do not use documentation changes to conceal an unclear API; improve the library interface first when needed.

Use `abipy-plotting` for plotting API conventions, `abipy-flowtk` for workflow examples, `abipy-cli` for command
references, and `abipy-reference-data` for bundled example inputs.

## Know maintained sources from generated output

The main maintained documentation sources are under `docs/`, with `docs/index.rst` defining the top-level toctrees.
Important areas include:

- `docs/tutorials`, `docs/workflows`, and topical `.rst` pages for narrative guides;
- `docs/scripts` for command-line documentation;
- `docs/abiref.bib` for citations and `docs/links.rst` for global substitutions/links;
- `abipy/examples/plot` and `abipy/examples/flows` for executable gallery sources;
- Python docstrings for API reference content.

`docs/api` is regenerated by `sphinx-apidoc`. `docs/gallery` and `docs/flow_gallery` are generated by Sphinx Gallery.
Edit the Python modules, docstrings, example sources, or generator configuration—not generated gallery pages. When
tracked API stubs change, regenerate them through the established command instead of hand-maintaining a module list.

Before editing or regenerating, check the working tree so generated output does not overwrite unrelated user work.

## Write narrative documentation

Follow the surrounding reStructuredText style and add a new page to the appropriate `toctree`; an unreferenced page
may build but remain undiscoverable. Give stable sections explicit labels when other pages should link to them.

Prefer semantic Sphinx roles and cross-references over literal names and raw URLs:

- Python objects: `:class:`, `:meth:`, `:func:`, `:mod:`;
- documents and sections: `:doc:` and `:ref:`;
- commands and files: `:program:` and `:file:`;
- citations: `:cite:` with an entry in `docs/abiref.bib`.

Reuse aliases already defined in `docs/links.rst`. Add a global alias only when several pages benefit; otherwise keep
the link local. Use notes and warnings for consequential information, not ordinary prose.

Keep commands copyable and specify their working directory, required environment, and whether they write files,
launch programs, submit jobs, or use the network. Do not document a destructive or scheduler command as though it
were an inspection command.

## Docstrings and API pages

AbiPy docstrings use Google-style sections interpreted by Napoleon. Document public parameters, units, shapes,
return values, exceptions, side effects, optional dependencies, and index conventions that are not obvious from the
signature. Keep examples short enough for the docstring; move complete workflows to the gallery.

New public modules are discovered by the `sphinx-apidoc` command used in `tasks.py`. The generated API excludes
tests, benchmarks, data, integration tests, test files, and examples. If a public object is intentionally exported,
also follow the package's `__all__` or public-import convention so autodoc and users see the same API.

Regenerate API stubs with the command encoded in `tasks.py` or with `invoke make-doc` only when an interactive full
workflow is desired. `invoke make-doc` also cleans, builds, and opens the HTML site in a browser, so it is not the
preferred headless verification command.

## CLI documentation

CLI pages under `docs/scripts` normally combine narrative examples with the `sphinxarg.ext` directive:

```rst
.. argparse::
:ref: abipy.scripts.abiopen.get_parser
:prog: abiopen.py
```

Keep the parser importable without executing the command, opening a GUI, accessing the network, or requiring an
optional runtime dependency. Use `.. command-output::` only for deterministic, fast, read-only commands available in
the documentation environment.

Update the scripts toctree when adding a maintained CLI page. The parser's own help remains the source of truth for
the complete option list; narrative docs should explain workflows and important safety constraints rather than
duplicate every flag manually.

## Plot gallery examples

Plot examples live in `abipy/examples/plot` and are selected by the gallery filename pattern `plot*`. Start with a
raw reStructuredText module docstring containing a concise title and underline:

```python
r"""
Example title
=============

Explain the scientific question and the data used.
"""
```

Use `# %%` blocks followed by explanatory comments to interleave narrative and executable code. Load bundled inputs
through `abipy.data`, close file-backed objects with context managers, and call public APIs as a user would. Let
Sphinx Gallery capture figures; do not save generated PNG/PDF files in the source directory.

Keep examples deterministic and modest in memory/runtime. Avoid credentials, network downloads, personal paths,
interactive prompts, GUI-only backends, and unavailable external executables. The docs configure Matplotlib `Agg`
and disable Plotly's default show behavior, so examples must not depend on browser display.

Add a new example only when it teaches a distinct workflow. Extend an existing example when the new call is a small
variation of the same concept.

## Flow gallery examples

Flow examples live in `abipy/examples/flows` and are selected by the pattern `run*`. Follow the established split:

- a `build_flow(options)` function creates and returns the graph;
- `@flowtk.flow_main` wraps `main(options)` for normal user execution;
- workdir and manager come from the supplied options;
- bundled structures and pseudos replace machine-specific inputs.

Documentation execution may build, validate, or visualize a graph, but it must not submit calculations. Follow the
nearest maintained `READTHEDOCS` guard for gallery-specific graph generation. Never add `--scheduler`, queue
submission, or cleanup of arbitrary work directories to documentation execution.

Choose minimal meshes/cutoffs when calculations or ABINIT queries cannot be avoided, while preserving the topology
being demonstrated. Clearly label pedagogical parameters that are not suitable for production science.

The full docs Makefile removes `abipy/examples/flows/flow_*` before gallery execution. Treat those as generated flow
directories and verify that no user-owned work is present there before running the full target.

## Build and verification levels

Activate the correct Python environment and install/use the existing `docs` dependency group. Do not install or
upgrade documentation packages implicitly merely because a build reports a missing dependency.

Use verification proportional to the change:

1. Run affected library/CLI tests and execute a new example directly with a headless backend where possible.
2. For prose, docstrings, or API links, build without executing galleries:

```bash
cd docs
READTHEDOCS=1 sphinx-build -D plot_gallery=0 -b html -d _build/doctrees . _build/html
```

3. Regenerate API stubs when public module structure changed.
4. Run the full `make html` from `docs` when gallery execution or full integration matters. It runs
`generate_rst_files.py`, cleans generated flow directories, and executes gallery examples.
5. Use `make linkcheck` when external links changed, recognizing that it requires network access and can fail for
reasons outside the repository.

For stricter review, add `-W -n --keep-going` to a focused Sphinx build, but distinguish new warnings caused by the
change from existing project warnings. The normal Makefile does not enable warnings-as-errors.

Do not open the generated site with `open`, a browser, or `invoke make-doc` in a headless agent session. Inspect the
build result and relevant HTML files directly.

## Review generated changes

After a build, inspect `git status` before accepting changes. Do not commit `_build`, gallery caches, notebooks,
images, zip files, flow work directories, or example output artifacts unless the repository intentionally tracks
that exact generated class.

Check that:

- new pages appear in the intended toctree;
- cross-references resolve and code examples match the current API;
- galleries execute without unexpected failures;
- no example submits work or depends on local configuration;
- API regeneration changes only the expected modules;
- generated artifacts have not leaked into source directories.

Report source pages/examples changed, generated API stubs changed, build command and environment, gallery execution
status, new versus pre-existing warnings, and any optional example not executed with the reason.
Loading
Loading