Skip to content

examples.md

Latest commit

 

History

History
304 lines (224 loc) · 8.53 KB

examples.md

File metadata and controls

304 lines (224 loc) · 8.53 KB
Raw

📋 Project Configuration Examples

Step-by-step guide for configuring the template into specific research projects

Quick Reference: Examples Showcase | Architecture | How To Use

This file shows examples of how to customize the template into specific research projects using each project's manuscript/config.yaml plus a small set of supported environment overrides. For related information, see examples-showcase.md, configuration.md, README.md, and ../core/architecture.md.

How Configuration Works

Project identity and metadata live in projects/{name}/manuscript/config.yaml. There is no automated renaming script and no .project_config / .env.template generation — you edit config.yaml directly (copy from config.yaml.example) and, optionally, override a few fields at runtime via environment variables.

The config loader (infrastructure/core/config/loader.py) reads config.yaml and exports exactly these values, which may also be supplied via environment variables:

  • PROJECT_TITLE
  • AUTHOR_NAME
  • AUTHOR_ORCID
  • AUTHOR_EMAIL
  • AUTHOR_DETAILS
  • DOI

Environment variables that are already set take precedence over config.yaml. Other identifiers (project directory name, package name in pyproject.toml) are set by how you create the project directory and edit pyproject.toml — not by any env var named PROJECT_NAME, PROJECT_CALLSIGN, or PROJECT_DESCRIPTION.

Example 1: Machine Learning Research Project

projects/{name}/manuscript/config.yaml:

paper:
  title: "Deep Learning Optimization"
  version: "1.0"

authors:
  - name: "Dr. Alex Chen"
    orcid: "0000-0001-2345-6789"
    email: "alex.chen@research.edu"
    affiliation: "Research University"
    corresponding: true

publication:
  doi: "10.5281/zenodo.98765432"

keywords:
  - "deep learning"
  - "optimization"

Example 2: Data Science Package

projects/{name}/manuscript/config.yaml:

paper:
  title: "Pandas Extension Toolkit"
  version: "0.1"

authors:
  - name: "Sarah Johnson"
    orcid: "0000-0002-3456-7890"
    email: "sarah.johnson@datascience.com"
    affiliation: "Data Science Lab"
    corresponding: true

# DOI omitted — not published yet

keywords:
  - "pandas"
  - "data manipulation"

Example 3: Academic Paper

projects/{name}/manuscript/config.yaml:

paper:
  title: "Quantum Computing Survey"
  version: "1.0"

authors:
  - name: "Prof. Michael Rodriguez"
    orcid: "0000-0003-4567-8901"
    email: "m.rodriguez@university.edu"
    affiliation: "University"
    corresponding: true

# DOI omitted until a real deposit assigns one

keywords:
  - "quantum computing"
  - "algorithms"

Project Structure

A configured project has this structure:

graph TB
    subgraph "Project"
        ROOT[project_name/]
        SRC[src<br/>Core business logic]
        TESTS[tests<br/>tests]
        SCRIPTS[scripts<br/>Thin orchestrators]
        MANUSCRIPT[manuscript<br/>Research manuscript]
        OUTPUT[output<br/>Generated files]
    end

    subgraph "Key Files"
        PYPROJECT[pyproject.toml<br/>Project config]
        CONFIG[manuscript/config.yaml<br/>Paper + author metadata]
        RENDER[root pipeline<br/>./run.sh pipeline]
    end

    ROOT --> SRC
    ROOT --> TESTS
    ROOT --> SCRIPTS
    ROOT --> MANUSCRIPT
    ROOT --> OUTPUT

    ROOT --> PYPROJECT
    MANUSCRIPT --> CONFIG
    ROOT --> RENDER

    classDef dir fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef file fill:#fff3e0,stroke:#e65100,stroke-width:2px

    class ROOT,SRC,TESTS,SCRIPTS,MANUSCRIPT,OUTPUT dir
    class PYPROJECT,CONFIG,RENDER file
Loading

Usage Workflow

1. Create the config

Option A: Edit config.yaml (recommended)

# Copy the example config
cp projects/{name}/manuscript/config.yaml.example projects/{name}/manuscript/config.yaml

# Edit with your information
vim projects/{name}/manuscript/config.yaml

Option B: Override fields via environment variables

export PROJECT_TITLE="Your Project Title"
export AUTHOR_NAME="Your Name"
export AUTHOR_ORCID="0000-0000-0000-0000"
export AUTHOR_EMAIL="your.email@example.com"
export DOI="10.5281/zenodo.12345678"  # Optional

2. Test the Build Process

# Pipeline automatically handles cleanup
uv run python scripts/runner/execute_pipeline.py --project {name} --core-only

3. Customize Further

Edit additional files as needed:

  • pyproject.toml — package name and dependencies
  • Manuscript files in manuscript/

Project Customization Examples

Adding Project-Specific Source Code

graph LR
    subgraph L2SRC["Layer 2 · projects · src · modules"]
        EXISTING[example.py<br/>Basic functions]
        NEW1[ml_optimizer.py<br/>ML algorithms]
        NEW2[data_processor.py<br/>Data utilities]
        NEW3[visualization.py<br/>Plotting tools]
    end

    subgraph SCRINT["Scripts Integration"]
        SCRIPT[ml_training.py]
        IMPORT["Import from projects/{name}/src/"]
        USE[Use ml_optimizer]
        USE2[Use data_processor]
        USE3[Use visualization]
    end

    EXISTING --> SCRIPT
    NEW1 --> SCRIPT
    NEW2 --> SCRIPT
    NEW3 --> SCRIPT

    SCRIPT --> IMPORT
    IMPORT --> USE
    IMPORT --> USE2
    IMPORT --> USE3

    classDef existing fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef new fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef script fill:#fff3e0,stroke:#e65100,stroke-width:2px

    class EXISTING existing
    class NEW1,NEW2,NEW3 new
    class SCRIPT,IMPORT,USE,USE2,USE3 script
Loading

Example: extending the tested optimizer

The public exemplar already provides a real optimization API in src/optimizer.py, with behavior tests in tests/test_optimizer.py. A thin script can configure and call that API without reimplementing the algorithm:

import numpy as np

from src.optimizer import gradient_descent, make_quadratic_problem


def main() -> None:
    objective, gradient = make_quadratic_problem(
        A=np.array([[2.0, 0.0], [0.0, 1.0]]),
        b=np.array([1.0, 1.0]),
    )
    result = gradient_descent(
        initial_point=np.array([4.0, -3.0]),
        objective_func=objective,
        gradient_func=gradient,
        step_size=0.1,
    )
    print(result.solution, result.termination_reason)


if __name__ == "__main__":
    main()

If the project needs a genuinely new optimizer, first add behavior tests that define convergence, invalid-input, and non-finite-state contracts; then implement it under src/, expose only the intended public API, and keep data loading, plotting, and file output in a thin script. Do not publish placeholder implementations or empty tests as evidence.

Tips for Successful Configuration

Project Naming

  • Use kebab-case for the package name in pyproject.toml (good for URLs and package names)
  • Keep the manuscript keywords concise but descriptive
  • Pick a clear, descriptive paper.title

Author Information

  • Omit publication.doi (or set DOI="") if the project isn't published yet
  • Use your actual ORCID if you have one
  • Choose an appropriate license for your use case

Validation Checklist

After configuring, ensure:

  • All tests pass with required coverage
  • Scripts can import from src/ modules
  • Markdown validation passes
  • PDF generation works
  • Project metadata is correct
  • License information is appropriate

Troubleshooting

Common Issues

  1. Script not found: Ensure you're in the repository root directory
  2. Build failures: Check that all dependencies are installed and read the selected project's output/logs/pipeline.log
  3. Markdown errors: Validate manuscript files after editing

Getting Help

  • Review the test output for specific error messages
  • Ensure all required dependencies are installed
  • Verify the thin orchestrator pattern is maintained

Summary

Per-project manuscript/config.yaml (plus the supported env overrides) configures the generic template into a project-specific deliverable while maintaining:

  • Thin orchestrator pattern - Scripts use projects/{name}/src/ methods
  • test coverage - All functionality validated
  • Automated build pipeline - PDF generation
  • Generic utilities - Reusable across projects
  • Clear architecture - Separation of concerns

For more examples and showcase projects, see examples-showcase.md.