Developer Guide

If you are planning significant changes, please open an issue first. The ColPrac guidelines are recommended. For Julia package development basics, see:

Local Setup

This procedure is required only once. Install Git and Julia on your local machine before starting.

Fork the repository on GitHub.
Clone the forked repository. Replace xxxxxx with your GitHub username.
```
git clone https://github.com/xxxxxx/Antique.jl.git
cd Antique.jl
```

Install Revise.jl.

julia --startup-file=no -e 'import Pkg; Pkg.add("Revise")'

Development Flow

This is the typical workflow for making changes.

Create a branch for your changes. Replace xxx with the issue number (e.g. issue/123).
```
git switch -c issue/xxx
```

Start an interactive session with Revise.jl.

julia --startup-file=no -i -e 'using Revise; import Pkg; Pkg.activate("."); using Antique'

Change the source code. When making new functions or updating docstrings, refer to Documenter: Adding docstrings.
If you need a new dependency, use julia --project=. --startup-file=no -e 'import Pkg; Pkg.add("SomePackage"); Pkg.resolve(); Pkg.instantiate()'. Replace SomePackage with the actual package name.

Run the tests. It will take a few minutes.

julia --project=. --startup-file=no -e 'using Pkg; Pkg.test()'

Build the documentation locally. HTML files (docs/build/*.html) will be generated. Please check them with Chrome or any other web browsers.

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")'

Commit and Push the codes (after steps 3–6 succeed).

git add "path/to/changed/file"
git commit -m "commit message"
git push origin issue/xxx

Submit a pull request on GitHub.

Adding New Models

This is the guideline for adding new models. Adding a new model may take from a few days to a few weeks due to reference search, test implementation, and writing documentation.

First, please submit a new issue or comment here. I will assign you to the issue. We need to find orthodox references (textbooks or papers, not Wikipedia) for the analytical solutions (eigenvalues and eigenfunctions) before the development. This will take more time than you think.
Finish Local Setup and follow Development Flow.
Please create 3 files:
1. src/ModelName.jl — Write the source code and docstrings in this file. The most helpful examples are the harmonic oscillator for one-dimensional systems and the hydrogen atom for three-dimensional systems. We recommend that you copy these files. First create a structure struct ModelName with the same name as the model name (The best way is Find & Replace). Because the function names conflict, you must always give the struct ModelName as the first argument to potential, energy, wavefunction and other functions. Multi-dispatch avoids conflicts. We recommend using Revise.jl while coding (Development Flow).
2. test/ModelName.jl — Write test code in this file. At a minimum, please check the normalization and the orthogonality of the eigenfunctions using QuadGK.jl. Please also do tests for the eigenvalues (for example, calculate the expectation values of the Hamiltonian (energy) using the eigenfunctions and check that these values match the eigenvalues).
3. docs/src/ModelName.md — Write documentation in this file. Include at least the definition of the Hamiltonian and the analytical solutions (eigenvalues and eigenfunctions). Call a docstring in the source code (src/ModelName.jl).
Please rewrite 3 files:
1. src/Antique.jl — Add export ModelName, add :ModelName to models = [...], add include("./ModelName.jl"), and add using .ModelNames: ModelName.
2. docs/make.jl — Add the new model into pages=[...] in this file.
3. docs/src/index.md — Add the new model to the list of supported models.
As described in Development Flow, please complete the following steps: run the tests, build and review the documentation, commit, push, and submit a pull request.

Versioning and Registering (for Maintainers)

This project follows Semantic Versioning. When bumping the version, update the version number in:

To register this package in the General registry, install Registrator and use it via the GitHub App.