Documentation: parameter conventions that are easy to get wrong

Open
  • Is something wrong?
#300 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
44/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
cpp
Domain
documentation

Research direction

Start by locating the application and model-library documentation for spinmc, spin, spinmc_evaluate, fulldiag_evaluate, qwl_evaluate, and sparsediag; the issue does not name specific files. Check each stated convention against the relevant documentation, then add explanations for the coupling signs and bond types, observable definitions, per-site quantities, error bars, and degeneracy reporting. Done when the documented behavior covers all six examples and makes the stated caveats clear.

Written by the indexing model from the issue text.

Description

documentation

Each of the following produced a plausible-looking but wrong calculation
before the convention was found by comparing with an exact result. None is a
code defect; all deserve a sentence in the application or model-library
documentation.

  • spinmc reads J>0 as ferromagnetic (H = -J sum s_i s_j), while the
    quantum spin model reads J>0 as antiferromagnetic (H = +J sum S_i.S_j).
  • spinmc_evaluate names: "Binder Cumulant" is the moment ratio
    <m^4>/<m^2>^2 (not 1 - <m^4>/3<m^2>^2), "Binder Cumulant U2" is
    <m^2>/<|m|>^2, "Susceptibility" is beta N <m^2>, "Connected
    Susceptibility" is beta N (<m^2> - <|m|>^2).
  • In the spin model J sets Jz and Jxy together; an Ising coupling
    needs Jxy=0 explicitly.
  • Lattices whose unit cell declares several bond types take J0, J1,
    J2: honeycomb lattice has types 0, 1, 2 for its three bond
    directions and ladder has legs 0 and rungs 1. A bare J sets only type
    0; the honeycomb cluster with J=1 is six isolated dimers (E/N = -3/8
    exactly). Documenting the typing, or giving the honeycomb a single default
    type, would prevent this.
  • fulldiag_evaluate and qwl_evaluate report per-site quantities under
    "Energy Density", "Specific Heat per Site", "Uniform Susceptibility per
    Site"; qwl_evaluate writes no error bars, and a single Wang-Landau pass
    with the default 16 refinement steps scatters by 10-20 % in E(T) between
    seeds.
  • sparsediag (Lanczos without reorthogonalisation) reports a degenerate
    pair as a single level; a degeneracy count needs fulldiag.

Observed on master at 0e2f2915d (Release build, GCC, OpenBLAS, HDF5 1.14, single-threaded), compared with independent reference calculations.

Dominant language
C++
Stars
32
Forks
10
Avg merge
4d 6h
Merged PRs (30d)
51

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ALPSim/ALPS

All issues in ALPSim/ALPS

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.