stan-dev / stan-dev/math

Add an ARCHITECTURE.md file

Open
#3,034 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
839
Forks
220
Avg merge
2d 4h
Merged PRs (30d)
14

Description

Description

@WardBrian brought up the idea of adding an ARCHITECTURE.md file to each of the Stan repos and I really like the idea. A long blog about these files can be found here but essentially it would be a markdown document that goes over each of the folders that exist in the repo, why they exist, and what is inside of them. It would also contain higher level documentation describing how the mechanics of the system work.

For Stan math that would be a file describing

  • Each of fwd/prim/rev along with their subfolders
  • An explanation of how they interconnect i.e. what happens when including only prim, rev, fwd, or all.
  • How we seperate each of these folders with the requires
  • An explainer on how our reverse and forward mode autodiff works, how the arena allocator and reverse pass callback scheme work
  • test folder structure, and overview of the CI setup
  • dependency overview
  • Threading structure

Can anyone else think of more things that should be included in the ARCHITECTURE.md file?

Current Version:

v4.8.1

Contributor guide

Open the contributing guide

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.

Research direction

Create ARCHITECTURE.md for the Stan Math repository. Start by surveying the fwd, prim, rev, requires, and test folder structures, then review the CI setup, dependencies, and threading structure. Done means the document explains their purposes and interconnections, including autodiff modes, arena allocation, reverse-pass callbacks, and the listed build and test concepts.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.