Contributing#

This page is the entry point for anyone who wants to fix a bug, add a feature or improve the documentation of CrystOD. It describes how the repository is organized, how it is tested and how a release is made.

Getting started#

  • Bug reports and feature requests go to ahntaeyoung1212/CrystOD#issues. For a wrong or missing symmetry result, attach the input structure (POSCAR or XYZ) and the exact command line; if you compared against another program (Bilbao Crystallographic Server, ISOTROPY/ISODISTORT, AMPLIMODES, phonopy), say which one and paste its answer.

  • Small fixes (a typo, a docstring, an error message) can go straight into a pull request.

  • Larger changes are best discussed in an issue first, so that the design is settled before the work is done.

Development setup#

CrystOD is developed on Linux and macOS with Python 3.11 in a conda environment; the package itself supports Python 3.10 and later (requires-python in pyproject.toml).

conda create -n crystod python=3.11 && conda activate crystod
git clone https://github.com/ahntaeyoung1212/CrystOD.git && cd CrystOD
pip install -e ".[dev]"

The editable install (-e) makes the checkout importable and puts the eleven console scripts (crystod, crystod-group, crystod-bz, crystod-phonon, crystod-mag, crystod-md, crystod-mol, crystod-xrd, crystod-slab, crystod-search, crystod-example) on the path, so an edit takes effect on the next run (a new console script, or a new version number, needs pip install -e . --no-deps again). The extras defined in pyproject.toml are:

extra

contents

needed for

quantum

pyscf

the --pyscf engines (crystod --diagram/--band/--dos/--visualize --pyscf, crystod-mol --diagram --pyscf) and the test-suite checks that exercise them

doc

sphinx, myst-parser, sphinx-book-theme, sphinx-copybutton

building the documentation

dev

quantum + doc + ruff, nbconvert, ipykernel, build, twine

everything a contributor needs: linting, executing the tutorial notebooks, building a release

all

quantum + doc

a user install with every optional feature

PySCF (about 500 MB with its dependencies) is optional on purpose: everything except the --pyscf engines runs without it, and a --pyscf command stops with a one-line ERROR that names the extra to install (crystod/_optional.py). Do not add an unconditional import pyscf anywhere.

Running the tests#

The regression suite is testsuite.py at the repository root: plain Python, no test-runner dependency. Run it from the repository root inside the environment:

python testsuite.py               # all 66 sections
python testsuite.py 02-10         # section 02-10 only
python testsuite.py 01-03 07-02   # sections 01-03 and 07-02
python testsuite.py 05            # the command group 05 (crystod-mag)

Each check prints [PASS] or [FAIL] with its name (and, on failure, the output of the command it ran); the run ends with Total: N passed, M failed and exits with status 1 if anything failed. The suite reads its inputs from example/ and writes to temporary directories, and every individual command has a 900 s timeout. Without PySCF the PySCF-dependent checks in sections 01-03, 01-10 and 07-02 are skipped with a [SKIP] line and the rest of the suite still runs; the CI matrix installs [quantum], so nothing is skipped there.

The MCP server. crystod-mcp/ is a separate package with its own pytest suite (56 tests: every tool on the bundled inputs plus protocol round trips); run it after installing the package next to CrystOD:

pip install -e "./crystod-mcp[test]"
python -m pytest -q crystod-mcp/tests

The mcp job of the Tests workflow runs it on every push.

Section numbers. One number CC-NN identifies a feature everywhere in the repository: CC is the command group and NN the index inside it. Section CC-NN of testsuite.py tests it (the key "CC-NN" of SECTIONS, the function test_CC_NN_name, the header [CC-NN]), example/CC-NN_name/ holds its worked example (the inputs, plus a line in example/README with the command), and section CC-NN of the command’s page in doc/ documents it (## 02-10. Isotropy subgroups (--parent) in doc/crystod-group.md, for example). The sub-sections of a section are lettered CC-NN-A, CC-NN-B, … (### 02-01-A. Point-group irreps (--pg/--point-group) in the same page). The command groups are 01 crystod (with 01-01, the library core, and 01-11, the Python API), 02 crystod-group, 03 crystod-bz, 04 crystod-phonon, 05 crystod-mag, 06 crystod-md, 07 crystod-mol, 08 crystod-xrd, 09 crystod-slab, 10 crystod-search and 11 crystod-example; the docstring at the top of testsuite.py lists all 66 sections by group. python testsuite.py CC-NN ... runs single sections, python testsuite.py CC a whole group, and an old number from before the CC-NN scheme is refused with its new number.

Numbering a new feature. A new feature takes the next free NN of its command group: after the last section of that group, whatever that section is, so no existing number ever moves (a new crystod-mag mode after 05-11 is 05-12). Use the same number for the test function and its SECTIONS entry ("05-12": test_05_12_name, kept in the order of the groups), the header line printed by the function, the example directory example/05-12_name/ with its line in example/README, the heading ## 05-12. Title of doc/crystod-mag.md and the entry in the docstring of testsuite.py. A command group with no section yet (a new command) takes the next free CC. The command-line regression sections (“extras”: aliases, error messages, removed flags) have no example directory of their own (01-10, 02-18, 03-03, 05-05, 06-02, 07-03; 04-11 also documents crystod-phonon --subgroup, whose inputs are those of 04-07_modulation, and 06-02 documents crystod-md --summary, whose input is in 06-01_xdatcar2adp); neither have 01-08, 05-04, 05-07, 05-11 and 11-01.

.github/workflows/test.yml runs the full suite on Linux (Python 3.10, 3.12, 3.13) and macOS (3.12) for every push and pull request to main.

Building the docs#

The documentation is MyST Markdown under doc/, built with Sphinx and sphinx-book-theme (phonopy-style). With the doc (or dev) extra installed:

sphinx-build -b html -W --keep-going doc doc/_build/html

then open doc/_build/html/index.html. -W turns warnings into errors, and that is what .github/workflows/docs.yml checks on every push. The published site, https://mochizuki-tus.github.io/CrystOD/, lives in the laboratory website repository and is copied there by the maintainer, so the workflow deploys nothing: it verifies that the build is clean and keeps the HTML as a run artifact. README.md and the corresponding pages in doc/ (install.md, quickstart.md, the command tables) are maintained in parallel; change both.

Code style#

  • ruff. ruff check . from the repository root must pass; .github/workflows/lint.yml runs the same command. The configuration is ruff.toml: Python 3.10 target, line length 100 for new code, and a deliberately small rule set (syntax errors, undefined and redefined names, invalid comparisons, bare except), the rules that point at a bug rather than a preference, each enabled because it is clean on the whole tree. The comments in ruff.toml list the rules and the candidates that are not enabled yet.

  • Docstrings are Google style (Args:, Returns:, Raises:) with a one-line summary first. Every public function and class needs one; they are what help() and the API documentation show.

  • English in code, comments, docstrings, documentation and commit messages.

  • Errors. The implementation modules double as command-line code and report bad input with raise SystemExit("ERROR: ..."): one sentence that names the remedy. The API layer (crystod/_api.py) turns that into a ValueError for library callers, so a function that follows this rule serves both. A dependency’s traceback is never the message a user sees.

  • Imports. An implementation module may import phonopy, spgrep, pyscf or matplotlib at module level, because the API domain modules load implementation modules lazily (PEP 562). crystod/__init__.py, the domain modules and any --help path must stay free of them (import crystod plus all ten domains is measured at about 0.2 s and a test in section 01-11 keeps it that way).

How to add a feature#

A feature touches the same places every time, in this order:

  1. Implementation module, crystod/<feature>.py: a function or class that takes plain Python/NumPy inputs and returns data; the terminal report and any HTML or VESTA output are separate functions. Existing modules are the template (crystod/isotropy_subgroup.py, crystod/phonon_subgroups.py).

  2. API export: add the public name to _EXPORTS in the domain module of the command it belongs to (crystod/salc.py, group.py, phonon.py, bz.py, mag.py, md.py, mol.py, xrd.py, search.py) as "name": ("implementation_module", "attribute"). That is the whole registration; crystod.<domain>.name then resolves lazily.

  3. Command line: the flag in build_parser() of crystod/cli/<command>.py and its branch in main(), with an example in the --help epilog. A feature that needs PySCF calls require_pyscf_or_exit() before importing it.

  4. Tests: checks in the section of that command in testsuite.py (or a new test_CC_NN_... function registered in the SECTIONS dict at the bottom of the file, numbered as described under Numbering a new feature), written with run_cli() and report() like the neighbouring checks. Assert on the physics (a space group, an irrep label, an amplitude), not only on the exit status, and say where the reference value comes from.

  5. Documentation: the numbered section in doc/<command>.md with the command line and its output; the command table in README.md if a new mode was added; an entry in doc/changelog.md.

  6. Example: example/CC-NN_<feature>/ with the inputs and a line in example/README. Generated outputs are git-ignored (example/**/*.html, *.csv, *.chk, …); commit the inputs only. Write the README to run inside its own directory: shared structures as ../test_POSCARs/..., files of another example as ../CC-NN_other/..., never a path from the repository root.

  7. Packaged example: decide whether the example ships with the package (it should, unless it needs large, unpublished or third-party data). Data left out of the package stays in the CrystOD development tree, and the README marks the commands that need it: “not in the pip package”, or “unpublished, not distributed” for the data of unpublished work. If it does ship:

    • add its files to example/PACKAGED, one path or glob per line, and a requires CC-NN_new: CC-NN_other line if the README uses files of another example directory;

    • commit the example files first (the sync script copies only files tracked by git and refuses selected files with uncommitted changes), then run python script/sync_packaged_examples.py, which copies the selection byte for byte into crystod/examples/ and rewrites crystod/examples/index.json and README (python script/sync_packaged_examples.py --check only compares);

    • commit the generated files under crystod/examples/ together with example/PACKAGED.

    Section 11-01 of the test suite checks that the packaged files are exactly the selection of example/PACKAGED, identical to their originals in example/ and within the size budget of that file, and that every file a README names is there when that example is copied alone (crystod-example CC-NN into an empty directory); a README paragraph whose marker line says “not in the pip package” or “not distributed” is skipped. Never edit the copies under crystod/examples/CC-NN_* by hand: change example/ and synchronize.

Commit messages and pull requests#

Commit subjects follow the Conventional-Commits-like pattern already in the log: a lower-case area prefix, a colon and an imperative summary, as in doc: add a desktop toggle for the right-hand table of contents or diagram: URL-selectable k point and embed-friendly level panel. Use the command or module as the area (phonon:, group:, mol:, diagram:, api:, cli:), or doc:, test:, ci:, examples: for the surrounding files. The body says why, and for a symmetry result, what it was validated against. A release commit is simply CrystOD vX.Y.Z.

A pull request should

  • target main and pass the three workflows (Tests, Lint, docs);

  • add or extend test-suite checks for the change, and update the documentation and the changelog together with the code;

  • describe the change, the reason and the validation in its description, in English.

Release process#

  1. Bump the version in three files, pyproject.toml (version), crystod/__init__.py (__version__) and CITATION.cff (version and date-released), and add the release section to doc/changelog.md (newest first). The documentation reads its version from pyproject.toml.

  2. Run the full suite and the docs build, and python script/sync_packaged_examples.py --check (the packaged examples must match example/PACKAGED).

  3. Commit the release (git add the changed files by name, new files under crystod/examples/ included, then git commit -m "CrystOD vX.Y.Z"), and build and check the distribution from an export of that commit, never from the working tree:

    rm -rf /tmp/crystod-rel && mkdir /tmp/crystod-rel
    git archive HEAD | tar -x -C /tmp/crystod-rel
    cd /tmp/crystod-rel && python -m build --outdir dist && twine check --strict dist/*
    

    The package-data globs of pyproject.toml read the disk and ignore .gitignore, so a build in the working tree would also pack whatever README test runs have left under crystod/examples/. Never use python -m build --no-isolation in the working tree: with setuptools-scm installed in the environment, every file tracked by git would go into the sdist. The export has neither problem. Check that the wheel’s crystod/examples/ holds exactly git ls-files crystod/examples.

  4. Tag and push:

    git tag v0.4.0
    git push origin main --tags
    
  5. The tag triggers .github/workflows/publish.yml: the build job refuses a tag that does not match the three version fields, builds the sdist and the wheel, runs twine check and stores them as an artifact; the publish job then waits for approval in the release environment and uploads with PyPI Trusted Publishing (OpenID Connect; no API token is stored in the repository). The one-time setup of the publisher on pypi.org and of the release environment on GitHub is spelled out at the top of publish.yml.

  6. Copy the freshly built documentation to the laboratory website repository.

About DEVELOPMENT.md#

DEVELOPMENT.md is the internal development log: a dated, Japanese-language record of decisions, validations and dead ends. It is kept outside the public repository (it is listed in .gitignore) and is not translated. This file is the entry point for new contributors; anything a contributor needs to know belongs here or in doc/.