# cosmolike/cocoa architecture

> Architecture diagram of the GitHub repository cosmolike/cocoa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cosmolike/cocoa
- Repository: https://github.com/cosmolike/cocoa

## Overview

##### Overall Project Type and Purpose
- The project is a full-stack, scientific computing environment tailored for cosmological analysis. It tightly integrates external Boltzmann codes (e.g., CAMB, CLASS), likelihood codes (Planck, ACT, SPT, etc.), and sampling routines (Cobaya/PolyChord) to simulate and analyze multi-probe cosmological data (from DES, LSST, Roman, etc.).
- The README emphasizes aspects like containerization and consistent compiler/library choices across machines, reflecting a need for robust reproducibility and HPC deployment.

##### Key Directories and Their Roles
- The top-level “Cocoa” directory houses the core environment and scripts:
– Installation and compilation scripts (e.g., setup_cocoa.sh, compile_cocoa.sh, start_cocoa.sh, stop_cocoa.sh) that set up the environment and build external modules.
– The “external_modules” folder is organized into subdirectories for code (e.g., CAMB, CLASS, cosmolike, various likelihood modules) and data (e.g., Planck, BAO, SPT), which are downloaded and compiled via installation scripts.
– The “projects” directory contains example YAML configuration files and project-specific scripts. This folder supports setting up concrete cosmological analyses with Cobaya-run commands.
- Additionally, there are installation libraries (e.g., cocoa_installation_libraries) with lecture notes and changes that support users and developers in understanding the lower-level code.

##### Main System Components
a. Environment & Containerization Layer (User Interface/Deployment)
– Conda Environment: Represent the use of cocoapy39.yml, cocoapy310.yml files for core package management.
– Docker Container (e.g., whovian-cocoa): Indicate that Cocoa can run within a dockerized environment for consistent setup across Linux, Windows, and macOS.
b. Core Scripts/Bootstrapper
– Setup and compilation scripts (setup_cocoa.sh, compile_cocoa.sh) that download and build external modules.
– Start/Stop scripts (start_cocoa.sh, stop_cocoa.sh) that manage the private Python/Cobaya environments.
c. External Modules & Libraries
– Modules under “external_modules/code” such as:
- Boltzmann codes (CAMB, CLASS)
- Likelihood codes (Planck’s PLC, SPT, ACT, etc.)
- Sampling and interfacing layers (cfastpt, cfftlog, cosmolike, log.c, spt_clik, etc.)
– Data directories under “external_modules/data” for cosmological datasets.
– “cocoa_installation_libraries” which contains patches, teaching notes, and library changes.
d. User Projects
– The “projects” folder (e.g., projects/example and lsst_y1) contains customized YAML configuration files and scripts for running evaluations, MCMCs, and profiling.
– Represents user-configured instances that use the core framework and the external modules.
e. Integration with Cobaya
– The overall system is a “wrapper” which integrates CosmoLike routines into the Cobaya sampler framework. There is a bidirectional relationship where Cocoa’s infrastructure prepares the necessary shared libraries, symbolic links, and environment variables so that Cobaya (and its “cobaya-run” command) can access likelihoods and data.

##### Relationships and Data/Control Flows
- The Cona/Docker layer encapsulates the full environment; within it, the startup scripts create a “private” workspace. From here:
– Setup scripts trigger the download, extraction, and compilation of the external modules.
– Compiled binaries and libraries are then linked (via softlink scripts from start_cocoa.sh) so Cobaya (the sampling engine) can locate and use them.
– User projects (YAML files) specify parameters and likelihood functions; these are fed to the Cobaya-run command (often wrapped in hybrid MPI+OpenMP commands).
– Feedback flows from sampling runs (MCMC chains, evaluations, profiling) back to the user who can observe outputs or fine-tune YAML configurations.
- Installation scripts and manual options control which modules or datasets are included. Environment flags (e.g., for debugging, ignoring certain datasets) impact the system’s compilation behavior.

##### Architectural Patterns and Technologies
- Modular architecture: Separation between core environment, external modules and user projects.
- Containerization and environment isolation: Ensures reproducibility (via conda environments and Docker).
- Use of multiple languages supported by language-specific compilation and linking (C, C++, Fortran, Python, Bash).
- Deployment on HPC: MPI and OpenMP settings and NUMA-aware scheduling (as seen in the mpirun flags) are important details.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Platform Environment"
        CE1["Conda Environment (cocoapy39)"]:::platform
        CE2["Conda Environment (cocoapy310)"]:::platform
        D["Docker Container (whovian-cocoa)"]:::platform
    end

    subgraph "Core Scripts/Bootstrapper"
        SC1["Setup Script (setup_cocoa.sh)"]:::scripts
        SC2["Compilation Script (compile_cocoa.sh)"]:::scripts
        AIS["Installation Scripts Directory"]:::scripts
        SS1["Start Script (start_cocoa.sh)"]:::scripts
        SS2["Stop Script (stop_cocoa.sh)"]:::scripts
    end

    subgraph "External Modules & Libraries"
        EC["External Code Modules"]:::modules
        ED["External Data"]:::modules
        IL["Installation Libraries"]:::modules
    end

    subgraph "Integration with Cobaya"
        CI["Cobaya Setup Script"]:::integration
        CC["Cobaya Changes"]:::integration
    end

    subgraph "User Projects"
        UP["User Projects & YAML Configurations"]:::projects
        EP["Example Project"]:::projects
    end

    %% Platform Environment to Core Scripts
    CE1 --> SC1
    CE2 --> SC1
    D   --> SC1

    %% Core Scripts internal flow
    SC1 --> SC2
    SC2 --> AIS
    AIS --> SS1
    AIS --> SS2

    %% Core Scripts to External Modules
    SC2 --> EC
    SC2 --> ED
    SC2 --> IL

    %% External Modules to Integration
    EC --> CI
    ED --> CI
    IL --> CC

    %% Integration to User Projects
    CI --> UP
    CC --> UP

    %% Within User Projects
    UP --> EP

    %% Feedback loop from User Projects to Integration
    UP -->|"feedback"| CI

    %% Click Events for Environment & Containerization Layer
    click CE1 "https://github.com/cosmolike/cocoa/blob/main/cocoapy39.yml"
    click CE2 "https://github.com/cosmolike/cocoa/blob/main/cocoapy310.yml"

    %% Click Events for Core Scripts/Bootstrapper
    click SC1 "https://github.com/cosmolike/cocoa/blob/main/Cocoa/setup_cocoa.sh"
    click SC2 "https://github.com/cosmolike/cocoa/blob/main/Cocoa/compile_cocoa.sh"
    click SS1 "https://github.com/cosmolike/cocoa/blob/main/Cocoa/start_cocoa.sh"
    click SS2 "https://github.com/cosmolike/cocoa/blob/main/Cocoa/stop_cocoa.sh"
    click AIS "https://github.com/cosmolike/cocoa/tree/main/Cocoa/installation_scripts/"

    %% Click Events for External Modules & Libraries
    click EC "https://github.com/cosmolike/cocoa/tree/main/Cocoa/external_modules/code/"
    click ED "https://github.com/cosmolike/cocoa/tree/main/Cocoa/external_modules/data/"
    click IL "https://github.com/cosmolike/cocoa/tree/main/cocoa_installation_libraries/"

    %% Click Events for Integration with Cobaya
    click CI "https://github.com/cosmolike/cocoa/blob/main/Cocoa/installation_scripts/setup_cobaya.sh"
    click CC "https://github.com/cosmolike/cocoa/tree/main/cocoa_installation_libraries/cobaya_changes/"

    %% Click Events for User Projects
    click UP "https://github.com/cosmolike/cocoa/tree/main/Cocoa/projects/"
    click EP "https://github.com/cosmolike/cocoa/tree/main/Cocoa/projects/example/"

    %% Styles
    classDef platform fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef scripts  fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef modules  fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef projects fill:#e6ccff,stroke:#333,stroke-width:2px;
```
