# digitaloctet/machine-composition architecture

> Architecture diagram of the GitHub repository digitaloctet/machine-composition, 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/digitaloctet/machine-composition
- Repository: https://github.com/digitaloctet/machine-composition

## Overview

##### Project Overview and Main Components
- Genetic Algorithm Engine: At its heart, the project contains a genetic algorithm implemented in genetic_algo.py. This script serves as the orchestrator of the entire process.
- Core Modules:
- Individual Module (individual.py): Defines the structure or “genome” representing a single musical composition candidate.
- Population Module (population.py): Manages groups of individuals and handles operations such as selection, crossover, and mutation.
- Fitness Module (fitness.py and fitness_test.py): Evaluates each individual’s quality based on specific musical criteria. The test file verifies the correctness of the fitness implementation.
- Configuration and Environment Setup:
- The environment.yml file is used to set up the necessary Python environment with dependencies (mido, numpy, scipy, matplotlib).
- Output Generation:
- The output directory contains subdirectories (output_random, output_rank, output_roulette, output_tournament), each storing MIDI (.mid) and audio (.wav) files resulting from the algorithm using different selection strategies.

##### Relationships and Interactions
- The genetic_algo.py script initiates the process by creating and managing a population.
- Each individual in the population (defined in individual.py) is evaluated using fitness.py.
- Based on fitness, genetic operations (like selection, crossover, and mutation) are applied — with different selection methods hinted by the various output folders (random, rank, roulette, tournament).
- The final outcome of the genetic process is translated into MIDI and WAV files and stored in the respective output subdirectories.
- Testing of fitness calculations is managed via fitness_test.py to ensure algorithmic correctness.

##### Architectural Patterns and Design Principles
- Modularity: The project clearly separates concerns into distinct modules (population, individual, fitness), which is a key to maintainability.
- Separation of Concerns: The orchestration of the algorithm is separate from the evaluation (fitness) and the data structure (individual/population).
- Configurability: The use of an environment file highlights the need for replicable and controlled dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization
    subgraph "Initialization"
        ENV["environment.yml"]:::env
    end

    %% Core Engine
    subgraph "Core Engine"
        GA["Genetic Algo Engine (genetic_algo.py)"]:::engine
        POP["Population Handler (population.py)"]:::module
        IND["Individual Representation (individual.py)"]:::module
        FIT["Fitness Evaluator (fitness.py)"]:::module
        TST["Testing Module (fitness_test.py)"]:::module
    end

    %% Output Generation
    subgraph "Output Generation"
        O_R["Random Strategy (MIDI/WAV)"]:::output
        O_Rank["Rank Strategy (MIDI/WAV)"]:::output
        O_Roulette["Roulette Strategy (MIDI/WAV)"]:::output
        O_Tour["Tournament Strategy (MIDI/WAV)"]:::output
    end

    %% Data Flow
    ENV -->|"setup_environment"| GA
    GA -->|"initialize_population"| POP
    POP -->|"create_individuals"| IND
    IND -->|"evaluate"| FIT
    GA -->|"orchestrate_evolution"| FIT
    FIT -->|"run_tests"| TST
    GA -->|"generate_output"| O_R
    GA -->|"generate_output"| O_Rank
    GA -->|"generate_output"| O_Roulette
    GA -->|"generate_output"| O_Tour

    %% Click Events
    click GA "https://github.com/digitaloctet/machine-composition/blob/main/code/genetic_algo.py"
    click POP "https://github.com/digitaloctet/machine-composition/blob/main/code/population.py"
    click IND "https://github.com/digitaloctet/machine-composition/blob/main/code/individual.py"
    click FIT "https://github.com/digitaloctet/machine-composition/blob/main/code/fitness.py"
    click TST "https://github.com/digitaloctet/machine-composition/blob/main/code/fitness_test.py"
    click ENV "https://github.com/digitaloctet/machine-composition/blob/main/code/environment.yml"
    click O_R "https://github.com/digitaloctet/machine-composition/tree/main/output/output_random"
    click O_Rank "https://github.com/digitaloctet/machine-composition/tree/main/output/output_rank"
    click O_Roulette "https://github.com/digitaloctet/machine-composition/tree/main/output/output_roulette"
    click O_Tour "https://github.com/digitaloctet/machine-composition/tree/main/output/output_tournament"

    %% Styles
    classDef env fill:#A7C7E7,stroke:#000,stroke-width:2px;
    classDef engine fill:#FFE699,stroke:#000,stroke-width:2px;
    classDef module fill:#C1E1C1,stroke:#000,stroke-width:2px;
    classDef output fill:#F9D5E5,stroke:#000,stroke-width:2px;
```
