# baptistedfr/predicting-oil-price-turning-points architecture

> Architecture diagram of the GitHub repository baptistedfr/predicting-oil-price-turning-points, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baptistedfr/predicting-oil-price-turning-points
- Repository: https://github.com/baptistedfr/predicting-oil-price-turning-points

## Overview

##### Overall Project Purpose & Type
- This project replicates research focused on using log‐periodic power law models and a variety of optimization algorithms (including multi-population genetic algorithms, particle swarm, simulated annealing, etc.) to predict turning points in oil prices.
- It is an algorithmic research framework that processes historical price data (as shown by the CSV files in the data directory), applies models (the LPPL and LPPLS models in the GQLib/Models directory), and uses various optimizers (in the GQLib/Optimizers directory) to generate prediction outputs and compare the performance of the algorithms.

##### Main Architectural Components
a. Data and Configuration Layer:
- Data input: CSV files located in the “data” directory for different markets (e.g., BTC, EURUSD, SSE, USO, WTI, SP500).
- Parameter configuration files in the “params” directory, which include JSON files (config_asset_classes.json, params_fa.json, params_mpga.json, etc.) defining algorithm parameters and settings.

b. Core Computation & Modeling Layer (GQLib):
- GQLib/Framework.py – likely orchestrates the prediction process and integrates different modules.
- GQLib/AssetProcessor.py – handles asset (price) data processing.
- GQLib/LombAnalysis.py – performs analysis tasks, perhaps related to time-series or spectral methods.
- GQLib/Models (LPPL.py, LPPLS.py) – contain implementations of the LPPL models used for prediction.
- GQLib/Optimizers – a collection of various optimization implementations (FA, MPGA, NELDER_MEAD, PSO, SA, SGA, TABU) plus an abstract optimizer to standardize interface across algorithms.
- The file “GQLib/enums.py” might be used to define enumerable constants to govern workflow or parameter settings.
- “GQLib/njitFunc.py” suggests the use of just-in-time (JIT) compilation (likely via Numba) for performance-critical functions.

c. Execution and Experimentation:
- The executable scripts “strat.py”, “test.py”, and the “Etude_USO_WTI.ipynb” notebook indicate that the project can be run both as a script-based analysis and an interactive exploratory workflow.
- The “Results” and “Results_strategy” directories store outputs of experiments with different optimization algorithms, and for different asset classes over various time intervals (daily/weekly). The JSON files stored therein represent the outcome of the prediction experiments.

d. Documentation:
- Documentation and research material are in the “Docs” folder and include the original research paper, final paper, and presentation slides.

##### Relationships and Data Flow
- Data flows from the Data and Params directories into the processing layer. Data is read (likely via AssetProcessor.py) and then fed into the Framework (GQLib/Framework.py) that coordinates which model (from GQLib/Models) and which optimizer (from GQLib/Optimizers) to use.
- The optimization algorithms compute the prediction models (using functions, including accelerated routines from njitFunc.py) and then generate result JSON files in the Results directory.
- Strat.py may combine model predictions into trading strategies, and test.py is used for validating components.

##### Architectural Patterns/Design Principles
- Modular design: Separating models, optimizers, and core simulation module (Framework) for maintainability and extensibility.
- Separation of concerns: Data management, computation logic, optimization strategies, and result storage are in distinct directories.
- Reusability and pluggability: Abstract interfaces (e.g., abstract_optimizer.py) suggest the addition of more algorithms without major changes to the core framework.
- Performance optimization: Use of JIT-compilation (njitFunc.py) to accelerate heavy computations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Configuration Layer
    subgraph "Data & Config"
        DataCSV["CSV Data (data)"]:::data
        Params["Parameter Config (params)"]:::config
    end

    %% Core Processing & Modeling Layer
    subgraph "Core Processing"
        AssetProcessor["AssetProcessor (GQLib/AssetProcessor.py)"]:::core
        Framework["Framework (GQLib/Framework.py)"]:::core
        LombAnalysis["LombAnalysis (GQLib/LombAnalysis.py)"]:::core
        subgraph "Models"
            LPPL["LPPL Model (GQLib/Models/LPPL.py)"]:::core
            LPPLS["LPPLS Model (GQLib/Models/LPPLS.py)"]:::core
        end
        Optimizers["Optimizers (GQLib/Optimizers)"]:::core
        JIT["JIT Functions (GQLib/njitFunc.py)"]:::core
        Enums["Enumerations (GQLib/enums.py)"]:::core
    end

    %% Execution Layer
    subgraph "Execution"
        Strat["strat.py"]:::exec
        Test["test.py"]:::exec
        Notebook["Etude_USO_WTI.ipynb"]:::exec
    end

    %% Output Layer
    subgraph "Output"
        Results["Results Output (Results)"]:::output
        ResultsStrategy["Strategy Results (Results_strategy)"]:::output
    end

    %% Documentation Layer
    subgraph "Documentation"
        Docs["Documentation (Docs)"]:::docs
    end

    %% Data Flow Connections
    DataCSV -->|"reads"| AssetProcessor
    Params -->|"configures"| AssetProcessor
    AssetProcessor -->|"orchestrates"| Framework
    Framework -->|"calls"| LPPL
    Framework -->|"calls"| LPPLS
    Framework -->|"selects"| Optimizers
    Framework -->|"analyzes"| LombAnalysis
    Optimizers -->|"accelerates via"| JIT
    Framework -->|"outputs"| Results
    Framework -->|"outputs"| ResultsStrategy
    Strat -->|"triggers"| Framework
    Test -->|"triggers"| Framework
    Notebook -->|"triggers"| Framework

    %% Click Events
    click DataCSV "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/data"
    click Params "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/params"
    click AssetProcessor "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/AssetProcessor.py"
    click Framework "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/Framework.py"
    click LombAnalysis "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/LombAnalysis.py"
    click LPPL "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/Models/LPPL.py"
    click LPPLS "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/Models/LPPLS.py"
    click Optimizers "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/GQLib/Optimizers"
    click JIT "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/njitFunc.py"
    click Enums "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/GQLib/enums.py"
    click Strat "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/strat.py"
    click Test "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/test.py"
    click Notebook "https://github.com/baptistedfr/predicting-oil-price-turning-points/blob/main/Etude_USO_WTI.ipynb"
    click Results "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/Results"
    click ResultsStrategy "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/Results_strategy"
    click Docs "https://github.com/baptistedfr/predicting-oil-price-turning-points/tree/main/Docs"

    %% Styles
    classDef data fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef config fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef exec fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef output fill:#d5f5e3,stroke:#229954,stroke-width:2px;
    classDef docs fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
```
