poisson-poisson requests sampling

Author: GioeleB00

DEV_WORKFLOW_GUIDE.md

@@ -1,6 +1,6 @@
 # **Development Workflow & Architecture Guide**
 
-This document outlines the standardized development workflow, repository architecture, and branching strategy for this project. Adhering to these guidelines ensures consistency, maintainability, and a scalable development process.
+This document outlines the standardized development workflow, repository architecture, and branching strategy for the backend of the FastSim project. Adhering to these guidelines ensures consistency, maintainability, and a scalable development process.
 
 ## 1. Technology Stack
 
@@ -13,13 +13,7 @@ The project is built upon the following core technologies:
 -   **Caching**: Redis
 -   **Containerization**: Docker
 
-## 2. Architectural Overview: A Multi-Repo Strategy
-
-To promote scalability, team autonomy, and clear separation of concerns, this project adopts a **multi-repo architecture**. Each core component of the system resides in its own dedicated repository. This approach allows for independent development cycles, testing, and deployment.
-
-Our architecture is composed of three main repositories:
-
-### 2.1. Backend Service (`project-backend`)
+### 2.1. Backend Service (`FastSim-backend`)
 
 This repository contains all code related to the FastAPI backend service. Its primary responsibility is to handle business logic, interact with the database, and expose a RESTful API.
 
@@ -61,69 +55,6 @@ project-backend/
 *   To be testable in isolation.
 *   To produce a versioned Docker image (`backend:<tag>`) as its main artifact.
 
-### 2.2. Frontend Service (`project-frontend`)
-
-This repository contains all code for the React web application. Its responsibility is to provide the user interface and interact with the backend via its API.
-
-**Folder Structure:**
-```
-project-frontend/
-├── .github/
-│   └── workflows/
-│       └── main.yml           # CI: Tests and publishes the frontend Docker image
-├── public/                  # Static assets (index.html, favicon, etc.)
-├── src/                     # Application source code
-│   ├── api/                 # Functions for backend API calls
-│   ├── components/          # Reusable UI components
-│   ├── hooks/               # Custom React hooks
-│   ├── mocks/               # Service worker mocks for API (for isolated testing)
-│   ├── pages/               # Page components
-│   └── index.js             # React application entrypoint
-├── .env.example
-├── .gitignore
-├── docker-compose.yml       # Base local development definition
-├── Dockerfile               # Multi-stage build for a lean production image
-├── package.json
-├── package-lock.json
-└── README.md                # Setup instructions for the frontend service
-```
-
-**Key Responsibilities:**
-*   To be testable in isolation (using a mocked API).
-*   To produce a versioned, production-ready Docker image (`frontend:<tag>`), typically served by Nginx.
-
-### 2.3. Infrastructure & E2E Tests (`project-master`)
-
-This repository is the "glue" that holds the system together. It does not contain application code but rather the configuration to orchestrate, test, and deploy the entire system.
-
-**Folder Structure:**
-```
-project-master/
-├── .github/
-│   └── workflows/
-│       ├── e2e-tests.yml      # CI: Runs End-to-End tests on a complete stack
-│       └── deploy.yml         # CD: Handles deployment to environments
-├── e2e-tests/                 # End-to-End test suite (e.g., Cypress, Playwright)
-│   ├── cypress/               # Test code
-│   └── cypress.config.js
-├── environments/              # Environment-specific configurations
-│   ├── staging/
-│   │   ├── docker-compose.yml # Docker Compose file for the Staging environment
-│   │   └── .env.example
-│   └── production/
-│       ├── docker-compose.yml # Docker Compose file for the Production environment
-│       └── .env.example
-├── scripts/                   # Deployment and utility scripts
-│   ├── deploy-staging.sh
-│   └── deploy-prod.sh
-└── README.md                  # Main project README: explains the overall architecture
-```
-
-**Key Responsibilities:**
-*   To define the composition of services for each environment (Staging, Production).
-*   To run End-to-End tests that validate the integration between services.
-*   To manage the Continuous Deployment (CD) process.
-
 ## 3. Branching Strategy: Git Flow
 
 To manage code development and releases in a structured manner, we use the **Git Flow** branching model.

docker_fs/.env.dev

@@ -1,9 +1,9 @@
 DB_HOST=db      
 DB_PORT=5432
-DB_NAME=project_backend_dev
-DB_USER=dev_user
-DB_PASSWORD=dev_pass
-DB_URL=postgresql+asyncpg://dev_user:dev_pass@db:5432/project_backend_dev
+DB_NAME=FastSim_dev
+DB_USER=FastSim_dev_user
+DB_PASSWORD=FastSim_dev_pass
+DB_URL=postgresql+asyncpg://FastSim_dev_user:dev_pass@db:5432/FastSim_dev
 
 PGADMIN_DEFAULT_EMAIL=[email protected]
 PGADMIN_DEFAULT_PASSWORD=secret

poetry.lock

@@ -20,6 +20,8 @@ pydantic-settings = "^2.10.1"
 pydantic = {extras = ["email"], version = "^2.11.7"}
 asyncpg = "^0.30.0"
 sqlalchemy-utils = "^0.41.2"
+numpy = "^2.3.1"
+simpy = "^4.1.1"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.4.1"

pyproject.toml

@@ -0,0 +1,118 @@
+"""
+Continuous-time event sampling for the Poisson-Poisson
+and Gaussian-Poisson workload model.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Iterator, Optional
+
+import numpy as np
+from app.schemas.simulation_input import SimulationInput
+
+MIN_TO_SEC_CONVERSION = 60  # 1 minute → 60 s
+
+def uniform_variable_generator(rng: Optional[np.random.Generator] = None) -> float:
+    """Return U~Uniform(0, 1)."""
+    rng = rng or np.random.default_rng()
+    return float(rng.random())
+
+
+def poisson_variable_generator(
+    mean: float,
+    rng: Optional[np.random.Generator] = None,
+) -> int:
+    """Return a Poisson-distributed integer with expectation *mean*."""
+    rng = rng or np.random.default_rng()
+    return int(rng.poisson(mean))
+
+
+def poisson_poisson_sampling(
+    input_data: SimulationInput,
+    *,
+    simulation_time_second: int = 3_600,
+    sampling_window_s: int = MIN_TO_SEC_CONVERSION,
+    rng: Optional[np.random.Generator] = None,
+) -> Iterator[float]:
+    """
+    Yield inter-arrival gaps (seconds) for the compound Poisson–Poisson process.
+
+    Algorithm
+    ---------
+    1. Every *sampling_window_s* seconds, draw
+         U ~ Poisson(mean_concurrent_user).
+    2. Compute the aggregate rate
+         Λ = U * (mean_req_per_minute_per_user / 60)  [req/s].
+    3. While inside the current window, draw gaps
+         Δt ~ Exponential(Λ)   using inverse-CDF.
+    4. Stop once the virtual clock exceeds *simulation_time_second*.
+    """
+    rng = rng or np.random.default_rng()
+
+    # λ_u : mean concurrent users per window
+    mean_concurrent_user = float(input_data.avg_active_users.mean)
+
+    # λ_r / 60 : mean req/s per user
+    mean_req_per_sec_per_user = (
+        float(input_data.avg_request_per_minute_per_user.mean) / MIN_TO_SEC_CONVERSION
+    )
+
+    now = 0.0                 # virtual clock (s)
+    window_end = 0.0          # end of the current user window
+    lam = 0.0                 # aggregate rate Λ (req/s)
+
+    while now < simulation_time_second:
+        # (Re)sample U at the start of each window
+        if now >= window_end:
+            window_end = now + float(sampling_window_s)
+            users = poisson_variable_generator(mean_concurrent_user, rng)
+            lam = users * mean_req_per_sec_per_user
+
+        # No users → fast-forward to next window
+        if lam <= 0.0:
+            now = window_end
+            continue
+
+        # Exponential gap from a protected uniform value
+        u_raw = max(uniform_variable_generator(rng), 1e-15)
+        delta_t = -math.log(1.0 - u_raw) / lam
+
+        # End simulation if the next event exceeds the horizon
+        if now + delta_t > simulation_time_second:
+            break
+
+        # If the gap crosses the window boundary, jump to it
+        if now + delta_t >= window_end:
+            now = window_end
+            continue
+
+        now += delta_t
+        yield delta_t
+
+
+def request_generator(
+    input_data: SimulationInput,
+    *,
+    simulation_time: int = 3_600,
+    rng: Optional[np.random.Generator] = None,
+) -> Iterator[float]:
+    """
+    Select and return the appropriate inter-arrival generator.
+
+    Currently implemented:
+      • Poisson + Poisson (default)
+    Gaussian + Poisson will be added later.
+    """
+    dist = input_data.avg_active_users.distribution.lower()
+
+    if dist in {"gaussian", "normal"}:
+        # TODO: implement gaussian_poisson_sampling(...)
+        raise NotImplementedError("Gaussian–Poisson sampling not yet implemented")
+
+    # Default → Poisson + Poisson
+    return poisson_poisson_sampling(
+        input_data=input_data,
+        simulation_time_second=simulation_time,
+        rng=rng,
+    )

src/app/core/requests_generator.py

@@ -8,7 +8,7 @@
 class RVConfig(BaseModel):
     """class to configure random variables"""
 
-    mean: int | float
+    mean: float
     distribution: Literal["poisson", "normal"] = "poisson"
     variance: float | None = None
 
@@ -19,7 +19,7 @@ def check_mean_is_number(
         ) -> float:
         """Ensure `mean` is numeric, then coerce to float."""
         err_msg = "mean must be a number (int or float)"
-        if not isinstance(v, (int, float)):
+        if not isinstance(v, float):
             raise ValueError(err_msg)  # noqa: TRY004
         return float(v)