From 3124f81d205ade735cf8fe61b2afaee1be711f4a Mon Sep 17 00:00:00 2001 From: Shuhei Ohno Date: Wed, 12 Aug 2026 17:36:11 +0900 Subject: [PATCH] Add developer guide --- README.md | 46 ++-------------- docs/Project.toml | 1 + docs/make.jl | 2 + docs/src/developer.md | 125 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+), 42 deletions(-) create mode 100644 docs/src/developer.md diff --git a/README.md b/README.md index ed8b1a1..35f788c 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,8 @@ TwoBody.jl: a Julia package for quantum mechanical two-body problems -## Documentation +## Documentation -https://juliafewbody.github.io/TwoBody.jl/dev/ - -## Dependency - -```mermaid ---- -config: - layout: elk - theme: mc ---- -flowchart TD - A["Hamiltonian.jl"] - C["Rayleigh-Ritz.jl"] - F["FDM.jl"] - Q["QTT.jl"] - N["VNN.jl"] - G["VMC.jl"] - H["DB.jl"] - Z["TwoBody.jl"] - A --> H - A --> C & F & Q & G - H --> C & F & Q & G - C & F & Q & G --> Z - A --> C & F & N & G - H --> C & F & N & G - F --> N - C & F & N & G --> Z -``` - -## Developer's Guide - -There are several tools for developers. - -```sh -git clone https://github.com/JuliaFewBody/TwoBody.jl.git -cd TwoBody.jl -julia -julia> include("dev/revice.jl") -julia> include("dev/test.jl") -julia> include("dev/docs.jl") -``` +- Home: https://juliafewbody.github.io/TwoBody.jl +- Developer Guide: https://juliafewbody.github.io/TwoBody.jl/dev/developer +- API Reference: https://juliafewbody.github.io/TwoBody.jl/dev/API diff --git a/docs/Project.toml b/docs/Project.toml index 3b2bed0..1150125 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -2,6 +2,7 @@ Antique = "be6e5d0e-34a5-4c8f-af83-e1b5389203d8" CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177" Lux = "b2108857-7c20-44ae-9111-449ecde12c47" Optimisers = "3bd65402-5787-11e9-1adc-39752487f4e2" TwoBody = "a92d7657-722c-45a6-9d18-9da4c8a753b6" diff --git a/docs/make.jl b/docs/make.jl index e3bffd7..6134fca 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,5 +1,6 @@ using TwoBody using Documenter +using DocumenterMermaid DocMeta.setdocmeta!(TwoBody, :DocTestSetup, :(using TwoBody); recursive=true) @@ -25,6 +26,7 @@ makedocs(; "Quantics Tensor Train" => "QTT.md", "Variational Neural Network" => "VNN.md", "Variational Monte Carlo" => "VMC.md", + "Developer Guide" => "developer.md", "API reference" => "API.md", ], ) diff --git a/docs/src/developer.md b/docs/src/developer.md new file mode 100644 index 0000000..f43c214 --- /dev/null +++ b/docs/src/developer.md @@ -0,0 +1,125 @@ +# [Developer Guide](@id developer-guide) + +If you are planning significant changes, please open an [issue](https://github.com/JuliaFewBody/TwoBody.jl/issues) first. The [ColPrac](https://github.com/SciML/ColPrac) guidelines are recommended. For Julia package development basics, see: + +- [How to develop a Julia package](https://julialang.org/contribute/developing_package/) +- [Pkg: Creating packages](https://pkgdocs.julialang.org/v1/creating-packages/) + +## Local Setup + +This procedure is required only once. Install Git and Julia on your local machine before starting. + +1. Fork [the repository](https://github.com/JuliaFewBody/TwoBody.jl) on GitHub. +2. Clone the forked repository. Replace `xxxxxx` with your GitHub username. + + ```sh + git clone https://github.com/xxxxxx/TwoBody.jl.git + cd TwoBody.jl + ``` + +3. Install [Revise.jl](https://github.com/timholy/Revise.jl). + + ```sh + julia --startup-file=no -e 'import Pkg; Pkg.add("Revise")' + ``` + +## Development Flow + +This is the typical workflow for making changes. + +1. Create a branch for your changes. Replace `xxx` with the issue number, for example `issue/20`. + + ```sh + git switch -c issue/xxx + ``` + +2. Start an interactive session with [Revise.jl](https://github.com/timholy/Revise.jl). + + ```sh + julia --startup-file=no -i -e 'using Revise; import Pkg; Pkg.activate("."); using TwoBody' + ``` + +3. Change the source code. When adding functions or updating docstrings, refer to [Documenter: Adding docstrings](https://documenter.juliadocs.org/stable/man/guide/#Adding-Some-Docstrings). +4. If you need a new dependency, replace `SomePackage` with its package name and run: + + ```sh + julia --project=. --startup-file=no -e 'import Pkg; Pkg.add("SomePackage"); Pkg.resolve(); Pkg.instantiate()' + ``` + +5. Run the tests. They may take a few minutes. + + ```sh + julia --project=. --startup-file=no -e 'using Pkg; Pkg.test()' + ``` + +6. Build the documentation locally. HTML files are generated in `docs/build/`; open `docs/build/index.html` in a web browser to review them. + + ```sh + julia --project=docs --startup-file=no -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' + julia --project=docs --startup-file=no -e 'include("docs/make.jl")' + ``` + +7. After the tests and documentation build succeed, commit and push the changed files. + + ```sh + git add "path/to/changed/file" + git commit -m "commit message" + git push origin issue/xxx + ``` + +8. Submit a pull request on GitHub. + +## Adding New Operators and Solvers + +TwoBody.jl uses Julia's multiple dispatch to keep the physical problem separate from its numerical solution. + +### Operators + +1. Define the operator in `src/Hamiltonian.jl` as a subtype of `KineticTerm` or `PotentialTerm`. +2. Implement the solver-specific operations required to support it, such as `element`, `matrix`, or local-energy evaluation. +3. Add tests to the corresponding files under `test/`. +4. Add or update the mathematical definition and API documentation under `docs/src/`. + +An unsupported operator–solver combination should fail explicitly rather than silently choosing an approximation. + +### Solvers + +1. Create `src/MethodName.jl` and define the method type and its `solve(hamiltonian::Hamiltonian, method::MethodName; ...)` implementation. +2. Include the source file from `src/TwoBody.jl` after its dependencies. +3. Create `test/MethodName.jl` and include it from `test/runtests.jl`. +4. Create `docs/src/MethodName.md` and add it to the `pages` list in `docs/make.jl`. +5. Run the complete test suite and documentation build as described in [Development Flow](@ref). + +## Versioning and Registering (for Maintainers) + +This project follows [Semantic Versioning](https://semver.org/). When bumping the version, update `version` in [`Project.toml`](https://github.com/JuliaFewBody/TwoBody.jl/blob/main/Project.toml). + +To register a release in the [General](https://github.com/JuliaRegistries/General) registry, use [Registrator](https://github.com/JuliaRegistries/Registrator.jl#via-the-github-app) through its GitHub App workflow. + +## Architecture + +`src/TwoBody.jl` defines the `TwoBody` module and includes the source files in dependency order. `Hamiltonian.jl` defines the shared problem representation. `Basis.jl` supports the Rayleigh–Ritz implementation, and `FDM.jl` supplies the discretization used by the variational neural-network method. The solver files extend `solve` for their respective method types. + +```mermaid +--- +config: + layout: elk + theme: mc +--- +flowchart TD + H["Hamiltonian.jl"] + D["DB.jl"] + B["Basis.jl"] + R["Rayleigh-Ritz.jl"] + F["FDM.jl"] + Q["QTT.jl"] + N["VNN.jl"] + V["VMC.jl"] + T["TwoBody.jl"] + + H --> D + H --> R & F & Q & N & V + B --> R + F --> N + H & D & B & R & F & Q & N & V --> T +```