📖 Glossary of Terms

Definitions of key concepts and terminology

Quick Reference: Cheatsheet | FAQ | Guide

Terminology Standards

Preferred Terms (as of v2.0):

Thin Orchestrator Pattern: Core architectural principle (capitalized when referring to the pattern name, lowercase in prose)
Two-Layer Architecture: Layer 1 (Infrastructure) and Layer 2 (Project)
Version: v2.0 (current system version)
Test Coverage: 90% minimum for project code, 60% minimum for infrastructure code
Build Pipeline: Orchestrated sequence from environment setup through copied deliverables. Core (execute_pipeline.py --project {name} --core-only): eight executor stages by default (clean, setup, infrastructure tests, project tests, analysis, PDF, validate, copy). Full adds optional LLM stages before copy. ./run.sh --pipeline logs main steps as [1/9]–[9/9] with an initial clean line as [0/9]. Stage scripts are scripts/00_*.py–scripts/05_*.py plus 06/07 for LLM and executive reporting where used.

A

AGENTS.md

technical documentation files found in each directory. Contains detailed information for developers and advanced users. Complemented by README.md files for quick reference.

See: Directory Documentation

Architecture Pattern

The overall system design that enforces separation of concerns between business logic (src/), tests, scripts, and documentation.

See: ../core/architecture.md | Thin Orchestrator Pattern

B

Branch Coverage

Testing metric ensuring all conditional branches (if/else, switch cases) are executed during tests. Required to be 100% for all src/ code.

See: Test Coverage

Build Pipeline

Automated sequence of operations that validates tests, runs scripts, generates documentation, and builds PDFs. Orchestrated by scripts/execute_pipeline.py (10-stage DAG pipeline).

Stages: Tests → Scripts → Validation → Glossary → Individual PDFs → Combined PDF

See: RUN_GUIDE.md

Business Logic

Core algorithms, mathematical functions, and computational methods. Must reside in src/ directory with test coverage. Scripts should never implement business logic.

See: Thin Orchestrator Pattern

C

Combined PDF

Single PDF document containing all manuscript sections in proper order. Generated from individual section PDFs by the build pipeline.

File: output/{name}/pdf/{name}_combined.pdf (top-level deliverable after copy outputs)

See: PDF Generation

Coverage Requirement

test coverage required: 90% minimum for project code, 60% minimum for infrastructure. Enforced by build pipeline before PDF generation.

Check: pytest tests/ --cov=src --cov-report=term-missing

See: Test Coverage

Cross-Reference

Internal link between document parts (sections, equations, figures, tables) using LaTeX \ref{} and \eqref{} commands.

Examples:

Section: \ref{sec:methodology}
Equation: \eqref{eq:objective}
Figure: \ref{fig:plot}

See: markdown-template-guide.md

D

Directory Documentation

Each major directory contains two documentation files:

AGENTS.md: technical reference
README.md: Quick reference and navigation

Directories: src/, tests/, scripts/, manuscript/, docs/

DOI (Digital Object Identifier)

Persistent identifier for academic publications. Optional configuration for the template.

Set: export DOI="10.5281/zenodo.12345678"

See: Project Metadata

E

Equation Environment

LaTeX structure for numbered mathematical equations with labels for cross-referencing.

Syntax:

\begin{equation}\label{eq:name}
f(x) = x^2
\end{equation}

Reference: \eqref{eq:name}

See: markdown-template-guide.md

F

Figure Generation

Process of creating visual outputs from data using scripts that follow the thin orchestrator pattern. Figures saved to output/figures/.

Pattern: Script imports from src/ → Uses tested methods → Handles visualization → Saves output

See: Thin Orchestrator Pattern

G

Glossary

Auto-generated API reference from src/ code. Updated automatically during build pipeline.

File: manuscript/98_symbols_glossary.md

Generation: uv run python infrastructure/documentation/generate_glossary_cli.py projects/code_project/src/ projects/code_project/manuscript/98_symbols_glossary.md (or your project’s paths; see docs/modules/modules-guide.md)

Guard Clause

Programming pattern that handles error conditions first, reducing nesting. Preferred style in this template.

Example:

def process(value):
    if value is None:  # Guard clause
        return default
    # Main logic here

H

Headless Plotting

Running matplotlib without display server using MPLBACKEND=Agg. Required for CI/CD and automated builds.

Set: export MPLBACKEND=Agg

I

Individual PDF

Single PDF file generated for each manuscript section. Allows focused review of specific sections.

Location: projects/{name}/output/pdf/*.pdf while building; after copy, output/{name}/pdf/*.pdf (see docs/RUN_GUIDE.md)

See: PDF Generation

Integration Test

Test that validates interaction between multiple components. Ensures scripts can import and use src/ methods correctly.

Example: Testing that figure generation scripts successfully import and use src/ functions

See: Testing

L

LaTeX Preamble

Document setup and styling configuration loaded before content. Defines packages, fonts, colors, and formatting.

File: manuscript/preamble.md

Location: projects/{name}/manuscript/preamble.md

M

Manifest

List of generated files collected during build pipeline. Used to verify all expected outputs were created.

Collected from: Script stdout when they print output paths

Manuscript

Research document composed of numbered sections in manuscript/ directory. Converted to PDFs during build.

Sections: 01-09 (main), S01-S99 (supplemental), 98 (glossary), 99 (references)

See: manuscript-numbering-system.md

Markdown Validation

Automated checking of markdown files for broken references, missing images, invalid links, and syntax errors.

Command: uv run python -m infrastructure.validation.cli markdown projects/{name}/manuscript/

See: markdown-template-guide.md

Mock Method

ABSOLUTELY PROHIBITED: Fake implementation of function for testing purposes. STRICTLY FORBIDDEN in this template - all tests must use data and real methods only.

Philosophy: Test actual behavior, not mocked behavior. Mocking undermines test reliability and integration validation.

See: Testing

O

Orchestrator

Script that coordinates operations by importing and using methods from src/. Should not contain business logic.

See: Thin Orchestrator Pattern

ORCID (Open Researcher and Contributor ID)

Unique persistent identifier for researchers. Optional configuration for the template.

Format: 0000-0001-2345-6789

Set: export AUTHOR_ORCID="0000-0001-2345-6789"

Output Directory

Location where all generated files are placed. All files are disposable and can be regenerated.

Location: output/

Subdirectories: pdf/, figures/, data/, tex/

P

Pandoc

Universal document converter used to transform markdown to LaTeX and PDF. Required system dependency.

Install: brew install pandoc (macOS) or apt-get install pandoc (Ubuntu)

See: Prerequisites

PDF Generation

Process of converting markdown sources to professional PDF documents using Pandoc and XeLaTeX.

Pipeline: Markdown → Pandoc → LaTeX → XeLaTeX → PDF

Time: ~84 seconds for rebuild (without optional LLM review)

See: RUN_GUIDE.md

PDF Validation

Automated checking of generated PDFs for rendering issues, unresolved references, and structural problems.

Command: uv run python scripts/04_validate_output.py or uv run python -m infrastructure.validation.cli pdf <path>

Checks: Unresolved references (??), missing citations, warnings, errors

See: pdf-validation.md

Prerequisites

Required system dependencies and software that must be installed before using the template.

System: pandoc, texlive-xetex, fonts Python: uv or pip, python 3.9+

See: getting-started.md | README.md

Project Metadata

Configuration information (author, title, DOI, etc.) applied to generated documents via environment variables.

Variables:

AUTHOR_NAME
AUTHOR_EMAIL
AUTHOR_ORCID
PROJECT_TITLE
DOI

See: Configuration System

R

Reference System

LaTeX-based cross-referencing that automatically numbers and links sections, equations, figures, and tables.

Types:

Sections: \ref{sec:name}
Equations: \eqref{eq:name}
Figures: \ref{fig:name}
Tables: \ref{tab:name}

See: Cross-Reference

Render Pipeline

Another name for Build Pipeline. The sequence from tests to final PDF.

Script: uv run python scripts/execute_pipeline.py --project {name} --core-only

Reproducibility

Ability to regenerate exact same results from source. Ensured through deterministic RNG seeds, fixed dependencies, and testing.

Tools: Version locking, seed fixing, environment capture

See: infrastructure/validation/integrity/checks.py

S

Script

Python file in scripts/ directory that orchestrates operations. Must follow thin orchestrator pattern.

Rules:

Import from src/
Use src/ methods for computation
Handle only I/O, visualization, orchestration
Print output paths

See: Thin Orchestrator Pattern

Section Label

Unique identifier for manuscript section used in cross-references.

Format: {#sec:section_name}

Example: # Introduction {#sec:introduction}

See: Cross-Reference

Source Code

Core business logic residing in src/ directory. Must have test coverage.

Requirements:

Type hints on public APIs
Docstrings on all functions
No circular imports
test coverage

See: infrastructure/AGENTS.md, code_project/src/AGENTS.md

Statement Coverage

Testing metric ensuring every line of code is executed during tests. Required to be 100% for all src/ code.

Check: Look for lines marked >>>>> in coverage report

See: Test Coverage

Supplemental Section

Additional manuscript content numbered S01-S99. Appears after main sections but before glossary.

Example: S01_supplemental_methods.md

See: manuscript-numbering-system.md

T

TDD (Test-Driven Development)

Development methodology where tests are written before implementation code.

Workflow: Write test → Run (fails) → Implement → Run (passes) → Refactor

See: ../core/workflow.md | ../core/how-to-use.md

Template Repository

GitHub repository type that can be used to create new repositories with same structure. This template is a template repository.

Use: Click "Use this template" button on GitHub

Test Coverage

Percentage of code executed during test runs. This template requires 90% minimum coverage for project code and 60% minimum for infrastructure.

Types:

Statement coverage (every line)
Branch coverage (every conditional)

Command: pytest tests/ --cov=src --cov-report=term-missing

See: Testing

Test Suite

Collection of all test files in tests/ directory. Ensures all functionality works correctly.

Status: Run uv run pytest tests/infra_tests/ projects/<name>/tests/ --collect-only to count tests on your checkout.

Run: uv run python scripts/01_run_tests.py --project <name> (or separate infra/project pytest invocations; see RUN_GUIDE.md)

See: tests/AGENTS.md

Testing

Process of validating code correctness through automated test cases. ABSOLUTE PROHIBITION: No mocks allowed - all tests must use data and computations only.

Requirements:

90% minimum for project code (currently 100% - coverage!)
60% minimum for infrastructure (currently 83.33% - exceeds stretch goal!)
data (no mocks)
Deterministic results
All tests must pass

Thin Orchestrator Pattern

Core architectural principle where scripts are lightweight wrappers that import and use src/ methods.

Principles:

ALL business logic in src/
Scripts only orchestrate
test coverage of src/
Clear separation of concerns

Benefits: Maintainability, testability, reusability, clarity

See: thin-orchestrator-summary.md

U

Unit Test

Test that validates a single function or method in isolation. Forms the foundation of the test suite.

Example:

def test_add_numbers():
    result = add_numbers(2, 3)
    assert result == 5

See: Testing

uv

Fast Python package manager used as default for this template. Alternative to pip.

Commands:

uv sync - Install dependencies
uv run pytest - Run tests

Install: pip install uv

V

Validation

Automated checking of various aspects: tests, markdown, PDFs, coverage, etc.

Types:

Test validation (pytest)
Markdown validation (validate_markdown.py)
PDF validation (scripts/04_validate_output.py)
Coverage validation (pyproject.toml [tool.coverage.*])

See: Build Pipeline

X

XeLaTeX

LaTeX engine that supports Unicode and modern fonts. Used for PDF generation.

Required: Part of texlive-xetex package

Install: brew install --cask mactex (macOS)

See: Prerequisites

Acronyms & Abbreviations

Term	Full Name	Description
API	Application Programming Interface	Public functions/methods in `src/`
CI/CD	Continuous Integration/Deployment	Automated build and test systems
CSV	Comma-Separated Values	Data file format
DOI	Digital Object Identifier	Persistent publication identifier
HTML	HyperText Markup Language	Web page format
I/O	Input/Output	Reading/writing files and data
LaTeX	(Lamport TeX)	Document preparation system
NPZ	NumPy Zipped	Compressed numpy array format
ORCID	Open Researcher and Contributor ID	Researcher identifier
PDF	Portable Document Format	Final output format
PNG	Portable Network Graphics	Image file format
RNG	Random Number Generator	Source of randomness
TDD	Test-Driven Development	Write tests before code
TOC	Table of Contents	Document navigation aid
UI	User Interface	Visual elements users interact with
UX	User Experience	Overall user interaction quality

FilesExpand file tree

glossary.md

Latest commit

History

glossary.md

File metadata and controls

📖 Glossary of Terms

Terminology Standards

A

AGENTS.md

Architecture Pattern

B

Branch Coverage

Build Pipeline

Business Logic

C

Combined PDF

Coverage Requirement

Cross-Reference

D

Directory Documentation

DOI (Digital Object Identifier)

E

Equation Environment

F

Figure Generation

G

Glossary

Guard Clause

H

Headless Plotting

I

Individual PDF

Integration Test

L

LaTeX Preamble

M

Manifest

Manuscript

Markdown Validation

Mock Method

O

Orchestrator

ORCID (Open Researcher and Contributor ID)

Output Directory

P

Pandoc

PDF Generation

PDF Validation

Prerequisites

Project Metadata

R

Reference System

Render Pipeline

Reproducibility

S

Script

Section Label

Source Code

Statement Coverage

Supplemental Section

T

TDD (Test-Driven Development)

Template Repository

Test Coverage

Test Suite

Testing

Thin Orchestrator Pattern

U

Unit Test

uv

V

Validation

X

XeLaTeX

Acronyms & Abbreviations

Related Documentation